Using the Check Verification API
Check Verification API Guide
API Endpoints
The Check Verification API is comprised of three API endpoints:
- POST /login
- POST /cvapi
- Get /cvapi
Endpoint Headers
When using either of the three API endpoints, please use the following Header:
| Header | Value |
|---|---|
| Accept | application/json |
| Content-Type | application/json |
| X-AUTH-TOKEN | {Provided by POST /login Endpoint and used with POST & GET /cvapi.} |
POST /login Endpoint
The POST /login Endpoint is used to obtain an X-AUTH-TOKEN which is required when utilizing the POST and GET /cvapi Endpoints. Please note that any token retrieved will expire within 72 hours if not utilized within that time frame.
The POST /login Endpoint consumes the following fields:
| Field | Description |
|---|---|
| username | Username of user who has API capabilities within the CheckVerification.com portal. |
| password | Password of user who has API capabilities within the CheckVerification.com portal. |
Successful POST /login Endpoint Response
If the username and password provided on POST /login Endpoint Request is successful, it will result in the following response.
200 OK Response
{
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOjIyfQ.OzEOgZiJ42BR"
}
Failed POST /login Endpoint Response - Not Formatted Properly
If the username and password provided on POST /login Endpoint Request is not properly formatted, it will result in the following response(s).
422 Uprocessable Entity
{
"errors": [
"username length must be at least 3"
]
}
- Or -
422 Uprocessable Entity
{
"errors": [
"password length must be at least 6"
]
}
Failed POST /login Endpoint Response - Invalid Authentication
If the username and password provided on POST /login Endpoint Request is invalid, it will result in the following response.
401 Unauthorized
{
"code": 401,
"message": "HTTP 401 Unauthorized"
}
POST /cvapi Endpoint
The POST /cvapi Endpoint is used to transmit bank account and payee data to the Check Verification API for verification of the routing number, account number, check writing history, and/or sufficient fund balance.
The POST /cvapi Endpoint consumes the following fields:
| Field | Description | Format |
|---|---|---|
| *licenseNumber | License Number found within the Check Verification portal which corresponds to the verification service the organization will be using in the submission process. | Allows for only valid license numbers. The field is numeric only. |
| **companyName | Company Name of bank account owner. Used if firstName/lastName fields are not applicable. | The field allows for alhpanumeric characters as well as symbols. The field limit is 50. |
| **firstName | First name of bank account owner. Used if companyName field is not applicable. | The field allows for alpha characters as well as symbols. The field limit is 20 characters. |
| **lastName | Last name of bank account owner. Used if companyName field is not applicable. | The field allows for alpha characters as well as symbols. The field limit is 30 characters. |
| *address1 | Address of bank account owner. | The field allows for alphanumeric characters as well as symbols. The field limit is 50. |
| *city | City of bank account owner. | The field allows for alphanumeric characters as well as symbols. The field limit is 50. |
| *state | State of bank account owner. | The field requires a valid two letter state abbreviation. The field requirement is 2. |
| *zip | Zip of bank account owner. | The field requires a valid five digit zip code. The field requirement is 5. |
| *amount | Amount of transaction which will be verified. Organizations requiring bank account validity, check writing history, or routing number validation can use "1.00". | The field requires a minimum of 1 digit prior to the decimal point and 2 digits after the decimal point. |
| *accountNumber | Bank account number provided by user or organization. | The field is numeric only. The field requires a minimum of 4 digits and has a limit of 20. |
| *routingNumber | Bank routing number provided by user or organization. | The field is numeric only. The field requires a valid 9 digit routing number. |
| checkNumber | Bank check number provided by user or organization. | The field requires a minimum of 3 digits. If a check number is not available, please leave it blank. |
| *orderId | Unique internal order ID which can be used to reference the submission. | The field allows for alphanumeric characters as well as symbols. The orderId field has a limit of 20. |
Successful POST /cvapi Endpoint Response
If the data provided on POST /cvapi Endpoint Request is successful, it will result in the following response structure.
200 OK
{
"id": 11343376,
"createdAt": "2021-03-15 14:29:39",
"atmNcnResult": 3,
"atmNcnCode": null,
"atmNcnDescription": null,
"liveVerifyResult": 0,
"liveVerifyCode": 0,
"subResult": null,
"routingResult": 3
}
POST /cvapi Response Fields and Values
Below is a list of possible values which may return as part of a successful Request sent to the POST or GET /cvapi Endpoints.
| Field | Description |
|---|---|
| id | Unique ID provided on submission of successful verification Request. |
| createdAt | Date and time transaction was successfully received (YYYY-MM-DD HH:MM:SS). |
| atmNcnResult (also used with Early Warning/Forewarn) | Result of the ATM/NCN Verification Service Request. 1 = Account Valid 2 = Account Invalid 3 = Not Utilized 4 = Surpassed Volume 5 = Pending Live Result 6 = Pending Result 7 = Cannot Verify 8 = Invalid RT Number |
| atmNcnCode (also used with Early Warning/Forewarn) | See "ATM/NCN and Early Warning Codes" Section. |
| atmNcnDescription (also used with Early Warning/ForeWarn) | See "ATM/NCN and Early Warning Codes" Section. |
| liveVerifyResult | Result of the Live Verification Service Request. 0 = Pending Verification (or Not Utilized if not using the Live Verify License) 1 = Verification Completed Successfully 2 = Bank Not in Network 3 = Could Not Verify 4 = Amount of Transaction Exceeds Banks Limit |
| liveVerifyCode | Bank Account status of the Live Verification Service Request. 0 = Pending Verification (or Not Utilized if not using the Live Verify License) 1 = Sufficient Funds 2 = Account Valid 3 = Account Invalid 4 = Insufficient Funds 5 = Cannot Verify 9 = Client Submissions Exceeded Limit 10 = Pending ATM Result 11 = Amount of Transaction Exceeds Banks Limit 14 = Bank Not In Network Legacy ID's 6 = Not Utilized 7 = Pending Verification 8 = Failed Verification 15 = Pending Manual Verification 16 = Invalid Routing Number |
| subResult | When provided by institution, Sub-Result of the Live Verification Service Request. 1 = Account Frozen 2 = Account Blocked 3 = Account Closed 4 = Name Does Not Match 5 = Incorrect Account Number 6 = Address Incorrect 7 = Bank Does Not Verify |
| routingResult | Result of the ATM/NCN Verification Service Request. 1 = Routing Valid 2 = Routing Invalid 3 = Not Utilized |
Failed POST /cvapi Submission - Invalid License Number
If the License Number provided on POST /cvapi Endpoint Request is not valid, it will result in the following response(s).
403 Forbidden
{
"code": 403,
"message": "Invalid License Number"
}
Failed POST /cvapi Submission - Invalid X-Auth-Token
If the X-Auth-Token provided on POST /cvapi Endpoint Request Header is not valid, it will result in the following response(s).
500 Internal Server Error
{
"code": 500,
"message": "Fail to identify the user. Wrong number of segments: 1"
}
GET /cvapi Endpoint
The GET /cvapi Endpoint is used to query the status of a transaction which has been submitted to the Live Verify service and, on submission resulted in a "pending" response.
The GET /cvapi Endpoint is comprised of and requires the following field:
| Field | Description | Format |
|---|---|---|
| id | Transaction/Verification ID returned when submitting the item to the POST /cvapi endpoint. | The field is numeric only. |
Successful GET /cvapi Endpoint Response
If the data provided on GET /cvapi Endpoint Request is successful, it will result in the following response structure.
200 OK
[
{
"id": 9711458,
"createdAt": "2020-11-17 00:11:37",
"atmNcnResult": 3,
"atmNcnCode": null,
"atmNcnDescription": null,
"liveVerifyResult": 1,
"liveVerifyCode": 3,
"subResult": null,
"routingResult": 3
}
]
Failed GET /cvapi Submission - Invalid Transaction ID
If the Transaction ID provided on GET /cvapi Endpoint Request is not valid, it will result in the following response(s).
401 Unauthorized
{
"code": 401,
"message": "HTTP 401 Unauthorized"
}
GET /cvapi Response Fields and Values
See "POST /cvapi Response Fields and Values" section.
ATM/NCN and Early Warning (ForeWarn) Codes.
Below is a list of ATM/NCN and Early Warning Codes which may be returned as part of a service request.
Early Warning (ForeWarn) Codes
| Code | Description | Meaning of Code |
|---|---|---|
| P70 | VALIDATED | The provider has determined that the account is open and valid. |
| P80 | VENDOR BUSY (Timeout) | The provider is not available at the time of submission. (i.e. providers platform is down) |
| P41 | NEGATIVE | The provider has determined that the account is invalid or cannot be used for electronic debit. |
| P73 | MEDIUM RISK APPROVAL | The provider has determined that the account is open and valid but may not allow debits. |
| BRN | BAD ROUTING NUMBER | The routing number provided is not a valid routing number. |
ATM/NCN Codes
| Code | Description | Meaning of Code |
|---|---|---|
| P00 | ACCT NOT LOCATED | The provider could not find that account number provided. |
| P70 | VALIDATED | The provider has determined that the account provided is not in poor standing or is in good standing. |
| P80 | VENDOR BUSY (Timeout) | The provider is not available at the time of submission. (i.e. providers platform is down) |
| P92 | PREAUTH SERVER UNAVAILABLE (Timeout) | The provider is not available at the time of submission. (i.e. providers platform is down) |
| P15 | HIGH RISK ACCOUNT | The routing number provided is not a valid routing number or the account is currently not in good standing. |
| P41 | NEGATIVE | The provider has determined that the account is invalid. |
| P71 | LOW RISK APPROVAL | The provider has determined that the account is valid and in good standing. |
| P73 | MEDIUM RISK APPROVAL | The provider has determined that the account is valid but may pose a risk when a debit is attempted. |
| U02 | ACCOUNT NOT APPROVED IN BLACK LIST | The account provided is blacklisted by the provider (reason unknown). |
| BRN | BAD ROUTING NUMBER | The routing number provided is not a valid routing number. |
| UNK | COULD NOT VERIFY | The provider could not provide any specific information for the account number submitted. |
| U84 | AUTH TIMEOUT | The provider is not available at the time of submission. (i.e. providers platform is down) |
| U85 | ACCT NUM LEN ERR | The provider has determined that the length of the account number provided does not match the expected length for the corresponding financial institution. |
Testing ATM/NCN and Early Warning
By utilizing a test license and the Routing Number "067006432" in combination with the below account numbers, developers can expect the following results to be provided in the JSON response.
| Account Number | ATM Code | ATM NCN Result | Description |
|---|---|---|---|
| 100000070 | "P70 " | 1 | Validated |
| 100000080 | "P80" | 2 | Vendor Busy |
| 100000041 | "P41" | 2 | Negative |
| 100000073 | "P73" | 1 | Medium Risk |
| 100000000 | "P00" | 2 | Account Not Located |
| 100000092 | "P92" | 2 | Preauth Server Unavailable |
| 100000015 | "P15" | 2 | High Risk |
| 100000071 | "P71" | 1 | Low Risk |
| 100000002 | "U02" | 2 | Account Not Approved in Blacklist |
| 100000084 | "U84" | 2 | Auth Timeout |
| 100000085 | "U85" | 2 | Account Number Length Error |
| 100000100 | "UNK" | 2 | Could Not Verify |
Testing Live Verify
By utilizing a test license and the Routing Number "067006432" in combination with the below account numbers, developers can expect the following results to be provided in the JSON response.
| Account Number | Live Verify Result | Live Verify Code | Description |
|---|---|---|---|
| 200000000 | 0 | 0 | Pending |
| 200000001 | 1 | 1 | Sufficient |
| 200000002 | 1 | 2 | Valid |
| 200000003 | 1 | 3 | Invalid |
| 200000004 | 1 | 4 | Insufficient |
| 200000005 | 3 | 0 | Cannot Verify |
| 200000009 | 3 | 0 | Client Submissions Exceeded Limit |
| 2000000011 | 4 | 0 | Amount of Transaction Exceeds Banks Limit |
| 2000000014 | 2 | 0 | Bank Not in Network |
Updated almost 3 years ago