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 and Web implementations, you will need to provide us with a redirect URI so that Plaid can return users to your application. If you are building an Android app, 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.
post
https://api.ratio.me
/v1/users/{userId}/banks:requestLink
Requests a bank account link token for a user
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 
Add the bank account to the user account
Use the public token that Plaid provides to add the bank account to your user
post
https://api.ratio.me
/v1/users/{userId}/banks:activateLink
Activates a bank account link for a user
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>"
}'
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
get
https://api.ratio.me
/v1/users/{userId}/banks/{bankId}
Get a Bank Account by ID for a user
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.  

KYC

Re-link Bank Account

Last modified 15d ago