Tutorial: Validate a user

The Validate product is available as a Beta version.

Introduction

This tutorial explains how to access account information in the UK with the Modelo Sandbox in order to validate a user's identity.

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

1. Select bank

To find which banks support accessing account information use GET institutions to retrieve the list of your supported 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"
      ]
    }
  ]
}

Filter the list for all institutions that support the ACCOUNTS feature. Then display these institutions in your application so the user can select which bank to share their account information from.

Once the user selects a bank, store the id of the institution to use in step 2.

2. Authorise

note

This example uses a single redirect flow using a callback URL.

Execute create account authorisation, including the institution ID and your callback URL.

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"
  }
}

Redirect the user to the authorisationUrl returned in the response.

The user is then asked to login and authorise the account sharing request with their bank. The Modelo sandbox credentials are: mits / mits.

Upon completion, the user is redirected back to the callback URL supplied in the request. In this example, the callback is https://display-parameters.com/ which displays the parameters returned with the redirect.

Store the consentToken to use when accessing account information in step 3. The featureScope array defines the account features you'll be able to access for each account the user authorises.

Note: Access to the user's account information is for a maximum of 90 days by default before requiring re-authorisation from the user.

3. Get accounts

Retrieve account information, specifying the consentToken in the header.

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": []
        }
      ]
    }
  ]
}

The response returns an array of account objects for each account the user has provided consent to share information from. The response from every institution is normalised so you can handle the data consistently.

You can then process this account information to validate your user's identity.