- Created by Suyash Somani, last modified by Walt Handloser on Feb 10, 2022
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
« Previous Version 12 Next »
The Data Exchange API (DX API) provides merchants additional data and real-time insights during the transaction process, prior to authentication even taking place. This helps merchants have greater visibility into issuer behavior, technical support, and performance, in order to determine the most suitable authentication strategy for their business.
Endpoints
Connection URLs for Staging and Production:
Environment | URL |
---|---|
Staging | |
Production |
GetInfo
Path | Request Object | Response Object |
---|---|---|
/V1/AccountNumber/GetInfo |
Data Exchange Request Field Names
Field | Description | Required |
---|---|---|
Base64 encoded SHA256 of SHA512 value that is a hash of timestamp, TransactionId and API Key | Y | |
Timestamp | This value can be a standard date/time format or, Java Epoch time in milliseconds Example: | Y |
Identifier | API Key Identifier or Name value | Y |
Algorithm | The hashing algorithm used to generate the Signature value. Valid options include:
| Y |
TransactionId | Alphanumeric value to uniquely identify the request. Will be echoed back on the response. 5-55 characters in length | O |
OrgUnitId | Processor/Merchant level OrgUnitId | Y |
Payload | The Payload for the Data Exchange request will contain an AccountNumber where the Card BIN to full Account Number will be passed. | Y |
Payload
Field | Description | Required |
---|---|---|
AccountNumber | The account number to profile. Must be full PAN of the cardholder. | Y |
CardType | Type of cards used for purchase. Possible Values: CB - Cartes Bancaires UPI - UnionPay International The CardBrand field is required for CB and UPI. It should not be included for any other card brands. |
C |
How to generate a Signature value?
SHA-256 Example
Timestamp: 2019-01-14T20:42:13.216Z Milliseconds Since Epoch: 1547498533216 TransactionId: 07643622 ApiKey: 13f1fd1b-XXXX-XXXX-XXXX-ca61878f2a44 Signature: wpGKFbhcBl+8JLVXGP0QqBooK6dtLBv9bYtI15NXL1U= Generate Signature: Signature = SHA-256(Epoch + TransactionId + ApiKey) where, TransactionId is optional. |
SHA-512 Example
Timestamp: 2019-01-14T20:42:13.216Z Milliseconds Since Epoch: 1547498533216 TransactionId: 07643622 ApiKey: 13f1fd1b-XXXX-XXXX-XXXX-ca61878f2a44 Signature: SBF4wmV5LPCsb7Em+Yfa2RB4xtohV8s2ffYArhPUrZqjEsgUjbuVzBPyhgYma5x71T5y7dIHPJHE2uqL3Vp0Hg== Generate Signature: Signature = SHA-512(Epoch + TransactionId + ApiKey) where, TransactionId is optional. |
Sample Request Messages |
With Card Brand{ "Algorithm": "SHA-256", "Identifier": "59c2745f2f3e7357b4aa516a", "OrgUnitId": "564cdcbcb9f63f0c48d6387f", "Signature": "4LeQr8F0bzh0f7XKesH9D7EIjT+s/Inx+eO1TrwMKNI=", "Timestamp": "2017-07-21T17:32:28Z", "TransactionId": "asdf123", "Payload": { "AccountNumber": "4000000000000002", "CardType": "CB" } } |
Without Card Brand{ "Algorithm": "SHA-256", "Identifier": "59c2745f2f3e7357b4aa516a", "OrgUnitId": "564cdcbcb9f63f0c48d6387f", "Signature": "4LeQr8F0bzh0f7XKesH9D7EIjT+s/Inx+eO1TrwMKNI=", "Timestamp": "1626113191", "TransactionId": "asdf123", "Payload": { "AccountNumber": "4000000000001000" } } |
Data Exchange Response Field Names
Field | Description | Type | Required |
---|---|---|---|
RequestId | A request identifier returned back from Cardinal | String | Y |
ErrorNumber | Application error number. A non-zero value represents the error encountered while attempting the process the message request. | String | Y |
ErrorDescription | Application error description for the associated error number. Possible Values:
|
String |
Y |
Payload | The Payload for the Data Exchange API response will contain:
|
Payload Object |
Y |
Payload
Field | Description | Type | Required |
---|---|---|---|
ReferenceId | This identifier represents the DeviceDataCollection session that has been started and must be passed in the Authentication JWT when invoking the DeviceDataCollectionUrl |
String |
Y |
Issuer | Indicates information related to the Issuer | Issuer Object | Y |
Account | Indicates information related to the Account | Account Object | Y |
RequestId | Alphanumeric value that was passed in TransactionId on the request | String | Y |
Issuer Object
Field | Description | Type | Required |
---|---|---|---|
SupportedVersions | Encompasses Issuer information based on the PRes received from each card network. | Array of Objects | Y |
SupportedVersions.Version | Specifies all the active 3DS protocol versions supported by the Issuer ACS | String | Y |
SupportedVersions.Capabilities | Provides information related to the Issuer Capabilities supported for each Version. | Array | O |
SupportedVersions.MethodURLPresent | Indicates whether there is a 3DS Method associated with the Issuer Range In case, MethodUrlPresent flag returns ‘false’, merchant can choose to skip the /Collect call if they are able to capture the required browser fields themselves and directly proceed with the Lookup Request. | Boolean | Y |
Account Object
Field | Description | Type | Required |
---|---|---|---|
LastFour | Represents the last four numbers of the AccountNumber field passed on the Data Exchange API request. | String | Y |
CardBrand | Type of card used for the purchase. Possible Values: Visa |
String |
Y |
Sample Response Message |
{ "ErrorNumber": 0, "ErrorDescription": "Success", "RequestId": "bc7af47b-a48b-4a20-a98e-cb2fc220329c", "Payload": { "Account": { "CardBrand": "Visa", "LastFour": "0094" }, "Issuer": { "SupportedVersions": [ { "Version": "2.1.0", "Capabilities": [ "AuthenticationAvailableAtACS" ], "MethodURLPresent": true }, { "Version": "2.2.0", "Capabilities": [ "AuthenticationAvailableAtACS", "DecoupledAuthentication", "DataOnly", "DelegatedAuthentication", "DelegateTrustedAuthentication" ], "MethodURLPresent": true } ] }, "ReferenceId": "51ca6679-12ed-47c4-8982-1a29e10d4587" } } |
- No labels