Single Check Deposit
Introduction
In this guide, we will walk through how to create single check deposits initiated by an end user through a mobile device using the JHA SmartPay mRDC™ web service. Our objective is to establish the basic mRDC web service deposit workflow; however, the examples should provide you with the information needed to customize your workflow to fit your specific business needs.
Getting Started
Tasks covered in this guide
- Create a batch with a single or multi-check deposit and then submit the batch for processing.
Required prerequisites before you continue
- You will need to obtain your test credentials to try any of the examples in this guide. You should receive these from the Integrations team near the start of your project.
- Review the mRDC Authentication Guide for an understanding of how to authenticate customers.
- Download the mRDC Web Service WSDL file from the Downloads menu.
Single Check Deposit Workflow
Single Check Deposit Diagram
Integrator Mobile Deposit Flow | EPS mRDC Mobile Deposit Flow | ||||
EPS Web Service | |||||
| 1. | |||||
| 2. | |||||
| 3. | |||||
| 4. | |||||
| 5. | |||||
| 6. | |||||
| 7. | |||||
| 8. | |||||
| |||||
Creating a Check Deposit Batch
Step 1 For our example below, we will use the SSO credentials authentication method. The user initiates the deposit flow in the mobile app. Send the Authenticate request with the following necessary information.
- Request ID
- Request Date
- Credentials - For required information, please see 'SSO Credentials' or 'Store Credentials'.
- Device Tracking
- PhoneKey
For an in-depth explanation about authentication, see the mRDC Authentication Guide for full details of the Authentication components and parameters.
Authenticate Request Example
{
"__type":"AuthenticateRequest:#JackHenry.Eps.Mobile.RDC",
"RequestDate":"/Date(1692650646000-0500)/",
"RequestId":"6S54FD652154654F154654S3D2F1SD3",
"Credentials":{
"__type":"SSOCredentialsSHA256:#JackHenry.Eps.Mobile.RDC",
"PhoneKey":"1",
"FIIdentifier":"999999",
"Hash":"String Content",
"UserNumber":"TestUser",
"SaltValue":"xyz",
"Timestamp":"/Date(1692650646000-0500)/"
},
"DeviceTracking":{
"__type":"DeviceTracking:#JackHenry.Eps.Mobile.RDC",
"AppBundleId":"testbundleid",
"AppVersion":"1.8.1",
"DeviceModel":"iOS",
"DeviceSystemName":"SystemName",
"DeviceSystemVersion":"15.0",
"Vendor":"JackHenry"
},
}
Log the following information from the AuthenticateResponse for use in subsequent requests:
- "SecurityToken"
Authenticate Response Example
Security Tokens are only valid for 15 minutes.
{
"RequestId": "6S54FD652154654F154654S3D2F1SD3",
"Result": 1,
"ResultCode": null,
"ResultMessage": null,
"ValidationResults": [],
"Credentials": {
"PhoneKey": "1",
"SecurityToken": "String Content"
},
"MFA": null,
"OwnerId": "OGRW5",
"PromptTermsAndConditions": false
}
Step 2 Send a GetLocations request. This allows you to retreive the list of eligible accounts the user can make a deposit to via mRDC.
The eligible accounts should be displayed to the customer so that they have the option to select the account they would like to make a deposit into via the mobile app.
GetLocations Request Example
{
"__type":"GetLocationsRequest:#JackHenry.Eps.Mobile.RDC",
"RequestDate":"/Date(1692650646000-0500)/",
"RequestId":"6S54FD652154654F154654S3D2F1SD3",
"Credentials":{
"SecurityToken":"String Content",
"PhoneKey":"1"
}
}
Log the following information from the GetLocationsResponse for use in subsequent requests:
- "SecurityToken" - New token should be used in the next request.
- "Name" - Account information to display to the customer when selecting an account.
- "LocationReference" - A unique ID used only within the mRDC web service.
GetLocations Response Example
{
"RequestId": "6S54FD652154654F154654S3D2F1SD3",
"Result": 1,
"ResultCode": null,
"ResultMessage": null,
"ValidationResults": [],
"Credentials": {
"PhoneKey": "1",
"SecurityToken": "String Content"
},
"Locations": [
{
"IsEnabled": true,
"LocationNumber": "705461",
"LocationReference": "L:T2PR",
"Name": "General Account"
},
{
"IsEnabled": true,
"LocationNumber": "1147677",
"LocationReference": "L:V7J71",
"Name": "Tech Donations"
}
]
}
Step 3 After displaying the list of eligible accounts from the GetLocations response, have the user select an account to make a deposit. Once the user has selected the account, send a GetBatches request. This method returns all batches and their corresponding information for the user.
The customer should have the option to continue with an open batch or create a new batch. If there is an open batch, display that batch to the customer to either delete or add an item to the batch. Typically, you would not want consumers with multiple open batches at once.
GetBatches Request Example
{
"__type":"GetBatchesRequest:#JackHenry.Eps.Mobile.RDC",
"RequestDate":"/Date(1692650646000-0500)/",
"RequestId":"6S54FD6521834u233928rei898u9",
"Credentials":{
"SecurityToken":"String Content",
"PhoneKey":"1"
}
}
Log the following information from the GetBatchesResponse for use in subsequent requests:
- "SecurityToken" - New token should be used in the next request.
- "Name" - Account information to display to the customer when selecting an account.
- "LocationReference" - A unique ID used only within the mRDC web service.
GetBatches Response Example
{
"RequestId": "6S54FD6521834u233928rei898u9",
"Result": 1,
"ResultCode": null,
"ResultMessage": "No deposits for the last 5 days",
"ValidationResults": [],
"Credentials": {
"PhoneKey": "string",
"SecurityToken": "String Content"
},
"Batches": []
}
Step 4 If there are no existing, open batches, the user will elect to start a new batch. Send a CreateBatch request. The CreateBatch response will provide the BatchReference that will be used in the next step.
CreateBatch Request Example
{
"__type":"CreateBatchesRequest:#JackHenry.Eps.Mobile.RDC",
"RequestDate":"/Date(1692650646000-0500)/",
"RequestId":"6S54FD652154654F154654S3D2F1SD3",
"Credentials":{
"SecurityToken":"String Content",
"PhoneKey":"1"
},
"LocationReference":"L:T2PR"
}
Log the following information from the GetBatchesResponse for use in subsequent requests:
- "SecurityToken" - New token should be used in the next request.
- "BatchReference" - A unique ID to identify an open batch that can be used in subsequent requests.
- "LocationReference" - A unique ID used only within the mRDC web service.
CreateBatch Response Example
{
"RequestId": "6S54FD652154654F154654S3D2F1SD3",
"Result": 1,
"ResultCode": null,
"ResultMessage": null,
"ValidationResults": [],
"Credentials": {
"PhoneKey": "1",
"SecurityToken": "String Content"
},
"Batch": {
"BatchNumber": "46843215684321584",
"BatchReference": "B:CYRGWP1",
"Events": [
{
"Date": "/Date(1692650810053-0500)/",
"Description": "Opened"
}
],
"LocationName": "General Account",
"LocationReference": "L:T2PR",
"Status": "BatchStatus05",
"StatusDescription": "Open For Scanning",
"TotalAmount": 0,
"TotalCount": 0
}
}
Adding a Check
Step 5 The user will begin adding checks into the batch using an item information screen that includes the ability to enter the check amount and capture check images. This is when the AddItem request will be sent.
For details on Mitek® image requirements, see the 'Best Practices' developer tool guide.
AddItem Request Example
{
"__type":"AddItemRequest:#JackHenry.Eps.Mobile.RDC",
"RequestDate":"/Date(1692650646000-0500)/",
"RequestId":"6S54FD652154654F154654S3D2F1SD3",
"Credentials":{
"SecurityToken":"String Content",
"PhoneKey":"1"
},
"BatchReference":"B:HC925R1",
"LocationReference":"L:T2PR",
"Amount":5.00,
"FrontImage":"FrontImage",
"BackImage":"BackImage"
}
Log the following information from the AddItemResponse for use in subsequent requests:
- "SecurityToken" - New token should be used in the next request.
- "BatchReference" - A unique ID to identify an open batch that can be used in subsequent requests.
- "LocationReference" - A unique ID used only within the mRDC web service.
AddItem Response Example
{
"RequestId": "6S54FD652154654F154654S3D2F1SD3",
"Result": 1,
"ResultCode": null,
"ResultMessage": null,
"ValidationResults": [],
"Credentials": {
"PhoneKey": "1",
"SecurityToken": "String Content"
},
"Item": {
"Amount": 5,
"BatchReference": "B:CYRGWP1",
"Customer": null,
"DataFields": [
{
"FieldName": "TransactionId",
"FieldType": 0,
"IsRequired": false,
"Text": "Transaction Number",
"Validation": "",
"ValidationMessage": "",
"Value": "998e2160-eedd-44aa-a5d2-1d23c1a8a87d-0"
},
{
"FieldName": "TransactionData1",
"FieldType": 0,
"IsRequired": false,
"Text": "Memo Field",
"Validation": "",
"ValidationMessage": "",
"Value": ""
},
{
"FieldName": "TransactionData2",
"FieldType": 0,
"IsRequired": false,
"Text": "test",
"Validation": "",
"ValidationMessage": "",
"Value": ""
}
],
"Events": [
{
"Date": "/Date(1692650885287-0500)/",
"Description": "Check Decision Performed"
},
{
"Date": "/Date(1692650885270-0500)/",
"Description": "Created"
}
],
"IQAStatus": "Nothing",
"ItemReference": "I:98SHN55",
"ProcessingStatus": null,
"ProcessingStatusDescription": null,
"Status": "ItemStatus04",
"StatusDescription": "Created",
"TransactionReferenceNumber": null
}
}
Step 6 The user should have the option to review the item in their batch. Send the GetItems request.
GetItems request example
{
"__type":"GetItemsRequest:#JackHenry.Eps.Mobile.RDC",
"RequestId":"da5sd146a5sd46as5d46651451236251",
"RequestDate":"\/Date(1635370380000)\/",
"Credentials":{
"PhoneKey":"string",
"SecurityToken":"String Content"
},
"BatchReference":"B:CYRGWP1"
}
Display the item in the batch to the user. At this time, the user should also have the option to delete the item within the batch or delete the entire batch if they choose.
Log the following information from the GetBatchesResponse for use in subsequent requests:
- "SecurityToken" - New token should be used in the next request.
GetItems Response example
{
"RequestId": "da5sd146a5sd46as5d46651451236251",
"Result": 1,
"ResultCode": null,
"ResultMessage": null,
"ValidationResults": [],
"Credentials": {
"PhoneKey": "s65d4a6s5d4as65d4as6",
"SecurityToken": "String Content"
},
"Items": [
{
"Amount": 5.0000,
"BatchReference": "B:CYRGWP1",
"Customer": null,
"DataFields": [
{
"FieldName": "TransactionId",
"FieldType": 0,
"IsRequired": false,
"Text": "Transaction Number",
"Validation": "",
"ValidationMessage": "",
"Value": "638e54b2-e6c1-41b9-8ac8-0d191bfbd82f-0"
},
{
"FieldName": "TransactionData1",
"FieldType": 0,
"IsRequired": false,
"Text": "Memo Field",
"Validation": "",
"ValidationMessage": "",
"Value": ""
},
{
"FieldName": "TransactionData2",
"FieldType": 0,
"IsRequired": false,
"Text": "Invoice Field",
"Validation": "",
"ValidationMessage": "",
"Value": ""
},
{
"FieldName": "TransactionData3",
"FieldType": 0,
"IsRequired": false,
"Text": "Extra Transaction Data Field",
"Validation": "",
"ValidationMessage": "",
"Value": ""
}
],
"Events": [
{
"Date": "/Date(1713204193287-0500)/",
"Description": "IQUA"
},
{
"Date": "/Date(1713204193270-0500)/",
"Description": "CAR Reco"
},
{
"Date": "/Date(1713204058937-0500)/",
"Description": "Check Decision Performed"
},
{
"Date": "/Date(1713204058937-0500)/",
"Description": "Created"
}
],
"IQAStatus": "Done",
"ItemReference": "I:G8P6YK5",
"ProcessingStatus": null,
"ProcessingStatusDescription": null,
"Status": "ItemStatus04",
"StatusDescription": "Created",
"TransactionReferenceNumber": null
}
]
}
Closing the Batch and Logging Out
Step 7 If the user has completed their deposit, the user will elect to make the deposit. Send the UpdateBatch Close request.
UpdateBatch Request Example
{
"__type":"UpdateBatchRequest:#JackHenry.Eps.Mobile.RDC",
"RequestDate":"/Date(1692650646000-0500)/",
"RequestId":"6S54FD652154654F154654S3D2F1SD3",
"Credentials":{
"SecurityToken":"String Content",
"PhoneKey":"1"
},
"Criteria":{
"__type":"UpdateBatchCriteriaCloseBatch:#JackHenry.Eps.Mobile.RDC",
"BatchReference":"B:HC925R1"
}
}
Log the following information from the GetBatchesResponse for use in subsequent requests:
- "SecurityToken" - New token should be used in the next request.
UpdateBatch Response Example
{
"RequestId": "6S54FD652154654F154654S3D2F1SD3",
"Result": 1,
"ResultCode": null,
"ResultMessage": null,
"ValidationResults": [],
"Credentials": {
"PhoneKey": "1",
"SecurityToken": "String Content"
},
"Batch": {
"BatchNumber": "46843215684321584",
"BatchReference": "B:CYRGWP1",
"Events": [
{
"Date": "/Date(1692651042277-0500)/",
"Description": "Closed"
},
{
"Date": "/Date(1692650885643-0500)/",
"Description": "Updated"
},
{
"Date": "/Date(1692650810053-0500)/",
"Description": "Opened"
}
],
"LocationName": "General Account",
"LocationReference": "L:T2PR",
"Status": "BatchStatus08",
"StatusDescription": "Submitted",
"TotalAmount": 5,
"TotalCount": 1
}
}
Step 8 If the user session is complete, send the Logout request.
The Logout response invalidates the security tokens.
Logout request example
{
"__type":"LogoutRequest:#JackHenry.Eps.Mobile.RDC",
"RequestDate":"/Date(1692650646000-0500)/",
"RequestId":"6S54FD652154654F154654S3D2F1SD3",
"Credentials":{
"SecurityToken":"String Content",
"PhoneKey":"1"
}
}
Handling Errors and Failed Requests
Not all requests will be successful. Below are a few common error messages you should be ready to handle.
- mRDC AuthenticateSSO Failure: This can happen for multiple reasons, the most common being a mismatched hash in the request, a timestamp that is out of sync, or the user has not been created or enabled. Should this error occur, please reach out through your normal support channels for assistance and refer to Authentication in the mRDC web service API Reference.
"Code" : "Auth-2003",
"Message" : "Failed to Authenticate"
- Velocity error: Velocity declines will happen when one of the check amount or count limits are exceeded by the transaction. It is important not to automatically retry the transaction as it will not succeed without being under the current limits. To handle this situation, store the velocity decline response with transaction details. Reach out through your normal support channels to discuss your velocity limits further.
- Duplicate transaction: Duplicate transactions will be declined. Transactions are checked against our duplicate table--which is a rolling 75 days of history--and are checked against other transactions for the same merchant (entityID). It is important that transactions that receive a duplicate error are not automatically retried. There are two ways to handle a duplicate transaction.
- The transaction is a true duplicate and will not need another attempt. Aside from recording the response, no further action is needed.
- You are certain that the transaction is not really a duplicate and you need it to process. If a transaction is flagged as a duplicate due to the Transaction Number, this means you will need to change the Transaction Number value to something unique, and then resubmit the request.
- Timeout waiting for response: Systems should be designed to wait 5 seconds to receive a response before timing out. If a timeout occurs, you can attempt to retry the request or reach out through your normal support channels for assistance.
Next steps
- Review the API Reference
This guide is just a starting point to show our basic deposit workflow. Please review the API Reference to see all APIs and their technical specifications.
- Explore other guides
We have other guides to show how to leverage our APIs in other common use cases. If your situation or question is not covered in the current guide, consult another resource.
- Get certified and move into production
Ready to put your new code into production use? Refer to this process guide that explains our certification steps and how to contact us to get started.