Using the MCC API

Mobile Check Capture API Guide

API Endpoints

The Payology Mobile Capture API is comprised of three API endpoints:

  1. POST /Mobile
  2. POST /Scanner
  3. 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:

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

FieldDescription
licenseNumberLicense number provided by the Check21.com team, allowing usage of the API.
fileNameCommon 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.
fileBodyBase64 value of front or rear check image in .jpg, .tif, or .pdf format. For best performance, we recommend not using PDF formats on submission.
tempIdUsed 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.

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:

FieldDescription
licenseNumberLicense number provided by the Check21.com team, allowing usage of the API.
fileNameCommon 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.
fileBodyBase64 value of front or rear check image in .jpg, .tif, or .pdf format. For best performance, we recommend not using PDF formats on submission.
tempIdUsed 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.

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:

FieldDescription
licenseNumberLicense number provided by the Check21.com team, allowing usage of the API.
base64TifBase64 Front cropped image of check provided within the JSON result on submission to the POST /Scanner or POST /Mobile Endpoints.
base64TifBackBase64 Rear cropped image of check provided within the JSON result on submission to the POST /Scanner or POST /Mobile Endpoints.
line1Virtual Endorsement Line 1 Text to be displayed on rear image of check.
line2Virtual Endorsement Line 2 Text to be displayed on rear image of check.
line3Virtual 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:

  1. A required field is missing.
  2. The Base64 is malformed.
  3. 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:

  1. 3 Personal Checks - Front Images (1.jpg, 2.jpg, 3.jpg)
  2. 1 Business Check - Front Image (4.jpg)
  3. 1 Personal Check - Rear Image (1-3_rear.jpg - Can be used when submitting any personal check)
  4. 1 Business Check - Rear Image (4_rear.jpg - Can be used when submitting the business check)
  5. 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.