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.
Connection URLs for Staging and Production:
Environment | URL |
---|---|
Staging | |
Production |
Path | Request Level Encryption | Request Object | Response Object |
---|---|---|---|
/V1/AccountNumber/GetInfo | No | ||
/V1/AccountNumber/EncryptedGetInfo | Yes |
When using the /EncryptedGetInfo endpoint, merchants should follow the below guidelines for successful implementation:
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.
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 |
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" } |
The Content-Type header should be application/jose in the POST message request for the Data Exchange API
Field | Type | Required | Description |
---|---|---|---|
Signature | Number | Y | A mathematical scheme for verifying the authenticity of digital messages or documents. |
Timestamp | String or Number | Y | This value can be an ISO 8601 format or, Unix Epoch Time milliseconds in numeric format. Example: |
Identifier | String | Y | API Key Identifier or Name value |
Algorithm | String | Y | The hashing algorithm used to generate the Signature value. Valid options include:
|
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. |
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.
| |
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. |
C=Conditional |
Listed below are the two supported methods of generating a Signature value.
|
Timestamp: 2019-01-14T20:42:13.216Z Milliseconds Since Epoch: 1547498533216 ApiKey: 13f1fd1b-XXXX-XXXX-XXXX-ca61878f2a44 Signature: SBF4wmV5LPCsb7Em+Yfa2RB4xtohV8s2ffYArhPUrZqjEsgUjbuVzBPyhgYma5x71T5y7dIHPJHE2uqL3Vp0Hg== Generate Signature: Signature = SHA-512(Unix Epoch Time in Miliseconds + ApiKey) |
Sample Request Messages | |
With Card Brand
| |
Without Card Brand
|
Sample Request Message (Encrypted) | |
|
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:
|
RequestId | String | Y | A request identifier returned back from Cardinal. |
Payload | Object | Y | The Payload for the Data Exchange API response will contain:
|
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. |
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:
|
Conditional fields in this table are only present when SupportedVersions is found.
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 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. 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. |
Sample Response Message | |
|