Data Exchange API

Owned by Suyash Somani
Last updated: Aug 12, 2024 by Kayleigh LaSalle
5 min read

The Data Exchange API (DX API) securely exchanges data between systems providing merchants additional data and real-time insights during the transaction process. The DX API call happens prior to authentication giving merchants visibility of issuer behavior to determine an authentication strategy.

Endpoints

Connection URLs for Staging and Production:

Environment

URL

Environment

URL

Staging

https://dataexchangestag.cardinalcommerce.com

Production

https://dataexchange.cardinalcommerce.com

GetInfo

Path

Request Level Encryption

Request Object

Response Object

Path

Request Level Encryption

Request Object

Response Object

/V1/AccountNumber/GetInfo

No


Data Exchange Request Field Names


Data Exchange Response Field Names

/V1/AccountNumber/EncryptedGetInfo

Yes

Encryption

When using the /EncryptedGetInfo endpoint, merchants should follow the below guidelines for successful implementation:

Encryption Keypair

The encryption/decryption keypairs are generated by Cardinal/Visa with the following parameters:

  • RSA 2048 bits:

    • RSA is a public-key encryption algorithm.

  • Signature Algorithm:

    • SHA256WITHRSA is a signature algorithm that uses SHA-256 for hashing and RSA for signing.

Create the JWE

When encrypting a JSON request be sure to wrap with JWE (JSON Web Encryption). Use your preferred encryption library to build the JWE:

  • Algorithm: RSA-OAEP (for instance, in Java, use JWEAlgorithm.RSA_OAEP_256)

  • Method: A256GCM (for instance, in Java, use EncryptionMethod.A256GCM)

The kid header should be a value provided by Cardinal/Visa. This is not the same as the CN. If the kid is invalid or inaccurate, a decryption error will occur.

Here is a sample request body for the /EncryptedGetInfo endpoint:

eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2Iiwia2lkIjoiZGF0YWV4Y2hhbmdlLXBrZS1tcGktY2MtMjA0OHNoYTItc3RhZy0yMDIzIn0.P1o7HjKuz6GTqQ21wtsmwSlxRgFedSuXadLBp3RRqdUWzYUX19ZxvtWeH3UfuCBHDKEytJKGifynhDorXicOKXuxMV9z3H_vWagbnPVgq5VFAK3tIAJNOR-gQsLCyrWezDN_kx8kbIhA_HZ_YN-INxXLp_QLCPCJJWLj8YdlqHBI3K6_JveSo377oNImGdWzePOvwnTQ7_t1LXsTuQy7K4T5noOGXnfmsCImyR2EQU8pKe-ot3ANCO3yeEsc95p1gG_KYl-Z1n9D26j_c5_6zo_LA3c-NnwEREYkQel1i_PENjbjabtBqHC4kaEfIom0yEvuPlzHcXVhoVfY3oX7RA.6MGunjUnZE7H-gWI87EXfg.d6a7dfE50cvS2A7oHHcl-0Yl4flnlEEhWWsjWtad2B5zpk_zj9LO5EHEGofInJjkfGYOsRWskFThxdpU797CVHfXMqf9jiN9CZlr0cEs8-qr1jpkKQl55J-i8i31CdR2HQhpY4z9JWpPcgcFyWfm4bHU7wKxHjWGda7tqd6qepWM2NwmdB1DjvI6Zmu_OxSTSGrAxX6Ux3LibGQ3-4IFFZaGDHibwZVQG1iqDSSOh7hPV3x9YnLYrQ7xc40ZqU8Xu2Uj1bFAS0oXBE-yBfv-x3pIOfIR0AfQOugwK72fHGb3e-Yg2ru60OlWH9J8RnahVpKimLF6gxCj4GlQT6SmE-UNG3z8pQxFCc10Ih-XVto.uYxzenPvUZ5JDC-gZlVzYw

Here is the decoded sample header:

{ "alg": "RSA-OAEP-256", "enc": "A128CBC-HS256", "kid": "dataexchange-pke-mpi-cc-2048sha2-stag-2023" }

Request the Header

The Content-Type header should be application/jose in the POST message request for the Data Exchange API

Data Exchange Request Field Names

Field

Type

Required

Description

Field

Type

Required

Description

Signature

Number

Y

A mathematical scheme for verifying the authenticity of digital messages or documents.

See examples below for generating the Signature value.

Timestamp

String or Number

Y

This value can be an ISO 8601 format or, Unix Epoch Time milliseconds in numeric format.

Example: 2024-07-21T17:32:28Z or, 1709659521000

Identifier

String

Y

API Key Identifier or Name value

Algorithm

String

Y

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

  • SHA-256

  • SHA-512

  • Although DXAPI supports SHA-512, the integrator should be aware that the subsequent /Collect call cannot support SHA-512.

OrgUnitId

String

Y

Processor/Merchant level OrgUnitId

Payload

Object

Y

The Payload for the Data Exchange request will contain an AccountNumber where full Account Number needs to be passed.

Payload

Field

Type

Required

Description

Field

Type

Required

Description

AccountNumber

String

Y

The account number to profile or the network tokens. Account number must be the full PAN of the cardholder between 13-19 digits.

Do not send a partial PAN in this field.

CardBrand

String

C

 

Type of cards used for purchase.

Possible Values:

CB - Cartes Bancaires

UPI - UnionPay International

ITMX - Interbank Transaction Management and Exchange

EFTPOS - eftpos Australia

MADA - Saudi Arabian Monetary Authority

AcquirerCountryCode

String

C

Issuers need to be aware of the acquirer's country code when the acquirer country differs from the merchant country. This field is required for a merchant acquiring in India and the European Economic Area (EEA).

This should be in alignment with ISO 3166-1.

How to generate a Signature value?

Listed below are the two supported methods of generating a Signature value.

SHA-256 Example

Timestamp: 2019-01-14T20:42:13.216Z Milliseconds Since Epoch: 1547498533216 ApiKey: 13f1fd1b-XXXX-XXXX-XXXX-ca61878f2a44 Signature: wpGKFbhcBl+8JLVXGP0QqBooK6dtLBv9bYtI15NXL1U= Generate Signature: Signature = SHA-256(Unix Epoch Time in Miliseconds + ApiKey)

SHA-512 Example

Sample Request Messages

With Card Brand

Without Card Brand

Sample Request Message (Encrypted)

Data Exchange Response Field Names

Field

Type

Required

Description

Field

Type

Required

Description

ErrorNumber

String

Y

Application error number. A non-zero value represents the error encountered while attempting the process the message request.

ErrorDescription

 String

 Y

Application error description for the associated error number.

Some Possible Values:

  • 0: Success (Not an Error)

  • 2000: AccountNumber is not valid

  • 1000: An error has occurred in the Service

RequestId

String

Y

A request identifier returned back from Cardinal.

Payload

Object

 Y

The Payload for the Data Exchange API response will contain:

  1. ReferenceId

  2. Issuer object

  3. Account object

Payload

Field

Type

Required

Description

Field

Type

Required

Description

Account

Object

Y

Indicates information related to the Account.

Issuer

Object

Y

Indicates information related to the Issuer.

ReferenceId

 String

 Y

This identifier represents the DeviceDataCollection session that has been started and must be passed in the Authentication JWT when invoking the DeviceDataCollectionUrl.

Account Object

Field

Type

Required

Description

Field

Type

Required

Description

LastFour

String

Y

Represents the last four numbers of the AccountNumber field passed on the Data Exchange API request.

CardBrand

 String

C

Type of card used for the purchase.

Possible Values:

  • AMEX

  • CB

  • DISCOVER

  • EFTPOS

  • ELO

  • ITMX

  • JCB

  • MADA

  • MASTERCARD

  • UPI

  • VISA

Issuer Object

Conditional fields in this table are only present when SupportedVersions is found.

Field

Type

Required

Description

Field

Type

Required

Description

SupportedVersions

Array of Objects

C

Indicates what EMV 3DS versions are supported by the Issuer, and what authentication options are supported for each listed version.

SupportedVersions.Version

String

C

Specifies all the active 3DS protocol versions supported by the Issuer ACS.

SupportedVersions.Capabilities

Array

C

Provides information for each capabilities array, which indicates the authentication options an Issuer supports for the given EMV 3DS version.

SupportedVersions.MethodURLPresent

Boolean

C

Indicates whether there is a 3DS Method associated with the Issuer Range

Sample Response Message