Link and Verify a Bank Account

A created user is required to link and verify a bank account

Overview

We use Plaid to link a user's bank account to Ratio.

Our Bank account API has four actions

• Link bank account

• Re-link bank account

• Replace existing bank account

• Remove existing bank account

First, you will need to install the appropriate Plaid SDK for your target device (iOS, Android, Web).

You do not need a Plaid account in order to use Ratio because your user is forming a direct relationship with Ratio and Ratio is responsible for all payments, compliance, and risk.

Reminder!

For iOS apps, you will need to provide sandbox and production redirect URIs so that Plaid can return users to your application. For Android apps, you must provide us with the Android Package Name. These values need to match what you send in your requestLink calls.

Link the bank account

Users can only have one bank account linked to Ratio at a time. We do not support having multiple bank accounts linked at once.

Fetch a Plaid link token

The first step in connecting a user's bank account is to request a link token from our API, then pass it to Plaid's SDK.

Request

{
  "redirectUri": "https://your.redirecturi.com",
  "androidPackageName": "com.example"
}

Response

{
  "linkToken": "link-sandbox-ab12c3d4-0000-123a-987f-26e621c2ee51"
}

cURL

curl --location -g --request POST 'https://api.ratio.me/v1/users/<USER_ID>/banks:requestLink' \
--header 'ratio-client-id: <YOUR_CLIENT_ID>' \
--header 'ratio-client-secret: <YOUR_CLIENT_SECRET>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
  "redirectUri": "<YOUR_REDIRECT_URI>",
  "androidPackageName": "<YOUR_ANDROID_PACKAGE_NAME>"
}'

You now have a link token that looks something like this:

link-sandbox-ab12c3d4-0000-123a-987f-26e621c2ee51. 

This token needs to be provided to Plaid’s SDK.

Once you have initiated the Plaid session using the link token, Plaid completely takes over. You do not need to do anything and Plaid will not emit any events until onSuccess or onExit.

If onSuccess - the user has successfully linked their bank account and you proceed with adding the bank account to the user account

If onExit - the user did not successfully authenticate their account (closed the Plaid SDK, bank connect was down, etc.) and you should bring them back to the screen that you are launching Plaid from

Add the bank account to the user account

Use the public token that Plaid provides to add the bank account to your user

Request

{
  "publicToken": "public-sandbox-72ffcabb-7eb1-4ac7-b7e4-d2261e3fa78f"
}

Response

{
  "bankAccount": {
    "id": "string",
    "createTime": "2023-04-05T18:58:07.546Z",
    "updateTime": "2023-04-05T18:58:07.546Z",
    "name": "Account Name",
    "mask": "1234",
    "linkStatus": "INACTIVE",
    "verificationStatus": "IN_REVIEW"
  }
}

cURL

curl --location -g --request POST 'https://api.ratio.me/v1/users/<USER_ID>/banks:activateLink' \
--header 'ratio-client-id: <YOUR_CLIENT_ID>' \
--header 'ratio-client-secret: <YOUR_CLIENT_SECRET>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
  "redirectUri": "<YOUR_REDIRECT_URI>",
  "androidPackageName": "<YOUR_ANDROID_PACKAGE_NAME>"
}'

Bank account verification

After the bank account is added to the user, Ratio runs a verification process to ensure that the user identity tied to the bank account is the same user identity that was provided during KYC.

At this point, you have two options to notify the user of the outcome of their bank verification:

Poll for status

• Link status = ACTIVE, means that you have successfully added the bank account to the user

• Verification status = APPROVED, means that we have successfully verified the bank account

• Verification status = DECLINED, stop polling, and present the user account flag found on the user object.

Verification is typically <5s. We suggest polling 10 times, every 2 seconds, and retry if needed

Webhook

Alternatively, you can listen to the bank verification event "BANK_UPDATED" by subscribing to webhooks.

Bank Account Linking and Verification Troubleshooting

A created user with KYC approved is required to verify a bank account

You can assign the deposit address, KYC the user, and link their bank account in any order. However the most common user flow is to set the deposit address, then KYC the user, then link their bank account.

For a bank account to become verified, the name on the account must match the name provided by the user during KYC.

There are 3 common reasons a bank account verification will fail:

1. The user has attempted to link a business bank account

2. The user has linked a joint bank account where they are not the first name on the account

   • Note that joint accounts are acceptable but banks typically only return the first name on the account and our verification will fail if the bank does not return your name.

3. The connection between Plaid and the user's bank is down. This used to be a much larger problem than it is today. Today, more than 60% of bank linking via Plaid is done via OAuth, which experiences near-zero downtime. If a bank connection is down, it is typically available again within a day.