RIBBIT

BankVERIFY+

Instant non-credentialed bank intelligence to identify risk and fraud on 99% of accounts

API Integration Guide

To get started, get access to our test environment

If someone within your organization already has access to our test site, they can add you as a user. Otherwise, talk to your sales representative for access

Log in to see customized integration instructions specific to your use case

Once logged in, you can access your API credentials

BankVERIFY+ can be performed from one simple API call

Get an OAuth token

You must log into https://test.RIBBIT.ai to obtain your clientId and clientSecret

You can obtain a bearer token from POST /v3/Token. For more information on obtaining a token, click here

Build your request

BankVERIFY+ requires specific PII (personally-identifiable information) in order to run properly and provide the most accurate results

See example for

Customer

Business

Customer PII Data

customerId
The customer id (or other unique id) from your system that references this customer or applicant

requestTypeId
A requestTypeId of 1 indicates that this verification is being ran on an individual, where 2 is for a small/medium business

signerFirstName
The first name of the customer or signer on the application

signerLastName
The last name of the customer or signer on the application

signerPhone
10-digit phone number of the customer or signer on the application

signerEmail
E-mail address of the customer or signer on the application

signerAddress
The physical address of the customer or signer on the application. If you have a physical and PO address, use the physical address.

Business Data
Used when the bank account belongs to a small/medium business

customerId
The customer id (or other unique id) from your system that references this customer (business)

requestTypeId
A requestTypeId of 2 indicates that this verification is being ran on a business, and 1 is for a customer

businessName
The full legal name of the business

businessPhone
10-digit phone number of the customer (business)

businessEmail
E-mail address of the customer (business)

businessAddress
The physical address of the business. If you have a physical and PO address, use the physical address.

signerFirstName
The first name of the customer or signer on the application

signerLastName
The last name of the customer or signer on the application

signerPhone
10-digit phone number of the customer or signer on the application

signerEmail
E-mail address of the customer or signer on the application

signerAddress
The physical address of the customer or signer on the application. If you have a physical and PO address, use the physical address.

Account Information

routingNumber
The 9-digit routing number of the customer's bank.
For testing purposes, you must use a real routing number

accountNumber
The customer's account number, including any leading zero's, when available.
For testing, you must use realistic numbers or test numbers
Click here for a list of test account numbers

accountTypeId
"1" for checking account, "2" for savings account
Please submit "1" or "2" as a string.

Alternately, if you already have an account token registered with us, you can provide the account token rather than the routing and account numbers and account type

accountToken
A pre-existing account token that references an account already saved in the RIBBIT platform

Loan / Offer / Spending Velocity Details
This information is used to determine affordability of a payment. Many of our attributes and results are centered around the customer's ability to pay (or repay) a specific amount.

offerAmount
The total amount of the loan, the offer amount for a credit product, or the maximum amount of spending allowed. If you do not have a total amount at this time, use an estimate or average. When being used at the top of an underwriting waterfall, the median amount is recommended.

paymentAmount
The amount of each payment, or the median payment/spending amount

terms
The terms of the repayment schedule. Available options are daily_oblic, weekly_oblig, biweekly_oblig, or monthly_oblig

Call BankVERIFY+

POST /v3/riskservices/onboarding/accounts/requestbvpanalytics

{
  "applicationInformation": {
    "requestTypeId": 1,
    "customerId": "A72F817B-744F-4D1F-B347-71E026D0B181",
    "signerFirstName": "John",
    "signerMiddleName": null,
    "signerLastName": "Smith",
    "signerPhone": "4565865555",
    "signerEmail": "jsmith@noemail.com",
    "signerAddress": {
      "address": "678 Fake Street",
      "city": "Oxford",
      "state": "OH",
      "zip": "45056"
	},
    "coSignerFirstName": null,
    "coSignerMiddleName": null,
    "coSignerLastName": null,
    "accountToken": null,
    "routingNumber": "642260020",
    "accountNumber": "111111111",
    "accountTypeId": "1",
    "offerAmount": 2000,
    "terms": "weekly_oblig",
    "paymentAmount": 200,
    "acquisitionOrRefreshType": "Acquisition"
  }
}

{
  "applicationInformation": {
    "requestTypeId": 2,
    "customerId": "A72F817B-744F-4D1F-B347-71E026D0B181",
    "businessName": "Frog Company",
    "businessPhone": "4562220000",
    "businessEmail": "frogcompany@frog.net",
    "businessAddress": {
      "address": "123 Fake Street",
      "city": "Oxford",
      "state": "OH",
      "zip": "45056"
	},
    "signerFirstName": "John",
    "signerMiddleName": null,
    "signerLastName": "Smith",
    "signerPhone": "4565865555",
    "signerEmail": "jsmith@noemail.com",
    "signerAddress": {
      "address": "678 Fake Street",
      "city": "Oxford",
      "state": "OH",
      "zip": "45056"
	},
    "accountToken": null,
    "routingNumber": "642260020",
    "accountNumber": "111111111",
    "accountTypeId": "1",
    "offerAmount": 2000,
    "terms": "weekly_oblig",
    "paymentAmount": 200,
    "acquisitionOrRefreshType": "Acquisition"
  }
}

Response

Click here to view our full API documentation and see/interact with the full response object

The BankVERIFY+ response will be one of the following response types

201 Success - The verification was successful

400 Bad Request - Invalid data was provided

401 Unauthorized - There is a problem with your credentials

403 Forbidden - You do not have permission to make this call

500 Error - A problem occurred which prevented the service from completing

201 - Success

A 201 (HTTP Created) response indicates that a verification record has been created, and is returned when BankVERIFY+ is successful

The API response contains all of the verification details, including recommended action codes, scores, attributes, and account information

Recommended Action Code (RA Code)
The RA Codes offer guidance on how to proceed with the customer's account based on our data results

A1

Best

Strong Positive History

A2

Good

Stable, Positive but some Negative History

A3

OK

Limited Bank History

A4

Flagged

Higher Risk Account and/or Recent Negative History

D1

Decline

Very High Risk and/or Negative History

BankVERIFY+ Score

A measure of bank account risk on a scale of 100-300 (with 300 being low risk) utilizing the BankVERIFY+ attributes

Reason Codes

The BankVERIFY+ score returns a set of three reason codes. Reason codes provide an understanding of why the score was not a perfect score of 300. Potential reason codes include:

stability of bank account transactions
stability of personally identifiable information
stability of amount requested or presented
amount of bank transaction history
recency or volume of bank transaction history
time between or recency of bank presentments
stability of bank account presented
velocity of transaction payment history

BankVERIFY+ RA Codes, Score, and Reason Codes can be found in the bvpAccountAnalyticsResult node

"bvpAccountAnalyticsResult": {
  "score": 150,
  "reasonCode1": "Length of bank presentment history is too short",
  "reasonCode2": "Too many affiliated bank presentments",
  "reasonCode3": "Risky bank account payment return history",
  "accept": false,
  "bvpActionableIntelligence": {
    "actionCode": "D1",
    "actionName": "Decline",
    "actionDescription": "very high risk and/ or very negative history",
  }
}

Attributes
Our data network identifies how often a bank account has been presented for payment and analyzes the bank/payment behavior to better predict financial outcomes. RIBBIT's proprietary database of linkages between accounts and PII elements results in a set of 600+ verification and payment behavior attributes that can be used to identify risk, fraud, and ability to afford payment(s) for underwriting / onboarding of bank accounts.

To use the bank account attributes to perform your own decisioning, you will need to obtain our Data Dictionary, which will map each attribute to their description
Bank Account Attributes can be found under Attributes in the bvpAccountAnalyticsResult node

"bvpAccountAnalyticsResult": {
  "attributes": [
    {
      "name": "bvpattr1",
      "value": 0
    },
    {
      "name": "bvpattr2",
      "value": 0
    }
  ]
}

400 - Bad Request

A 400 error is returned when the quality of the data you are providing is not high enough to run BankVERIFY+.
You will want to handle these errors, because in many cases, you may be able to obtain better information from your customer and try again

Invalid Account Verification
These responses will incur a fee for Account Verification as the account information is invalid.

ID01: Invalid Routing Number

ID02: Invalid Account Number

ID11: Account Structure Issue

The account number does not follow the patterns of a legitimite account number

Failed Data Requirements
No Charge. The data provided does not meet our BankVERIFY+ data structure requirements.

ID10: Account number is invalid. Account number can only have numeric values.

ID12: Account number cannot exceed 17 characters in length.

ID13: Business email cannot exceed 100 characters in length.

ID14: Business email is not a valid email address.

ID15: Business name is required for request type of 2.

ID16: Business name length cannot be longer than 150 characters.

ID17: Business Phone number cannot exceed 12 characters in length.

ID18: Business phone number length is invalid.

ID19: Signer first and last names are required.

ID20: Signer first name is required.

ID21: Signer last name is required.

ID22: Email cannot exceed 100 characters in length.

ID23: ExternalCustomerId cannot exceed 100 characters.

ID24: Signer First name must be at least 2 characters long.

ID25: Signer First name cannot exceed 100 characters long.

ID26: Signer Middle name cannot exceed 100 characters in length.

ID27: Signer Last name must be at least 3 characters in length.

ID28: Signer Last name cannot exceed 100 characters in length.

ID29: Length of the signer first name: (SignerFirstName returned) needs to be at least 2 characters in length.

ID30: Length of the signer last name: (SignerLastName returned) needs to be at least 3 characters in length.

ID31: Phone number cannot exceed 12 characters in length.

ID32: Routing number is invalid. Routing number can only have numeric values.

ID33: Signer email is not a valid email address.

ID34: Signer phone number length is invalid.

ID35: The AccountTypeId should be either a 1 for Checking or 2 for Savings.

ID36: The account number length is invalid.

ID37: The RequestType should be either a 1 for Consumer or 2 for Business.

ID38: Routing number can only be 9 characters long.

ID39: Account number must be at least 5 characters long.

ID40: The routing and account numbers cannot match.

EX01: The system had an issue processing your request.

EX02: There was a problem running BVP. Please try again later.

401 - Unauthorized

A 401 error indicates a problem with your credentials

Has your token expired?
When you receive a OAuth Bearer token, you also receive it's expiration time. If your token has expired, generate a new one

Check your credentials
Make sure you are using the clientId and clientSecret that is found by clicking "API" on the left menu. API credentials are different from widget credentials. Widget credentials will return a 401.

Check the environment and URL
Make sure you are calling our test environment with keys from our test environment

Test API
Test Website

https://sandbox.RIBBIT.ai/v3
https://test.RIBBIT.ai

Production API
Production Website

https://prod.RIBBIT.ai
https://portal.RIBBIT.ai

Reach out to us
There may be some other issue going on with your credentials. Send us a message at support@RIBBIT.ai

403 - Forbidden

A 403 error indicates that your account does not have permission to perform BankVERIFY+

Don't worry, it's probably on us
Send us a message at support@RIBBIT.ai and we'll take a look at your account

500 - Error

If you receive a 500-level error, then there was a problem running BankVERIFY+. These errors are more vague, as they don't fall into the above categories. Sometimes, these errors are caused by incorrect or unexpected values provided to the service. Other times, these are errors caused by our systems.

We actively monitor all 500-level errors
We are constantly looking for ways to improve our systems, and are always monitoring our system health

Reach out to us if you are having problems or receiving unexpected results
Sending a message to support@RIBBIT.ai will create a ticket, and our team will respond quickly

Moving to Production

From a technology standpoint, the following is involved in switching to production

Whitelist your IP addresses
Our production API is IP address restricted. You must provide to us a list of public IP addresses that your back-end uses to call our API

Point your URL to our production server
Our production API server is https://prod.RIBBIT.ai

Use production credentials (clientId and clientSecret)
Log into our production portal (https://portal.RIBBIT.ai), then click on "API" to see your production credentials

In addition to the above changes, the following must also be complete

Fully Executed Service Agreement

Underwriting Approval

Review of test environment transactions, to ensure you are supplying the correct information and utilizing the service to it's fullest capacity

Still have questions?

Send us a message at support@RIBBIT.ai and we will be happy to answer your questions or schedule a meeting!