Using the MCC API
Mobile Check Capture API Guide
API Endpoints
The Payology Mobile Capture API is comprised of three API endpoints:
- POST /Mobile
- POST /Scanner
- POST /OCR
It is recommended that clients using the Mobile Check Capture API in a hybrid or native mobile application use the /Mobile endpoint, while clients using a flatbed/desktop scanner use the /Scanner endpoint.
The usage of the OCR endpoint only applies if the client is attempting to detect rear-side endorsements within the check image. This is common when the Pay to the Order of field matches the name of the depository account (i.e. Check21.com is on the Pay to the Order of and the account where the check is deposited is registered in the name of Check21.com).
POST Headers
When using either of the three API endpoints, please use the following Header:
| Header | Value |
|---|---|
| Accept | application/json |
| *Content-Type | application/x-www-form-urlencoded |
*When using Postman or Insomnia during the testing process.
POST /Mobile Endpoint
The POST /Mobile Endpoint is most commonly used in hybrid or native mobile applications. It differs from the Scanner endpoint only by the way in which the original image submitted is cropped. More details of the difference and workflows performed on submission can be found in the section marked Under the Hood.
The POST /Mobile Endpoint consumes the following fields:
| Field | Description |
|---|---|
| licenseNumber | License number provided by the Check21.com team, allowing usage of the API. |
| fileName | Common name of the file being transmitted via API. It is extremely important that any file name submitted has an extension of .jpg, .tif, or .pdf. |
| fileBody | Base64 value of front or rear check image in .jpg, .tif, or .pdf format. For best performance, we recommend not using PDF formats on submission. |
| tempId | Used only when submitting the rear image of the check. The value of this field is supplied in the JSON response produced during the front check image submission. |
| line1 | Virtual Endorsement Line 1 Text to be displayed on rear image of check. **Can only be used when submitting the rear image of check with tempId |
| line2 | Virtual Endorsement Line 2 Text to be displayed on rear image of check. **Can only be used when submitting the rear image of check with tempId |
| line3 | Virtual Endorsement Line 3 Text to be displayed on rear image of check. **Can only be used when submitting the rear image of check with tempId |
| contrastAmount | Apply contrast changes to images. Normally used when retrying image on failure. Format (d.dd). Sample (0.50). Recommended increments in 0.25. |
| retryFailures | On image failure, the solution will rotate the images in 90 degree increments. Format (true/false). Recommended to be "true". |
If using the Mobile Check Capture AI (BETA) Endpoint, the following fields can be consumed:
| Field | Description | Type |
|---|---|---|
| detectCertifiedCheck | When enabled, this function will return an array (certifiedCheckSearch) within the response. The array may include keywords within the check that signify the presence of a Money Order or Cashiers Check and the confidence ratio. If a confidence ratio is equal to 100, there is an incredibly high likelihood that the check is a Certified Check. | true / false |
| keywordSearch | When utilized, this function will return an array (keywordSearch) within the response. The array will include any keyword or key phrase passed as the value of the parameter and the confidence ratio for each value. | keyword or key phrase separated by semicolon. (alphanumeric only) |
Note: When using AI, contractAmount and retryFailures functions are not permitted.
POST /Scanner Endpoint
The POST /Scanner Endpoint is most commonly used in desktop/flatbed scanning workflows. It differs from the Mobile endpoint only by the way in which the original image submitted is cropped. More details of the difference and workflows performed on submission can be found in the section marked Under the Hood.
The POST /Scanner Endpoint consumes the following fields:
| Field | Description |
|---|---|
| licenseNumber | License number provided by the Check21.com team, allowing usage of the API. |
| fileName | Common name of the file being transmitted via API. It is extremely important that any file name submitted has an extension of .jpg, .tif, or .pdf. |
| fileBody | Base64 value of front or rear check image in .jpg, .tif, or .pdf format. For best performance, we recommend not using PDF formats on submission. |
| tempId | Used only when submitting the rear image of the check. The value of this field is supplied in the JSON response produced during the front check image submission. |
| line1 | Virtual Endorsement Line 1 Text to be displayed on rear image of check. **Can only be used when submitting the rear image of check with tempId |
| line2 | Virtual Endorsement Line 2 Text to be displayed on rear image of check. **Can only be used when submitting the rear image of check with tempId |
| line3 | Virtual Endorsement Line 3 Text to be displayed on rear image of check. **Can only be used when submitting the rear image of check with tempId |
| contrastAmount | Apply contrast changes to images. Format (d.dd). Sample (0.50). Recommended to be "0.50". |
| retryFailures | On image failure, the solution will rotate the images in 90 degree increments. Format (true/false). Recommended to be "true". |
Important Notes Regarding POST /Mobile and /Scanner Endpoints
It's important to remind our clients that we do not store check images or sensitive data captured during the submission process. For this reason, on submission of a front check image to either the /Mobile or /Scanner endpoints, a tempId is provided within the JSON response. This tempId must be provided when submitting the rear image of the check to the endpoints. The tempId will be available for a period of 10 minutes, thereafter being deleted. For more details regarding the purpose of the tempId see section Under the Hood.
POST /OCR Endpoint
The POST /OCR Endpoint is most commonly used in an attempt to detect whether the rear check image has an endorsement. It has a significant purpose if the Check21.com client using the API OCR endpoint is a financial institution or a third-party processor/aggregator.
The POST /OCR Endpoint consumes the following fields:
| Field | Description |
|---|---|
| licenseNumber | License number provided by the Check21.com team, allowing usage of the API. |
| base64Tif | Base64 Front cropped image of check provided within the JSON result on submission to the POST /Scanner or POST /Mobile Endpoints. |
| base64TifBack | Base64 Rear cropped image of check provided within the JSON result on submission to the POST /Scanner or POST /Mobile Endpoints. |
| line1 | Virtual Endorsement Line 1 Text to be displayed on rear image of check. |
| line2 | Virtual Endorsement Line 2 Text to be displayed on rear image of check. |
| line3 | Virtual Endorsement Line 3 Text to be displayed on rear image of check. |
Failure of Submission to POST /Mobile or POST /Scanner Endpoint
There are three reasons for which a submitted check item may fail on POST:
- A required field is missing.
- The Base64 is malformed.
- The image cannot be rotated and cropped.
A field missing in the submission of a check item to the Mobile Check Capture API endpoint will result in the following response:
Missing Field Response
{
"code": 500,
"message": "fileBody is required"
}
A malformed Base64 or image which cannot be rotated and cropped will result in the following response:
Base64 or Image Cannot be Processed
{
"code": 500,
"message": "Fail to crop image"
}
Fields and Values of Successful JSON Response
Upon successful submission of a check image to all endpoints, a JSON response is returned. The JSON response includes a variety of different fields and values.
Successful Result of All Endpoints
Below is a successful response of submission to all endpoints. Please note, the TIFF and JPG fields have been edited prior to their presentment on this page and that all "cropped" fields will not be provided on a call to the POST /OCR endpoint.
{
"routingNumber": "063100277",
"checkNumber": "5024",
"croppedMicr": "A063100277A789789789C5024",
"base64TifBackEndorse": "SUkqAAgAAAARAP4ABAABAAAAAAAAAAABBAABAAAAu ... back tiff base64",
"croppedTiff": "ABCDE",
"RecognitionResult": {
"Response": {
"Status": "Success",
"Fields": {
"Field": [
{
"Confidence": 1000,
"Value": "T063100277T789789789U5024",
"Accepted": true,
"Name": "ACR_Codeline1",
"Location": {
"Left": 70,
"Top": 444,
"Right": 742,
"Bottom": 468
}
},
{
"Payor_Parsed": {
"Param": [
{
"Confidence": 94,
"Value": "Roberta Robertson",
"Accepted": true,
"Name": "Name1"
},
{
"Confidence": 0,
"Value": "Long",
"Accepted": false,
"Name": "Name2"
},
{
"Confidence": 100,
"Value": 4,
"Accepted": true,
"Name": "Number of Lines"
},
{
"Confidence": 100,
"Value": 0,
"Accepted": true,
"Name": "Overall Score"
},
{
"Confidence": 0,
"Value": "Long",
"Accepted": false,
"Name": "Phone"
},
{
"Confidence": 0,
"Value": "Long",
"Accepted": false,
"Name": "PO Box"
},
{
"Confidence": 0,
"Value": "Long",
"Accepted": false,
"Name": "Social Security Number1"
},
{
"Confidence": 0,
"Value": "Long",
"Accepted": false,
"Name": "Social Security Number2"
},
{
"Confidence": 0,
"Value": "Long",
"Accepted": false,
"Name": "State"
},
{
"Confidence": 0,
"Value": "Long",
"Accepted": false,
"Name": "Street"
},
{
"Confidence": 0,
"Value": "Long",
"Accepted": false,
"Name": "Town"
},
{
"Confidence": 0,
"Value": "Long",
"Accepted": false,
"Name": "Zip Code"
}
]
},
"Confidence": "00",
"Value": "|Nm1=Roberta Robertson[94]|Nm2=Long[0]|St=Long[0]|Apt=Long[0]|Ssn1=Long[0]|Ssn2=Long[0]|Drv1=Long[0]|Drv2=Long[0]|Ph=Long[0]|Fx=Long[0]|Box=Long[0]|Twn=Long[0]|State=Long[0]|Zip=Long[0]|Email=Long[0]|Dob1=Long[0]|Dob2=Long[0]|Lines=4|Score=0|Win=<51,272,138,461>|Dt=2|Flags=0x0|Unparsed=+3389 Sheridan St",
"Accepted": false,
"Name": "PayorNameAndAddress",
"Location": {
"Left": 34,
"Top": 33,
"Right": 783,
"Bottom": 184
}
},
{
"Confidence": 10,
"Value": "08-14-2019",
"Accepted": false,
"Name": "DATE",
"Location": {
"Left": 60,
"Top": 0,
"Right": 1200,
"Bottom": 354
}
},
{
"Confidence": 1000,
"Value": 750,
"Accepted": true,
"Name": "Amount",
"Location": {
"Left": 985,
"Top": 186,
"Right": 1153,
"Bottom": 238
}
}
]
},
"GeneralInformation": {
"ImageOrientationFeature": "Rotated",
"ElapsedTimeInMsec": 109,
"Country": "USA",
"ErrorCode": 0,
"ErrorMessage": "API error=00000",
"Paper_Name": "Check",
"ImageOrientation": "Normal",
"Engine": "Orbograph",
"DocType": "Personal"
},
"ImageAnalysis": {
"QualityTests": {
"Test": [
{
"content": "Passed",
"Name": "DogsEar"
},
{
"content": "Passed",
"Name": "FrontExcessiveSpot"
},
{
"content": "Passed",
"Name": "FramingError"
},
{
"content": "NotTested",
"Name": "FrontRearMisMatch"
},
{
"content": "Passed",
"Name": "FrontStreak"
},
{
"content": "Passed",
"Name": "FrontAboveMaximumSize"
},
{
"content": "Passed",
"Name": "MaxSize"
},
{
"content": "Passed",
"Name": "FrontBelowMinimumSize"
},
{
"content": "Passed",
"Name": "MinSize"
},
{
"content": "Passed",
"Name": "PiggyBack"
},
{
"content": "Passed",
"Name": "FrontExcessiveSkew"
},
{
"content": "Passed",
"Name": "FrontTooLight"
},
{
"content": "Passed",
"Name": "FrontTooDark"
},
{
"content": "Passed",
"Name": "TornEdges"
},
{
"content": "Passed",
"Name": "UpsideDown"
}
],
"Enabled": true
},
"UsabilityTests": {
"Test": [
{
"content": "Passed",
"Name": "IntegrityTest"
},
{
"content": "Passed",
"Name": "MICRLine"
},
{
"content": "Passed",
"Name": "Payee"
},
{
"content": "Passed",
"Name": "PayorNameAndAddress"
},
{
"content": "Passed",
"Name": "Signature"
},
{
"content": "Passed",
"Name": "Date"
},
{
"content": "NotTested",
"Name": "Endorsement"
},
{
"content": "NotTested",
"Name": "CourtesyAmount"
},
{
"content": "Passed",
"Name": "LegalAmount"
}
],
"Enabled": true
},
"Enabled": true
}
},
"Request": {
"DocID": 1000089968,
"MicrBuffer": "12312.123.4567.123456789",
"CarIcrSetId": 9999,
"IqaSetId": ""
}
},
"check21Base64Jpg": "ABCDE",
"tempId": "94d035fa-8aa8-497a-87c1-ccec9e717ca6",
"accountNumber": "789789789"
}
Sample Checks
Below you will find a link to a zip file consisting of sample check images you can use during your testing process. The zip file consists of the following:
- 3 Personal Checks - Front Images (1.jpg, 2.jpg, 3.jpg)
- 1 Business Check - Front Image (4.jpg)
- 1 Personal Check - Rear Image (1-3_rear.jpg - Can be used when submitting any personal check)
- 1 Business Check - Rear Image (4_rear.jpg - Can be used when submitting the business check)
- Check_Micrs.txt - MICR values for each of the front check images (To be used when submitting the images to the Payment Gateway)
Sample Check URL: https://www.check21.com/sample_checks/Sample_Checks.zip
Next Steps
As developers who may be reviewing this section of the guide, it is important to understand what occurs upon submission of check items to the Mobile Check Capture endpoints. The steps taken within this workflow directly affect performance and thus response times. For further information, please see Under the Hood.
Updated 9 months ago