Using the MCC Restful API

The Mobile Check Capture API Process

Mobile Check Capture API Usage

The team at Check21.com has developed a Restful API into the Payology Mobile Check Capture solution. The API can be utilized by external solutions, most commonly Native Mobile Applications, to create a Check Capture Submission record, in-turn cropping, rotating, and parsing check images submitted. The API also provided developers with the capability to determine the status of the Record post-submission, an important step in the mobile check capture process.

The API is split into two different endpoints:

1. "ccs" which allows for POST, GET, and PUT calls.
2. "rear-image" which allows for POST calls only.

Important Notes

The Check21.com team suggests you contact our support team prior to using API functionality. Our team can guide developers through the use of the API and ensure that Native Mobile Applications are being built using best practices. You can also view, Best Practice for more information.

CCS Endpoint

The CCS Endpoint is most commonly used to submit the front check image in Base64 for processing, determine the status of the Check Capture Submission record created on submission, and the updating of the Check Capture Submission record with the user entered/confirmed values.

POST CCS Endpoint

The POST CCS Endpoint is used to transmit the front check image for processing, link the newly created Check Capture Submission record to an Account, User, or Contact, and optionally, validate the user entered check amount against the expected amount (i.e. shopping cart amount, invoice, etc).

The Endpoint can be called using the following URL:

https://<YOUR_INSTANCE>.salesforce.com/services/apexrest/c21mcc/ccs/

Fields Within Body of POST CCS Endpoint

The body of the POST payload will include the following fields:

Fields	Description	Required	Mapped Field
frontCheck	Front Check Image in Base64 format.	Yes	N/A
Account	Salesforce Account ID used if linking the Check Capture Record to one Salesforce Account ID.	No	Maps to field "c21mccAccountc" in Check Capture Submission Record.
User	Salesforce User ID used if linking the Check Capture Record to one Salesforce User ID.	No	Maps to field "c21mccUser_IDc" in Check Capture Submission Record.
Contact	Salesforce Contact ID used if linking the Check Capture Record to one Salesforce Contact ID.	No	Maps to field "c21mccContactc" in Check Capture Submission Record.
expectedAmount	The Expected Amount of the check. This is most commonly used if the check is linked to an invoice or policy (i.e. shopping cart amount) whose amount must match the user entered check amount.	If using Expect Amount validation, yes. Otherwise, no.	Maps to field "c21mccExpected_Amountc" in Check Capture Submission Record.
url	All additional data sent in the URL will be saved to the URL field within the Check Capture Submission Record. This can be used as a parsing field to relate the check to multiple records (i.e. one check to 3 invoices).	no.	Maps to field "c21mccURLDatac" in Check Capture Submission Record.

Example of a POST to the CCS Endpoint

Below is an example of a POST to the CCS Endpoint. Please note that "expectedAmount" can only be utilized if Expected Amount validation is enabled in the Payology Mobile Check Capture Settings. As a reminder, the backCheck Base64 below is an example and as such is not "real".

POST CCS

{
      "frontCheck": "sldkjf09uw34rpiohjdjfkns0iue 0r9u3rhfsdfh0wuefs9h0sidk...",
      "account": "001i000001AWbWuGTA",
      "user": "",
      "contact": "",
      "expectedAmount": "100.00"
      "url": "12309843,23049823,3293485"
	}

Successful Result of a POST CCS Endpoint

Below is a successful response of a POST CCS Endpoint.

👍

Status: 200

{
"Hash_id":"sdfsdifDHFKSD32",
"id":"001i000001AWbWuGTA"
}

Failed Results of the POST CCS Endpoint

Below are failed responses of a POST request to the CSS Endpoint.

🚧

Status: 400

Invalid input, object invalid.

📘

Status: 500

{
"error": "Please attach a valid Base64."
}

GET CCS Endpoint

The GET CCS Endpoint is used to determine the OCR capture amount, routing number, account number, and check number (if exists) on the newly created Check Capture Submission record. The data should be prepopulated within the Native Mobile Application and confirmed/edited by the user. The captured data is rarely used when transmitting the check to the client's financial institution. Instead, the user confirmed/updated data is used.

The Endpoint can be called using the following URL:

https://<YOUR_INSTANCE>.salesforce.com/services/apexrest/c21mcc/ccs/?id=<ID_CHECK_CAPTURE_SUBMISSION>

Fields Within Body of GET CCS Endpoint

The response body of the GET payload will include the following fields:

Fields	Description
status	Possible options include: Pending Front Submission Pending Front JSON Response Failed Front Submission Pending Rear Submission Pending Rear JSON Response Failed Rear Submission Pending OCR Response Failed OCR Submission Pending User Confirmation Expected Amount Incorrect Duplicated Completed
amount	Amount captured by the two-tiered OCR engine.
checkNumber	Check Number captured by the two-tiered OCR engine. Note: This field may appear with a NULL value in some instances (i.e. temporary checks, certified checks, etc).
accountNumber	Amount captured by the two-tiered OCR engine.
routingNumber	Amount captured by the two-tiered OCR engine.

Successful Result of a GET CCS Endpoint

Below is a successful response of a GET CCS Endpoint.

👍

Status: 200

{
"status":"Completed",
"amount":1.25,
"checkNumber":"0101",
"accountNumber":"12345679",
"routingNumber":"067006432"
}

Failed Results of the GET CCS Endpoint

Below are failed responses of a GET request to the CSS Endpoint.

🚧

Status: 400

Invalid id supplied.

❗️

Status: 500

{
"error": "That object is calling CheckForce API at the moment. Please try again later."
}

PUT CCS Endpoint

The PUT CCS Endpoint is used to update the user entered/confirmed amount, routing number, account number, and check number on the newly created Check Capture Submission record. Updating the data fields will trigger an update of the MICR line accordingly. This data will subsequently be used when transmitting the check to the client's financial institution.

The Endpoint can be called using the following URL:

https://<YOUR_INSTANCE>.salesforce.com/services/apexrest/c21mcc/ccs

Fields Within Body of PUT CCS Endpoint

The body of the PUT payload must include the following fields:

Fields	Description	Required
id	Check Capture Submission Record ID returned on POST ccs.	Yes
user_amount	User entered/confirmed amount in XXXX.XX format.	Yes
user_routingNumber	User entered/confirmed routing number consisting of 9 digits.	Yes
user_checkNumber	User entered/confirmed check number. Note: Some checks (i.e. certified checks, temporary checks) may not have a check number. If no check number exists on GET ccs call, we recommend not presenting the user with the check number field for input.	Yes
user_accountNumber	User entered/confirmed account number consisting of at least 5 digits, but no more than 17.	Yes

Example of a CCS Endpoint PUT

Below is an example of a PUT to the CCS Endpoint. Although the amount of a check is being extracted using a two-tiered OCR system, it is important to confirm/request the amount from the user. Check21.com recommends using the user-entered amount for accuracy.

PUT CCS

{
      "id": "001i000001AWbWuGTA",
      "user_amount": "100.00",
      "user_routingNumber": "067006432",
      "user_checkNumber": "0101",
      "user_accountNumber": "000042847572"
	}

Successful Result of a PUT to the CCS Endpoint

Below is a successful response of a PUT to the CCS Endpoint. Please note, that the id returned is the Salesforce ID for the Check Capture Submission Record.

👍

Status: 200

{
"id":"001i000001AWbWuGTA"
}

Failed Results of PUT to the CCS Endpoint

Below are failed responses of a PUT request to the CSS Endpoint.

🚧

Status: 400

Invalid input, object invalid.

❗️

Status: 500

{ "error": "That object is calling CheckForce API at the moment. Please try again later." }

Rear-Image Endpoint

The simplest of the two endpoints, the Rear-Image Endpoint, is used to submit and link the rear check image (in Base 64) to the Check Capture Submission record.

The Endpoint can be called using the following URL:

https://<YOUR_INSTANCE>.salesforce.com/services/apexrest/c21mcc/rear-image/

Fields Within Body of POST Rear-Image Endpoint

The body of the POST payload must include the following fields:

Field	Description	Required
backCheck	Base64 Rear Image of Check	Yes
id	Check Capture Submission Record ID returned on POST ccs.	Yes

Example of a Rear-Image Endpoint POST

Below is an example of a POST to the Rear-Image Endpoint. As a reminder, the backCheck Base64 below is an example and as such is not "real".

Post Rear-Image

{
      "backCheck": "sldkjf09uw34rpiohjdjfkns0iue 0r9u3rhfsdfh0wuefs9h0sidk...",
      "id": "001i000001AWbWuGTA"
	}

Successful Result of Rear-Image Endpoint

Below is a successful response of a submission to the Rear-Image Endpoint. Please note, that the id returned is the Salesforce ID for the Check Capture Submission Record.

👍

Status: 200

{
"id":"001i000001AWbWuGTA"
}

Failed Results of Rear-Image Endpoint

Below are failed responses of a submission to the Rear-Image Endpoint.

🚧

Status: 400

Invalid input, object invalid.

❗️

Status: 500

{
"error": "You cannot send the back Image at this moment, please try again later and check if the Front Image is already attached."
}

❗️

Status: 500

{
"error": "Failed Front Check Image Submission, please try again."
}

❗️

Status: 500

{
"error": "Please attach a valid Base64."
}

Next Steps

Salesforce Developers or Administrators who seek to understand the Data Model, specifically the Objects utilized in the Check Capture process, can do so by viewing the section labeled, The Data Model.