Skip to main content

mRDC Authentication Guide

Introduction

mRDC Web Service authentication is handled with a security token that must be included in all authenticated requests. The security token is first obtained using the Authenticate method. This is the only web service request that does not require the security token. The Authenticate request includes user credentials that will allow the EPS system to validate and authenticate a user.

If the Authenticate request is successful, a security token will be returned. This security token must be included in the next web service request by assigning it to the Credentials field in the request. Each successful web service response will contain a new security token that must replace the security token used in the previous request and be included in the next web service request. In other words, each successful web service response (including the Authenticate response) will include a security token that must also be included in the next web service request. If the web service response is not successful, the last security token may be used in the next web service request until a successful web service response is returned with a new security token.

Getting Started

Task covered in this guide

  • Authenticate a customer into the mRDC web service workflow

Required prerequisites before you continue

  • You will need to obtain a shared secret if you are going to be using single sign-on (SSO) authentication. This should have been part of your demo credential set.
  • If you are going to be using SSO authentication you will need an active JHA SmartPay Business™ user and their UserNumber to connect.
  • If you are going to use store credentials authentication, make sure you have your Store Key, Store ID, and Entity ID (these should have already been provided to you).

Demo Merchant

mRDC Web Service authentication is handled with a security token that must be included in all authenticated requests. The security token is first obtained using the Authenticate method. This is the only web service request that does not require the security token. The Authenticate request includes user credentials that will allow the EPS system to validate and authenticate a user. If the Authenticate request is successful, a security token will be returned. This security token must be included in the next web service request by assigning it to the Credentials field in the request.

Each successful web service response will contain a new security token that must replace the security token used in the previous request and be included in the next web service request. In other words, each successful web service response (including the Authenticate response) will include a security token that also must be included in the next web service request. If the web service response is not successful, the last security token may be used in the next web service request until a successful web service response is returned with a new security token.

When to Authenticate and How Often

Authentication should be used sparingly and occur when a user first initiates deposit activities in the front-end application, meaning either they intend to make a deposit or view their deposit history. Once authenticated, since a new security token is returned with each request/response thereafter, you should not authenticate the user again unless the session has 15 minutes of no activity. After 15 minutes, the most recent security token will have expired and a new authenticate request will be necessary.

Authentication Methods
SSO Authentication Method

Integrators who have an already authenticated user in their platform and want to connect to a matching user on the EPS side—leveraging all of the stored EPS permissions and entitlements for that user—will want to use the SSO method of authentication.

The SSO credentials consist of the properties shown below.

note

All values described below are required.

  • FIIdentifier - A unique credential value provided by EPS that identifies the specific merchant entity. It is important to note that this value represents only a single merchant entity under an owning entity and this value will be unique and new for each merchant entity that is boarded. It is not a true FI or owner level value.
  • Hash - A unique string value. Hashed value (either SHA256 or SHA512) used for comparison.
  • Shared Secret - A unique string value generated and provided by EPS to be stored securely on the integrator's system for hashing. It is NOT used for passing in the request.
  • UserNumber - A unique string value representing the individual that exists on the EPS platform to authenticate. This value is controlled by the admin of the merchant entity or owning entity, and it typically relates back to an online banking user value of some kind.
  • SaltValue - Shared Salt value to make the hash unique.
  • Timestamp - Current date and time of the SSO authentication that must be within 10 minutes of the EPS server time. Required to be in the format yyyy-mm-ddThh:mm:ss for non-JSON requests: (e.g., 2019-06-17T19:20:40). Required to be in the format /Date(xxxxxxxxxx-xxxx)/ for JSON requests: (e.g., /Date(1560817240000-0500)/). All timestamps must be converted to Central Time.
note

The timestamp used for the hash calculation should be in the format m/d/yyyy h:mm:ss tt. (e.g. 6/17/2019 7:20:40 PM). This timestamp format is used in the hash calculation for both XML and JSON requests and must also be converted to Central Time.

Example hash and resulting string

The string values must be concatenated in this order: CustomerNumber + Timestamp + FIIdentifier + SharedSecret + SaltValue.

Example values: 1234 + 6/17/2019 7:20:40 PM + 5678 + abcd1234 + xyz

Resulting string to hash using: 12346/17/2019 7:20:40 PM5678abcd1234xyz

Resulting hash using the SHA256 method: a189729c2292d323131a5c14cf351f3fa8507928d3f8904f9c9eee9b2c5e3b291

note

The hash must be in all lowercase as shown above.

Example SSO SHA256 Authenticate Request:

{
    "__type":"AuthenticateRequest:#JackHenry.Eps.Mobile.RDC",
    "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"
    },
    "RequestDate":"/Date(1692650646000-0500)/",
    "RequestId":"6S54FD652154654F154654S3D2F1SD3"
}

Example SSO SHA256 Authenticate Response:

{
    "RequestId": "6S54FD652154654F154654S3D2F1SD3",
    "Result": 1,
    "ResultCode": null,
    "ResultMessage": null,
    "ValidationResults": [],
    "Credentials": {
        "PhoneKey": "1",
        "SecurityToken": "String Content"
    },
    "MFA": null,
    "OwnerId": "OGRW5",
    "PromptTermsAndConditions": false
}
Store Credentials Method

Integrators who want to have full control over user entitlements and access that come from their system will want to use Store Credentials method of authentication. This allows all deposit activity to be submitted under one “user” set of credentials on the EPS side which means that there will be no need to keep up with multiple user logins in EPS. Since all activity using this method takes place under one user, deposit history using the GetBatches and GetItems methods will be grouped together. Typically, integrators using this method employ their own method for filtering deposit history to their users so that they see the right data.

The store credentials consist of the properties shown below.

note

All values described below are required.

  • StoreID - A unique numerical value provided by EPS for authentication. The storeID can be unique to each individual merchant, or a primary storeID can be assigned at the Partner/owner level.

  • StoreKey - A unique string value provided by EPS for authentication. The password corresponds with the storeID.

  • EntityID - A unique numerical value provided by EPS. This represents the merchant entity on the EPS side to process transactions under.

Example Store Credentials Authenticate Request:

{
    "__type" : "AuthenticateRequest:#JackHenry.Eps.Mobile.RDC",
    "Credentials" : {
        "__type" : "StoreCredentials:#JackHenry.Eps.Mobile.RDC",
        "EntityId" : "67890",
        "StoreId" : "123456",
        "StoreKey" : "You Store Key Here"
    },
    "DeviceTracking" : {
        "__type" : "DeviceTracking:#JackHenry.Eps.Mobile.RDC",
        "AppBundleId" : "test",
        "AppVersion" : "1.0",
        "DeviceSystemName" : "test",
        "DeviceSystemVersion" : "10",
        "DeviceModel" : "test",
        "Vendor" : "Your Company Name Here"
    },
    "RequestId" : "test1",
    "RequestDate" : "/Date(1600107271)/"
}

User Credentials and MFA Credentials Methods

Third-party applications will generally not want to use these methods for authentication. Please speak with the EPS Tech Integrations team if you are considering using these methods.

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 of which are a mismatched hash in the request, a timestamp that is out of sync, or the user has not been created or enabled. Please reach out through your normal support channels for assistance should this error occur, and refer to Authentication in the mRDC web service API Reference.
"Code" : "Auth-2003",
"Message" : "Failed to Authenticate"
  • mRDC AuthenticateSSO Invalid Hash Length Failure: This error response will be returned if the hash being sent in the request is an invalid length. Check to make sure you are using the proper hashing algorithm that is compatible for the request type, either SHA 256 or SHA 512.
"Code" : "Cred-2232",
"Message" : "Hash Length is Invalid"
  • mRDC Authenticate Store Credentials Failure: This can happen for multiple reasons, but the most common are either incorrect credentials (Store Key, Store ID, Entity ID) or the merchant entity doesn’t have the correct permissions enabled for mRDC access. These errors cannot be retried, as multiple failures will result in a complete lockout. Check your credentials and verify that nothing has changed on your end before proceeding. Login failures often require customer support assistance to resolve, so please contact us through your normal support channels if this occurs.
"Code" : "Auth-2003",
"Message" : "Failed to Authenticate"
Next steps

  • Review the API Reference - This guide is a starting point to show how to authenticate an mRDC customer. 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.