Skip to main content

Multi Check Deposit

Introduction

In this guide, we will walk through how to create multi-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 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.
Multi-Check Deposit Workflow
Integrator Mobile Deposit Flow
EPS mRDC Mobile Deposit Flow

EPS Web Service

1.

Send AuthenticateSSO request

Authenticate response with security token

User initiates deposit flow

2.

Send GetLocations request

GetLocations response with list of accounta user can deposit to with security token

3.

Send GetBatches request

GetBatches response with security token

Display to user any open batches that may exist. They should have the option to continue with an open batch or create a new batch

4.

User elects to start a new batch, send CreateBatch request

CreateBatch response with security token

5.

User begins adding checks to the batch using an item information screen which includes the ability to capture check images. Send AddItem request

AddItem response with security token

6.

Send GetItems reqeust

GetItems response with security token

Display list of items in batch to the user. The user should also have the option to delete any item in the batch if they choose. The user should also have the option to delete the entire batch if they choose.

7.

User elects to make deposit, send UpdateBatch Close request

UpdateBatch response with security token

8.

If user session is complete, send Logout request

Logout response to invalidate security tokens

 

 

Creating a Multi-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 required information.

note

For an in-depth explanation about authentication, see the mRDC Authentication Guide for full details about 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 this value from the AuthenticateResponse for use in subsequent requests:

  • "SecurityToken"
note

Security Tokens are only valid for 15 minutes.

Authenticate Response Example

{
    "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 will allow you to retreive the list of eligible accounts the user can make a deposit via mRDC.

note

The eligible accounts should be displayed to the customer so 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 will return all batches and their corresponding information for the user.

note

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 will 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 provides 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 Checks to the Batch

Step 5 Using an item information screen that includes the ability to enter the check amount and capture check images, the user will begin adding checks into the batch. This is when the AddItem request will be sent.

note

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"
	}
note

Repeat step 5 if the user would like to add more items to the batch.

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 Send the GetItems request. This method provides the user the option to review a list of items within the batch and be able to delete any item in the batch if they choose.

GetItems Request Example

	{
	"__type":"GetItemsRequest:#JackHenry.Eps.Mobile.RDC",
	"RequestDate":"/Date(1692650646000-0500)/",
	"RequestId":"6S54FD652154654F154654S3D2F1SD3",
	"Credentials":{
    	"SecurityToken":"String Content",
	"PhoneKey":"1"
	},
	"BatchReference":"B:HC925R1"
	}

Log the following information from the GetItems response 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.
  • "ItemReference" - The unique value assigned to each item that can be used to get more details about an item within the batch.

GetItems Response Example

{
    "RequestId": "6S54FD652154654F154654S3D2F1SD3",
    "Result": 1,
    "ResultCode": null,
    "ResultMessage": null,
    "ValidationResults": [],
    "Credentials": {
        "PhoneKey": "s65d4a6s5d4as65d4as6",
        "SecurityToken": "String Content"
    },
    "Items": [
        {
            "Amount": 5.0000,
            "BatchReference": "B:3YYTYV1",
            "Customer": null,
            "DataFields": [
                {
                    "FieldName": "TransactionId",
                    "FieldType": 0,
                    "IsRequired": false,
                    "Text": "Transaction Number",
                    "Validation": "",
                    "ValidationMessage": "",
                    "Value": "bc18793d-a6c3-4931-927d-3f8d02cab9e7-0"
                },
                {
                    "FieldName": "TransactionData1",
                    "FieldType": 0,
                    "IsRequired": false,
                    "Text": "Invoice Field",
                    "Validation": "",
                    "ValidationMessage": "",
                    "Value": ""
                }
            ],
            "Events": [
                {
                    "Date": "/Date(1709762513907-0600)/",
                    "Description": "Check Decision Performed"
                },
                {
                    "Date": "/Date(1709762513907-0600)/",
                    "Description": "Created"
                }
            ],
            "IQAStatus": "Nothing",
            "ItemReference": "I:GPXXWH5",
            "ProcessingStatus": null,
            "ProcessingStatusDescription": null,
            "Status": "ItemStatus04",
            "StatusDescription": "Created",
            "TransactionReferenceNumber": null
        },
        {
            "Amount": 5.0000,
            "BatchReference": "B:3YYTYV1",
            "Customer": null,
            "DataFields": [
                {
                    "FieldName": "TransactionId",
                    "FieldType": 0,
                    "IsRequired": false,
                    "Text": "Transaction Number",
                    "Validation": "",
                    "ValidationMessage": "",
                    "Value": "efc13ad6-bb8e-4bbb-8786-8fbe341909d1-1"
                },
                {
                    "FieldName": "TransactionData1",
                    "FieldType": 0,
                    "IsRequired": false,
                    "Text": "Invoice Field",
                    "Validation": "",
                    "ValidationMessage": "",
                    "Value": ""
                }
            ],
            "Events": [
                {
                    "Date": "/Date(1709763016413-0600)/",
                    "Description": "Check Decision Performed"
                },
                {
                    "Date": "/Date(1709763016413-0600)/",
                    "Description": "Created"
                }
            ],
            "IQAStatus": "Suspect",
            "ItemReference": "I:JSLYWH5",
            "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.

note

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, we have covered 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 has 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 necessary.
    • You are certain that the transaction is not really a duplicate and you need to process it. 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.