Link and Verify a Bank Account
We use Plaid to link a user's bank account to Ratio.
Our Bank account API has four actions
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.
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.
Users can only have one bank account linked to Ratio at a time. We do not support having multiple bank accounts linked at once.
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.
Oops, something is missing.We could not find the original source to display this content.
Request
Response
{
"redirectUri": "https://your.redirecturi.com",
"androidPackageName": "com.example"
}
{
"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
Use the public token that Plaid provides to add the bank account to your user
Oops, something is missing.We could not find the original source to display this content.
Request
Response
{
"publicToken": "public-sandbox-72ffcabb-7eb1-4ac7-b7e4-d2261e3fa78f"
}
{
"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>"
}'
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:
- 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.
Oops, something is missing.We could not find the original source to display this content.
Alternatively, you can listen to the bank verification event "BANK_UPDATED" by subscribing to webhooks.
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.
Last modified 2mo ago