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	Data Exchange Request Field Names	Data Exchange Response Field Names

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

1 Endpoints
- 1.1 GetInfo
2 Encryption
- 2.1 Encryption Keypair
- 2.2 Create the JWE
- 2.3 Request the Header
3 Data Exchange Request Field Names
- - 3.1.1 Payload
- 3.2 How to generate a Signature value?
  - - 3.2.1.1 SHA-256 Example
    - 3.2.1.2 SHA-512 Example
  - 3.2.2 Sample Request Messages
    - 3.2.2.1 With Card Brand
    - 3.2.2.2 Without Card Brand
  - 3.2.3 Sample Request Message (Encrypted)
4 Data Exchange Response Field Names
- 4.1 Payload
  - 4.1.1 Account Object
  - 4.1.2 Issuer Object
- 4.2 Sample Response Message
5 Error Scenarios

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: 2024-12-13T13:38:12.022Z 
Milliseconds Since Epoch: 1734097092022
ApiKey: example_secret_api_key
Signature: TBLXrSqbwFIvkCz1vBr+bBpGcUpYhJb/Hl+a2H/dleg=

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: ReferenceId Issuer object 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

Error Scenarios

HTTPS Status Codes	Error Number	Description	Recommendation

HTTPS Status Codes	Error Number	Description	Recommendation
200	1	`"Message":"Unsupported Algorithm. Please sign your request with a supported algorithm."`	Check to see if the signature algorithm is invalid, wrong, or missing.
200	1000	`"ErrorDescription":"An error has occurred in the service"`	This could be triggered by a missing OrgUnitId or missing payload, if not then reach out to support.
200	1000	`"ErrorDescription":"Error processing request. We have encountered an unexpected error."`	Reach out to support.
200	1001	`"Message":"Not authorized to access this request."`	The OrgUnitId does not have permission to send this request.
200	1003	`"Message":"Invalid request. Please check your formatting."`	Check to see if the request message is missing any fields required fields.
200	1010	`"Message":"Invalid Signature. Your request contains an invalid signature."`	The Signature is either missing or invalid for the API identifier and timestamp. Generate a new signature.
200	1011	`"Message":"Signature expired. Your signature is not within the acceptable time frame."`	The signature needs to be generated again.
200	2000	`"ErrorDescription":"AccountNumber is not valid"`	Check that the account number is the correct length and does not include invalid characters.
200	3000	`"ErrorDescription":"Error during decryption"`	Confirm JWE steps including formatting, and ensuring the header is valid, if everything looks correct reach out to support.
415	N/A	<empty>	Invalid Content-Type in the Content-Type header. Should be "application/json" for the unencrypted endpoint.
400	N/A	<empty>	Invalid OrgUnitId or JSON.