Account verification use case

Your goal is to verify the account number and routing number information that has been retrieved from the end-user. Use the Akoya API endpoints to retrieve the account numbers and routing numbers of a consumer’s account directly from their financial institution’s APIs. Matching the account numbers and routing numbers from the end user with the account numbers and routing numbers from the Akoya API endpoints verifies the account.

Account verification relies on the Akoya Payments product. For more information, see the blog post Instant Account Verification with Akoya.

Prerequisites

The API calls require you to have the account holder’s consent. Each data call requires the end-user’s associated id token.

• See Get authorization code for the user authorization process
• See Token to obtain the bearer token for the API calls

Retrieve account information

The account information endpoint is a standalone endpoint that supplies useful account information. You need to retrieve a list of available accounts permissioned by the account holder from this endpoint.

Make the GET request /accounts-info/{version}/{providerId}

• The {version} parameter is the Akoya major version number. Use v2.
• The {providerId} parameter is the shortened version of the bank data provider name, example, mikomo for Mikomo, our fictional provider. You can find the providerId for each bank listed under the Data providers tab of the Data Recipient Hub.

Retrieve account information curl example

curl --request GET \
     --url https://sandbox-products.ddp.akoya.com/accounts-info/v2/mikomo?accountIds=%3AaccountId \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <id_token>'
   

Find accountId

From the results of the retrieve account information call, find the the accountId of the selected account. This is the key for retrieving the payments credentials of the account and routing numbers.

Account information results example

{
    "depositAccount": {
      "accountId": "g833202fb0866d0ad83472c429",
      "accountType": "CHECKING",
      "accountNumberDisplay": "xxxxxxxx0071",
      "currency": {
        "currencyCode": "USD"
      },
      "description": "Checking Plus",
      "fiAttributes": [
           {
            "name": "accountOpenedDate",
            "value": "2020-04-23"
           },
           {
            "name": "interestPaidLastYear",
            "value": "3.20"
           }
      ],
      "nickname": "Nickname Checking Plus 0071",
      "productName": "Checking Plus",
      "status": "OPEN",
      "lineOfBusiness": "Personal",
      "balanceType": "ASSET",
      "interestRate": 0.0125,
      "interestRateType": "FIXED",
      "interestRateAsOf": "2022-03-24T14:15:22Z",
      "lastActivityDate": "2022-03-24T14:15:22Z"
    }
  }

Retrieve routing number and account number from bank

The payments endpoint supplies us with payment information, including the routing and account numbers. We use these numbers to verify the account. Since this information is retrieved directly from the bank’s APIs, this qualifies as a verified account number under the Nacha WEB debit rule.

Make the GET request /payments/{version}/{providerId}/{accountId}/payment-networks .

• The {version} parameter is the Akoya major version number. Use v2.
• The {providerId} parameter is the shortened version of the bank data provider name
• You retrieved the {accountId} with the account information call.

Retrieve payment information curl example

curl --request GET  
--url https://sandbox-products.ddp.akoya.com/payments/v2/mikomo/g833202fb0866d0ad83472c429/payment-networks  
--header 'accept: application/json'  
--header 'authorization: Bearer \<id_token>'\`

Find the routing number and account number

The bankId is the routing number, and the identifier is the account number.

{
    "paymentNetworks": [
        {
            "transferOut": true,
            "identifier": "454992210071",
            "bankId": "125000024",
            "transferIn": true,
            "identifierType": "ACCOUNT_NUMBER",
            "type": "US_ACH"
        }
    ]
}

Compare the account and routing numbers

Compare the routing and account numbers submitted by the user with the verified routing and account numbers you obtained from the Akoya endpoints. Matching numbers verify the account.