Tutorial: Validate a user

The Validate product is available as a Beta version.

This tutorial walks through how to access the account information in the UK with the Modelo Sandbox.

Get Institutions

1. Get Institutions

Optional - This step is optional as it is entirely possible to access account data without retrieving the Institution list, however it is often required to display a list of supported banks for your customer to choose which bank they would like to share their data from.

Note: All requests made to the Yapily API require basic authentication.

To display this list, use GET Institutions:

Request:

Copy
Copied
curl -L -X GET 'https://api.yapily.com/institutions' \
  -u 'APPLICATION_KEY:APPLICATION_SECRET'

Response:

Copy
Copied
  "meta": {
    "tracingId": "acbb76db4ab8f4ac7f039d000456c13f",
    "count": 1
  },
  "data": [
    {
      "id": "modelo-sandbox",
      "name": "Modelo Sandbox",
      "fullName": "Modelo Sandbox",
      "countries": [
        {
          "displayName": "United Kingdom",
          "countryCode2": "GB"
        }
      ],
      "environmentType": "SANDBOX",
      "credentialsType": "OPEN_BANKING_UK_AUTO",
      "media": [
        {
          "source": "https://images.yapily.com/image/ce2bfdbf-1ae2-4919-ab7b-e8b3d5e93b36?size=0",
          "type": "icon"
        },
        {
          "source": "https://images.yapily.com/image/ca502f24-d6df-4785-b4b8-1034b100af77?size=0",
          "type": "logo"
        }
      ],
      "features": [
        "INITIATE_ACCOUNT_REQUEST",
        "ACCOUNT_REQUEST_DETAILS",
        "EXISTING_PAYMENTS_DETAILS",
        "ACCOUNT_BALANCES",
        "CREATE_BULK_PAYMENT",
        "ACCOUNT_PERIODIC_PAYMENTS",
        "ACCOUNT_STATEMENTS",
        "INITIATE_BULK_PAYMENT",
        "ACCOUNT_STATEMENT",
        "ACCOUNT",
        "INITIATE_DOMESTIC_PERIODIC_PAYMENT",
        "INITIATE_SINGLE_PAYMENT_SORTCODE",
        "ACCOUNT_DIRECT_DEBITS",
        "ACCOUNTS",
        "ACCOUNT_TRANSACTIONS",
        "EXISTING_PAYMENT_INITIATION_DETAILS",
        "CREATE_DOMESTIC_SINGLE_PAYMENT",
        "INITIATE_DOMESTIC_SINGLE_PAYMENT",
        "ACCOUNT_STATEMENT_FILE",
        "CREATE_INTERNATIONAL_SINGLE_PAYMENT",
        "IDENTITY",
        "CREATE_DOMESTIC_SCHEDULED_PAYMENT",
        "INITIATE_DOMESTIC_SCHEDULED_PAYMENT",
        "CREATE_SINGLE_PAYMENT_SORTCODE",
        "ACCOUNT_TRANSACTIONS_WITH_MERCHANT",
        "INITIATE_INTERNATIONAL_SINGLE_PAYMENT",
        "PERIODIC_PAYMENT_FREQUENCY_EXTENDED",
        "ACCOUNT_SCHEDULED_PAYMENTS",
        "CREATE_DOMESTIC_PERIODIC_PAYMENT"
      ]
    }
  ]
}
  • Each Institution returned contains a logo, name, id and a list of supported features. As we want to retrieve account information and transactions, the institution needs to support the ACCOUNTS and ACCOUNT_TRANSACTIONS features.
  • In your app, you should ask the user to select the bank they wish to share their account data from.
  • Once selected, the Institution id should be passed in the next step.

2. Authorisation

AIS Authorisation

After obtaining the institution-id and confirming that the bank supports the ability access accounts information and transactions, the next step is to generate an authorisation-url that is used to redirect the user to their chosen bank and to authorise the account request.

When building your live application, Yapily recommends that the authorisationUrl is surfaced to the user on a page in your application where an overview of the request is displayed to the user before sending them directly to the bank to approve the request to share their account information. This is to help to reduce the the likeliness of unauthorised requests by providing all the key information to the user upfront. The authorisationUrl can be set as the link in a button that will "Confirm" that the user agrees with the overview.

To do this, execute Create Account Authorisation:

Request:

Copy
Copied
curl -L -X POST 'https://api.yapily.com/account-auth-requests' \
 -H 'Content-Type: application/json' \
 -u 'APPLICATION_KEY:APPLICATION_SECRET' \
 -d '{
   "applicationUserId": "account-data-and-transactions-tutorial",
   "institutionId": "modelo-sandbox",
   "callback": "https://display-parameters.com/"
 }'

Response:

Copy
Copied
{
  "meta": {
    "tracingId": "ceab45e96f852afdb59ec8eaf8f93594"
  },
  "data": {
    "id": "979f8a58-c955-46b5-b25d-bdc447c28a80",
    "userUuid": "c78035e1-3140-44f7-9539-527785069356",
    "applicationUserId": "account-data-and-transactions-tutorial",
    "institutionId": "modelo-sandbox",
    "status": "AWAITING_AUTHORIZATION",
    "createdAt": "2021-03-04T11:05:17.234Z",
    "featureScope": [
      "ACCOUNT_STATEMENT_FILE",
      "ACCOUNT_STATEMENTS",
      "ACCOUNT_BALANCES",
      "ACCOUNT_SCHEDULED_PAYMENTS",
      "ACCOUNT_STATEMENT",
      "ACCOUNT_TRANSACTIONS_WITH_MERCHANT",
      "ACCOUNT_TRANSACTIONS",
      "ACCOUNT_DIRECT_DEBITS",
      "IDENTITY",
      "ACCOUNT",
      "ACCOUNTS",
      "ACCOUNT_PERIODIC_PAYMENTS"
    ],
    "state": "e539228113de43b3a3d4c3b9944620d3",
    "institutionConsentId": "aac-74e55df8-a673-48b4-b8ae-3e8d0e45080f",
    "authorisationUrl": "{authorisationUrl}",
    "qrCodeUrl": "https://images.yapily.com/image/d4113d96-9d6c-4e69-a840-2e327cff1b1d/1614855917?size=0"
  }
}

AIS Bank

  • The AccountAuthorisationResponse returned includes the authorisationUrl that you should redirect the user to.
  • Note that the featureScope object defines every feature that you will be able to access for each account the user authorises using the consentToken that will be issued once they authorise the request.
  • The user will be asked to login and authorise the account sharing request in their bank. For this tutorial we use the sandbox credentials : mits / mits .
  • Access to the user's account information and all other features that the Consent was created for will be for a maximum of 90 days by default before requiring re-authorisation from the user, however, there are several cases where the length of time that the user's data can be accessed may vary. See the further reading links below to find out more.
  • Upon completion the user will be redirected back to the callback url supplied in the request. In our example we are using https://display-parameters.com/ , which will display the parameters returned with the redirect. The most important of which is the consentToken , which is used in the next steps to access the accounts information and transactions.

3. Get the Accounts

Once the user authorises the account request and you have the consentToken, you are able to access the account information that the user has consented to share.

To do this, execute Get Accounts:

Request:

Copy
Copied
curl -L --X GET 'https://api.yapily.com/accounts' \
  -H 'Consent: {consentToken}' \
  -u 'APPLICATION_KEY:APPLICATION_SECRET'

Response:

Copy
Copied
{
  "meta": {
    "tracingId": "14df65068fd38689b392ad39602143cb",
    "count": 1
  },
  "data": [
    {
      "id": "700004000000000000000007",
      "type": "Personal - Current",
      "balance": -99765867307.74,
      "currency": "GBP",
      "usageType": "PERSONAL",
      "accountType": "CURRENT",
      "nickname": "xxxx0009",
      "accountNames": [
        {
          "name": "Mr. Mitsuhirato"
        }
      ],
      "accountIdentifications": [
        {
          "type": "PAN",
          "identification": "1234000000000001"
        }
      ],
      "accountBalances": [
        {
          "type": "EXPECTED",
          "dateTime": "2021-03-04T11:08:39.291Z",
          "balanceAmount": {
            "amount": -99765867307.74,
            "currency": "GBP"
          },
          "creditLineIncluded": false,
          "creditLines": []
        }
      ]
    }
  ]
}

AIS Get Accounts

  • The response contains an array of Account objects for each account the user gave their consent to at the bank.
  • Yapily normalises the response for every Institution to ensure that the data that is provided from the customer's account can be handled in the same way.
  • The id refers to the account id

Congratulations! You've just pulled account information via Yapily.

Related Tutorials