RDA Authentication Guide

Introduction

The JHA SmartPay Remote Deposit Anywhere™ (RDA) web service authentication is handled with a security token that must be included in the header of all authenticated requests. The security token is first obtained when you send a token request to a separate authentication endpoint. The token request includes user credentials that will allow the EPS system to validate and authenticate a user. If the token request is successful, a security token will be returned. This security token must be included each subsequent request to the RDA web service by sending it as a bearer token in the header of each request. The security token will expire after 15 minutes. After the token expires, a new security token will need to be obtained to continue using the web service.

Demo Merchant

You will receive a set of demo credentials and a demo merchant at the beginning of your integration and instead of a sandbox environment (endpoint), you will be coding/testing against this demo merchant in the live system. These demo credentials will only be valid for your non-processing demo merchant, which means that the transactions will process on our system but will not be sent out through the check clearing networks. At the completion of the API certification process, you will be provided your production credentials. For more information about the demo merchant, please speak with your Implementation Coordinator or the EPS Tech Integrations team.

Getting Started

Here’s what you’ll do in this guide

Authenticate a customer into the RDA web service workflow

Required prerequisites before you continue

• You will need to obtain a shared secret if you are going to use SSO authentication. You should receive this as part of your credential set from the Integrations team.
• You will need to first enroll a user into RDA using the RDA Admin enrollment process. See the RDA enrollment guide here.
• If you are using SOAP/XML, download the RDA Web Service WSDL file from the Downloads page.

When and How Often to Authenticate

Authentication should be used sparingly and should occur when a user first initiates deposit activities in the front-end application, meaning they either intend to make a deposit or view their deposit history. Once authenticated, you can use the security token for 15 minutes. After 15 minutes, the security token will have expired and a new token request will be required.

User Authentication Method

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

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. Using this method, you will send an HTML form using an HTTP POST request to the authentication endpoint (https://smartpay.profitstars.com/auth/connect/token). The request should be sent using the credentials below (the shared secret is only for generating the hash value and should not be sent in the request). Once the token has been generated, you will send it as a bearer token in the header of each subsequent request to the RDA web service.

note

All values described below are required.

NAME	DESCRIPTION
client_id	This identifies the authentication type. For SSO authentication, you can use the value MobileRDASSO.
grant_type	This indicates the type of credentials being granted. The value should be client_credentials.
scope	This is the scope of the request. The value should be apiaccess.
home_banking_id	A unique string value representing the individual that exists in the EPS platform to authenticate. This value is controlled by the FI or integrator and typically relates back to an online banking user value of some kind.
fi_identifier	A unique credential value provided by EPS that identifies the specific RDA entity for the FI. It is important to note that this value represents only a single RDA entity for the FI. An FI may have multiple RDA entities; therefore, this value will be unique and new for each new RDA entity that is boarded. It is not a true FI- or owner-level value.
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 following format: m/d/yyyy h:mm:ss tt. All timestamps must be converted to Central Time.
salt	Shared salt value to make the hash unique. This value is generated and supplied by you as the integrator.
hash	A unique string value. Hashed value (either SHA256 or SHA512) used for comparison.
type	This identifies the hash calculation type. Valid values are SHA256 and SHA512.
phone_key	This identifies the mobile device and should be unique to each mobile device accessing the system. This value is generated by you as the integrator.
shared secret	A unique string value generated and provided by EPS to be stored securely on the integrator's system for hashing. NOT for passing in the request.

Example hash and resulting string

The string values must be concatenated in this order: home_banking_id + timestamp + fi_identifier + SharedSecret + salt.

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 1: The hash must be in all lowercase as shown above.
NOTE 2: 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 both the token request and the hash calculation for both XML and JSON requests and must also be converted to Central Time.

Example SSO Authenticate Request:

client_id: "MobileRDASSO"
grant_type: "client_credentials"
scope: "apiaccess"
home_banking_id: "1234"
fi_identifier: "5678"
timestamp: "6/17/2019 7:20:40 PM"
salt: "xyz"
hash: "a189729c2292d323131a5c14cf351f3fa8507928d3f8904f9c9eee9b2c5e3b291"
type: "SHA256"
phone_key: "123test"

Example SSO Authenticate JSON Response:

{
    "access_token": "xxxxxxxxxxxxxxx",
    "expires_in": 900,
    "token_type": "Bearer",
    "scope": "apiaccess"
}

Using Access Token

Once you have been provided an access token by the RequestAccessToken response, you will set the Authorization header of the next RDA web service request with your access token as a bearer token. You will do this for each subsequent web service request to authenticate each request. The token lasts 15 minutes before expiring. After it expires, you will need to send a new request to the token endpoint for a new authentication token. See below for an example web service request.

Example Web Service Request:

• "Method": POST
• "Content-Type": application/JSON
• "Authorization": Set the Bearer Token in the authorization.

{
    "__type": "CreateBatchRequest:#JackHenry.Eps.Mobile.RDA",
    "RequestId": "1234test",
    "RequestDate": "/Date(1629199027219-600)/",
    "Credentials": {
        "__type": "TokenCredentials:#JackHenry.Eps.Mobile.RDA",
        "SecurityToken": null,
        "PhoneKey": null
    },
    "BatchNumber": "123test"
}

Handling Errors and Failed Requests

• RDA AuthenticateSSO Failure - This can happen for several reasons, the most common of which are a mismatched hash in the request, a timestamp that is out of sync, or the user is not enrolled. For any scenario other than the user is not enrolled, please reach out through your normal support channels for assistance.

{
    "error": "Authentication failed"
}

• RDA 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, e.g., either SHA 256 or SHA 512.

{
    "error": "Hash Length is Invalid"
}

• Invalid Client Error - This means that your client_id is incorrect. The client_id should be: MobileRDASSO.

{
    "error": "invalid_client"
}

• Invalid Scope Error - This means that your scope is invalid. The scope should be "apiaccess".

{
    "error": "invalid_scope"
}

• Invalid Request Error - This means that your HTTP request type is not valid. The token request endpoint only accepts an HTTP POST request.

{
    "error": "invalid_request"
}

• Unsupported Grant Type Error - This means that your grant_type is not valid. The grant_type should be "client_credentials".

{
    "error": "unsupported_grant_type"
}

Next Steps

• Review the API Reference - This guide is a starting point to show how to authenticate an RDA customer. Please review the API Reference to see all methods 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, be sure to 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.