Verifying Bank Accounts
How do I create a bank account identity verification?
Understand how to verify an external bank account against a customer's KYC information
What is a bank account identity verification?
In order to process transfers on the Cybrid Platform, it is required that the customer connecting the external bank account owns the external bank account, and that customer has successfully KYC'd. The bank account identity verification will verify that the name on the connected external bank account matches the name provided during KYC.
Bank account identity verifications are required in order to create transfers on the Cybrid Platform.
Bank account verifications are currently only required for individual customers, not business customers.
Creating a bank account identity verification
The following are prerequisites to creating a bank account identity verification:
- The individual customers state is "verified" (i.e. the customer has successfully completed KYC)
- The external bank account state is "unverified" (i.e. the external bank account has been created but not yet verified)
With these prerequisites met, you can create a customer bank account identity verification via the POST /api/identity_verifications endpoint.
Cybrid Plaid
If you are using Cybrid's Plaid services, you will need to create an identity verification of type "bank_account" and method "account_ownership".
When using the "account_ownership" method, no further customer details are required when creating the bank account identity verification as that information is verified against the Plaid-connected bank account.
An example POST /api/identity_verifications for "method"="account_ownership" request body is below:
{
"type": "bank_account",
"method": "account_ownership",
"customer_guid": "<insert customer_guid>",
"external_bank_account_guid": "<insert external_bank_account_guid>"
}
Partner Plaid
If you are using your own Plaid services (i.e. "plaid_processor_token"), you will need to create an identity verification of type "bank_account" and method "attested_ownership".
When using the "attested_ownership" method, you must provide the customer details when creating the bank account identity verification. Depending how you're storing your customer details, one option is to use the Plaid Identity API to retrieve the customer details in order to pass to the POST request.
An example POST /api/identity_verifications for "method"="attested_ownership" request body is below:
{
"type": "bank_account",
"method": "attested_ownership",
"name": {
"first": "<insert first>",
"last": "<insert last>",
"full": "<insert full>"
},
"address": {
"street": "<insert street>",
"city": "<insert city>",
"subdivision": "<insert state/province>",
"postal_code": "<insert zip/postal code>",
"country_code": "<insert country code>"
},
"customer_guid": "<insert customer_guid>",
"country_code": "<insert country code>",
"date_of_birth": "<insert dob>",
"phone_number": "<insert phone>",
"email_address": "<insert email>",
"identification_numbers": [
{
"type": "<insert ID type>",
"issuing_country_code": "<insert country code>",
"identification_number": "<insert ID number>"
}
],
"external_bank_account_guid": "<insert external_bank_account_guid>"
}
Understanding when the bank account identity verification is complete
After creating a bank account identity verification, you can check the state and outcome of the identity verification using the GET /api/identity_verifications/{identity_verification_guid} endpoint.
Waiting State
All bank account identity verifications will progress immediately from the "storing" state to the "waiting" state.
When a bank account identity verification is either auto-approved or auto-rejected:
- The bank account identity verification will progress from the "waiting" state to the "completed" state (see Completed State below).
When a bank account identity verification is neither auto-approved nor auto-rejected:
- The bank account identity verification will remain in the "waiting" state.
- A Persona document submission inquiry will be automatically created to allow the customer to provide a supplementary document.
- Partners may use the GET /api/identity_verifications/{identity_verification_guid} endpoint to retrieve the "persona_inquiry_id".
- Partners may share the Persona URL + "persona_inquiry_id" directly with the customer (e.g. https://withpersona.com/verify?inquiry-id=<"persona_inquiry_id">).
- Alternatively, partners may use the "persona_inquiry_id" and the Persona SDK to integrate the supplementary document upload experience directly into their application. See Partner Drive Identity Verifications.
- Note: The Cybrid web SDK does not support bank account identity verifications.
- If the customer does not take any action with the above Persona URL, the bank account identity verification will remain in "waiting" state for up to 24 hours before expiring.
Pending State
When the customer has browsed to the Persona URL above:
- The bank account identity verification will progress from the "waiting" state to the "pending" state.
- If the customer does not take any further action beyond browsing to the above Persona URL, the bank account identity verification will remain in "pending" state for up to 24 hours before expiring.
Reviewing State
When the customer has uploaded the supplementary document using the Persona URL above:
- The bank account identity verification will progress from the "pending" state to the "reviewing" state.
- The Cybrid team will be notified that the supplementary documented has been uploaded.
- The bank account identity verification will remain in the "reviewing" state until the Cybrid team has reviewed and determined the outcome (i.e passed, failed).
Completed State
When a bank account identity verification is either auto-approved or auto-rejected:
- The bank account identity verification will progress immediately from the "waiting" state to the "completed" state.
Passed Outcome
When the bank account identity verification is either immediately auto-approved, or approved by the Cybrid team while in the "reviewing" state:
- The bank account identity verification will progress to the "completed" state with a "passed" outcome.
When "outcome":"passed", the bank account identity verification is complete and successful, and the external bank account will progress to "state":"verified".
Failed Outcome
When the bank account identity verification is either immediately auto-rejected, or rejected by the Cybrid team while in the "reviewing" state, the bank account identity verification will progress to the "completed" state with a "failed" outcome, and the "failure_codes" array will return one of the following errors:
- "name_check_failure": The name used during KYC does not match the name registered on the bank account.
- "address_check_failure": The address used during KYC does not match the name registered on the bank account.
- "phone_number_check_failure": The phone number used during KYC does not match the name registered on the bank account. Note: This will not prevent passing.
- "email_address_check_failure": The email address used during KYC does not match the name registered on the bank account. Note: This will not prevent passing.
- "decision_timeout": The bank account verification has timed out.
Note: The external bank account will remain in the "unverified" state until a successful bank account identity verification is completed.
When "outcome":"failed", the bank account identity verification is complete but not successful, and a new bank account identity verification must be created.
Expired State
When the bank account identity verification has been in "waiting" state for 24 hours:
- The Persona document submission inquiry link will expire and is no longer usable for uploading supplementary documents.
- The bank account identity verification will progress to the "expired" state.
Note: The external bank account will remain in the "unverified" state until a successful bank account identity verification is completed.
When "state":"expired", the bank account identity verification did not complete, and a new bank account identity verification must be created.
Updated 12 days ago