DOCUMENTATION
Guides
Recipient login

Account verification use case

Suggest Edits

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.

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 and account numbers 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 routing and account numbers

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 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.


Need help?

Check out our Developer Community, or visit the Support Center in the Data Recipient Hub.

Looking for provider nuance documentation?

All provider nuance documentation is available in the Data providers section in the Data Recipient Hub.

Still stuck?

For all production issues, submit a support ticket through the Data Recipient Hub. Our support team is standing by 24/7. Questions and non-production issues will be answered during business hours.

Updated 5 months ago