Docs
  • What We Do
  • Supported Countries, Payment Methods, and Cryptocurrencies
  • Getting Started
  • Integration Guides
    • API
      • Required Headers
      • Create a User
      • Assign a Deposit Address
      • KYC
      • Link and Verify a Bank Account
        • Re-link Bank Account
        • Update Bank Account
        • Delete Bank Account
      • Transaction Limits
      • Buy Crypto (ACH)
      • Transaction Monitoring
      • Transaction History
    • React Native
      • Installation
      • Session Token and Wallet Signing
      • Preset Order Details
      • Example
      • Reference
      • Release History
      • User experience
        • Sign up
        • Sign in
        • Buy crypto
        • Settings & activity
    • React JS (Beta)
      • Installation
      • Session Token and Wallet Signing
      • Preset Orders
      • Callbacks
      • Theming
      • Example
      • Reference
      • Release History
  • API Reference
    • Endpoints
      • Auth
        • Crypto Wallet
        • Email OTP
        • SMS OTP
      • Activity
      • Bank
      • Client
      • Config
      • Crypto
      • Users
      • Wallets
      • Webhook Registrations
    • Custom Headers
    • Error Codes
    • Types Glossary
    • Postman
    • Open API Specification
    • Webhooks
  • Design Reference
    • UI/UX Starter kit
    • UI Requirements
  • Guides
    • Sandbox Testing
    • User Authentication
    • Link a new Signing Wallet to an Existing User
    • Plaid Bank Linking
      • Plaid OAuth Support
    • Client Dashboard (Alpha)
  • User Support Reference
    • User Account Flags
      • KYC Review
      • Transaction Processing
      • NSFs and Returned Payments
      • Fraud
    • Transactional Emails
Powered by GitBook
On this page

Was this helpful?

  1. Integration Guides
  2. API

Link and Verify a Bank Account

PreviousKYCNextRe-link Bank Account

Last updated 1 year ago

Was this helpful?

A 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

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

{
  "redirectUri": "https://your.redirecturi.com",
  "androidPackageName": "com.example"
}
{
  "linkToken": "link-sandbox-ab12c3d4-0000-123a-987f-26e621c2ee51"
}
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

{
  "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 --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

Bank Account Linking and Verification Troubleshooting

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.

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

A with 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 , then , then .

webhooks
KYC approved
created user
set the deposit address
KYC the user
link their bank account
Re-link bank account
Replace existing bank account
Remove existing bank account
created user
Link bank account
you will need to install the appropriate Plaid SDK
sandbox