Using the Check Verification API

Check Verification API Guide

API Endpoints

The Check Verification API is comprised of three API endpoints:

  1. POST /login
  2. POST /cvapi
  3. Get /cvapi

Endpoint Headers

When using either of the three API endpoints, please use the following Header:

HeaderValue
Acceptapplication/json
Content-Typeapplication/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:

FieldDescription
usernameUsername of user who has API capabilities within the CheckVerification.com portal.
passwordPassword 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:

FieldDescriptionFormat
*licenseNumberLicense 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.
**companyNameCompany 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.
**firstNameFirst 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.
**lastNameLast 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.
*address1Address of bank account owner.The field allows for alphanumeric characters as well as symbols. The field limit is 50.
*cityCity of bank account owner.The field allows for alphanumeric characters as well as symbols. The field limit is 50.
*stateState of bank account owner.The field requires a valid two letter state abbreviation. The field requirement is 2.
*zipZip of bank account owner.The field requires a valid five digit zip code. The field requirement is 5.
*amountAmount 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.
*accountNumberBank 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.
*routingNumberBank routing number provided by user or organization.The field is numeric only. The field requires a valid 9 digit routing number.
checkNumberBank 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.
*orderIdUnique 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.

FieldDescription
idUnique ID provided on submission of successful verification Request.
createdAtDate 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.
liveVerifyResultResult 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
liveVerifyCodeBank 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
subResultWhen 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
routingResultResult 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:

FieldDescriptionFormat
idTransaction/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

CodeDescriptionMeaning of Code
P70VALIDATEDThe provider has determined that the account is open and valid.
P80VENDOR BUSY (Timeout)The provider is not available at the time of submission. (i.e. providers platform is down)
P41NEGATIVEThe provider has determined that the account is invalid or cannot be used for electronic debit.
P73MEDIUM RISK APPROVALThe provider has determined that the account is open and valid but may not allow debits.
BRNBAD ROUTING NUMBERThe routing number provided is not a valid routing number.

ATM/NCN Codes

CodeDescriptionMeaning of Code
P00ACCT NOT LOCATEDThe provider could not find that account number provided.
P70VALIDATEDThe provider has determined that the account provided is not in poor standing or is in good standing.
P80VENDOR BUSY (Timeout)The provider is not available at the time of submission. (i.e. providers platform is down)
P92PREAUTH SERVER UNAVAILABLE (Timeout)The provider is not available at the time of submission. (i.e. providers platform is down)
P15HIGH RISK ACCOUNTThe routing number provided is not a valid routing number or the account is currently not in good standing.
P41NEGATIVEThe provider has determined that the account is invalid.
P71LOW RISK APPROVALThe provider has determined that the account is valid and in good standing.
P73MEDIUM RISK APPROVALThe provider has determined that the account is valid but may pose a risk when a debit is attempted.
U02ACCOUNT NOT APPROVED IN BLACK LISTThe account provided is blacklisted by the provider (reason unknown).
BRNBAD ROUTING NUMBERThe routing number provided is not a valid routing number.
UNKCOULD NOT VERIFYThe provider could not provide any specific information for the account number submitted.
U84AUTH TIMEOUTThe provider is not available at the time of submission. (i.e. providers platform is down)
U85ACCT NUM LEN ERRThe 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 NumberATM CodeATM NCN ResultDescription
100000070"P70 "1Validated
100000080"P80"2Vendor Busy
100000041"P41"2Negative
100000073"P73"1Medium Risk
100000000"P00"2Account Not Located
100000092"P92"2Preauth Server Unavailable
100000015"P15"2High Risk
100000071"P71"1Low Risk
100000002"U02"2Account Not Approved in Blacklist
100000084"U84"2Auth Timeout
100000085"U85"2Account Number Length Error
100000100"UNK"2Could 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 NumberLive Verify ResultLive Verify CodeDescription
20000000000Pending
20000000111Sufficient
20000000212Valid
20000000313Invalid
20000000414Insufficient
20000000530Cannot Verify
20000000930Client Submissions Exceeded Limit
200000001140Amount of Transaction Exceeds Banks Limit
200000001420Bank Not in Network