Data Exchange API

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

GetInfo

Path

Request Object

Response Object

Path

Request Object

Response Object

/V1/AccountNumber/GetInfo

Data Exchange Request Field Names

Data Exchange Response Field Names

 

 

Data Exchange Request Field Names

Field

Description

Required

Field

Description

Required

Signature

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: 2017-07-21T17:32:28Z or, 1626113191

Y

Identifier

API Key Identifier or Name value

Y

Algorithm

The hashing algorithm used to generate the Signature value. Valid options include:

  • SHA-256

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

Field

Description

Required

AccountNumber

The account number to profile. Must be full PAN of the cardholder.
(Network tokens must be passed in this field)

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

1 2 3 4 5 6 7 8 9 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

1 2 3 4 5 6 7 8 9 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

1 2 3 4 5 6 7 8 9 10 11 12 { "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

1 2 3 4 5 6 7 8 9 10 11 { "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

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:

  • 0 : Success (Not an Error)

  • 2000 : AccountNumber is not valid

  • 1000 : An error has occurred in the Service

 

 

String

 

 

Y

Payload

The Payload for the Data Exchange API response will contain:

  1. ReferenceId

  2. Issuer object

  3. Account object

 

 

Payload Object

 

 

Y

Payload

Field

Description

Type

Required

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

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

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
Mastercard
Amex
CB
JCB
Discover
ELO
UPI

 

 

 

 

String

 

 

 

 

Y

Sample Response Message

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 { "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" } }