Skip to main content

RDA Authentication Guide

Introduction​

RDA Web Service authentication is handled with a security token which must be included in all authenticated requests. The security token is first obtained using the Authenticate method. This is the only web service request in the RDA workflow 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 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.

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 store 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 EPS Tech Integrations team.

Getting Started​

Here’s what you’ll do in this guide

  • Authenticate a customer into the RDA web service workflow

Prerequisites needed before continuing

  • You will need to obtain a shared secret if you are going to be using 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.
  • Download the RDA Web Service WSDL file from the Downloads page

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 there has been 15 minutes of no activity. After 15 minutes the most recent security token will have expired and a new authenticate request will be needed.

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.

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 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.
  • 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 integrators system for hashing. NOT for passing in the request.
  • HomeBankingID - 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.
  • SaltValue - Shared Salt value to make the hash unique.
  • Timestamp - Current Date time of the SSO authentication and 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-xxx)/ for JSON requests: (e.g., /Date(1560817240000-500)/). All timestamps must be converted to Central Time.

Example hash and resulting string​

The string values must be concatenated in this order: HomeBankingId + 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 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 the hash calculation for both XML and JSON requests and must also be converted to Central Time.

Example SSO Authenticate JSON Request:​

{
    "Credentials":{
        "__type":"SSOCredentialsSHA256:#JackHenry.Eps.Mobile.RDA",
        "FIIdentifier":"5678",
        "Hash":" A189729c2292d323131a5c14cf351f3fa8507928d3f8904f9c9eee9b2c5e3b291",
        "HomeBankingId":"1234",
        "SaltValue":"xyz",
        "Timestamp":"/Date(1560817240000-500)/",
        "PhoneKey":"1"
    },
    "DeviceTracking":{
        "AppBundleId":"testbundleid",
        "AppVersion":"1.0",
        "DeviceModel":"android",
        "DeviceSystemName":"testuserandroid",
        "DeviceSystemVersion":"1.0",
        "Vendor":"Your Company Name Here"
    },
    "RequestDate":"/Date(1560817240000)/",
    "RequestId":"123456789"
}

Example SSO Authenticate JSON Response:​

{
    "RequestId" : "123456789",
    "Result" : 1,
    "ResultCode" : null,
    "ResultMessage" : null,
    "ValidationResults" : [ ],
    "Credentials" : {
        "SecurityToken" : "365926065:175645:3631503214:175645:637668020662806815:tlDQomEazT4w+uJbuLIX7YEsQc3WsRUg125DjLGNGSGEn1zsgjDqDQ:6:0:4096:ed146458ac6543708f139641d6c59cdd:None"
    },
    "PromptTermsAndConditions" : false
}

Handling Errors and Failed Requests​

  • RDA AuthenticateSSO Failure - This can happen for multiple reasons and the most common 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 not enrolled, please reach out through your normal support channels for assistance and refer to Authentication in the RDA web service API Reference.
"Code" : "Auth-1001",
"Message" : "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. Either SHA 256 or SHA 512.
"Code" : "Cred 1232",
"Message" : "Hash Length is Invalid"

Next Steps​

  • Review the API Reference - This guide is just 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 so if this one doesn’t cover what you are looking for, give another guide a try.
  • 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.