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:
- "ccs" which allows for POST, GET, and PUT calls.
- "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".
{
"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.
{
"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".
{
"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.
Updated almost 4 years ago