Versions Compared

Old Version 12

changes.mady.by.user Walt Handloser

Saved on

compared with

New Version Current

changes.mady.by.user Kayleigh LaSalle

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

The Data Exchange API (DX API) provides 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 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 businessgiving merchants visibility of issuer behavior to determine an authentication strategy.

Endpoints

Connection URLs for Staging and Production:

Environment

URL

Staging

https://dataexchangestag.cardinalcommerce.com

Production

https://dataexchange.cardinalcommerce.com

GetInfo

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)

Note

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:

Code Block
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:

Code Block
{
"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

Table of Contents

Anchor
DataExchangeRequest
DataExchangeRequest
Data Exchange Request Field Names

FieldDescription

Type

Required

Description

Signature

Base64 encoded SHA256 of SHA512 value that is a hash of timestamp, TransactionId and API Key

Y

Timestamp

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 a standard date/time an ISO 8601 format or, Java Unix Epoch time in millisecondsTime milliseconds in numeric format.

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

Identifier

String

Y

Identifier

API Key Identifier or Name value

Algorithm

String

Y

Algorithm

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

  • SHA-256

Y

  • SHA-512

TransactionId

Alphanumeric value to uniquely identify the request. Will be echoed back on the response.

5-55 characters in length

O

OrgUnitIdOrgUnitId

String

Y

Processor/Merchant level OrgUnitId

Payload

Object

Y

Payload

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

Y

Payload

FieldDescription

Type

Required

Description

AccountNumber

String

Y

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

Note

Do not send a partial PAN in this field

)

.

CardBrand

YString

CardType

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

Note

The CardBrand field is required for CB and UPI, UPI, ITMX, EFTPOS and MADA. It should not be included for any other card brands.

 

 

 C

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.

Info

C=Conditional

Anchor
Signature
Signature
How to generate a Signature value?

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

SHA-256 Example

Code Block
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(Unix Epoch Time +in TransactionIdMiliseconds + ApiKey)
where, TransactionId is optional.

SHA-512 Example

Code Block
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(Unix Epoch
+
Time in
TransactionId
Miliseconds + ApiKey)
where, TransactionId is optional.
Sample Request Messages
With Card Brand
 Code Block
languagejson
{
  "AlgorithmSignature": "SHA-256"gFM3PI3JHoz9ammwXmLryRi7Mq+lxCbOTOFCyd3aNSM=",
  "IdentifierTimestamp": "59c2745f2f3e7357b4aa516a"2024-02-21T20:12:39.307Z",
  "OrgUnitIdIdentifier": "564cdcbcb9f63f0c48d6387f59c282d02f3e7357b4aa6f13",
  "SignatureOrgUnitId": "4LeQr8F0bzh0f7XKesH9D7EIjT+s/Inx+eO1TrwMKNI=59c2745f2f3e7357b4aa516a",
  "TimestampAlgorithm": "2017-07-21T17:32:28ZSHA-256",
  "TransactionIdOrgUnitId": "asdf12359c2745f2f3e7357b4aa516a",
   "Payload": {
      "AccountNumber": "400009******0800",
"4000000000000002      "CardBrand":"CB",
      "CardTypeAcquirerCountryCode": "CB840"
  }
}
Without Card Brand
 Code Block
languagejson
{
  "AlgorithmSignature":"KmL2SLBeTRRU9TlxA6XfnAYg5yWn1QwEO0GL1RtP8mg=",
"SHA-256"Timestamp":"2024-02-21T20:10:20.872Z",
  "Identifier": "59c2745f2f3e7357b4aa516a59c282d02f3e7357b4aa6f13",
  "OrgUnitIdAlgorithm": "564cdcbcb9f63f0c48d6387fSHA-256",
  "SignatureOrgUnitId": "4LeQr8F0bzh0f7XKesH9D7EIjT+s/Inx+eO1TrwMKNI=59c2745f2f3e7357b4aa516a",
  "TimestampPayload": "1626113191",{
     "TransactionIdAccountNumber": "asdf123400009******0800",
  "Payload":
{     "AccountNumberAcquirerCountryCode": "4000000000001000840"

 }
}
Sample Request Message (Encrypted)
 Code Block
languagejson
eyJraWQiOiJkYXRhZXhjaGFuZ2UtcGtlLW1waS1jYy0yMDQ4c2hhMi1wcm9kLTIwMjMiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAifQ.tmCD4Euz5gl64AjrX8vULyg4_YRJSu0vbKDCHq-1MJ3uhtikIxU5_TuQ4muFW2APXq7xbvBdmNulIZg0zEpTSZrMD6rcpXkO4b0vCvNz-WIrL6D2rOxD82rmJRnKktgHdi1-AKeBil9SVV1sqfVXGgJ0EFyuMP38TK8pQW5PKIcHt_KyiIj2AeCt6hR2yc83ZkWR_IHj4EMC-xT2PNyVOu7rXDTW6F-SlHqWWIQ5DaIvk-N7LCoO4o-TGHn0-mUKti42H_jMUixpb9tPf514PH3mhOxlqr2kzTrn43aQO2z17TSyoeZmsLtnx1nNY9uMUbqF7sl2YreKFHCQROr8-w.4TUjSAhAwk4kxz7l.jIpzAp6vLTSpVeU-FGXygElSe11chFhBl7f3kDCXcTSAgE2p-0ADP_u2cUKFoKYsWM1-i1lKYt-hAhz2VR0Ox1ccezAFh5CCGZt02C77Z6ZyxJ47lTbk6NoPyTdWZWOZjnM3BWV9IMFym1wbsY6JHeyInM5_ziScUynGPcONoTUv-h6Qg9FvDLkNhHnExjEWtX_6lQuj3rkyKHsobqdpqQd_9v6BdaLMSiFz3OZ9thHhi5njzl_rfu1yyZD3Ym_wt3LYwheO7e8e-spVzElLy9te36kO84IYpiXV3a7g7E9vltpbm6RkI33tQ1elsW0eG9TWKxOn_bywPPbwBSxg9EyHbV5oBTOblWtMilWrLUg9uSchl7-AGpz4Is7j5e-RUY3_5tCrBlvNUR5Yg5NlS2Pa_FX-iq2i.w1DwqjKuDxkhHAE3s0VQnw
 Anchor
DataExchangeResponse
DataExchangeResponse
 Data Exchange Response Field Names
A request identifier returned back from Cardinal
Field
Description
Type
Required
RequestId
Description
ErrorNumber
String
Y
ErrorNumber
Application error number. A non-zero value represents the error encountered while attempting the process the message request.
String
ErrorDescription
Y String
ErrorDescription
 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
String
 
 
Y
Payload
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
Payload Object
Description
 
Account
 
Field
Description
Type
Required
Object
Y
Payload
Field
Description
Type
Required
SupportedVersions
Encompasses Issuer information based on the PRes received from each card network.
Array of Objects
Y
SupportedVersions.Version
ReferenceIdIndicates 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
 
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
.
Account Object
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
Description
Type
Required
LastFour
Represents the last four numbers of the AccountNumber field passed on the Data Exchange API request
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
String
.
Y
SupportedVersions.Capabilities
Array
C
Provides information related to the Issuer Capabilities supported for each Version.
Array
O
SupportedVersions.MethodURLPresent
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.
Boolean
Y
Account Object
.
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
 Code Block
languagejson
{
    "ErrorNumber": 0,
    "ErrorDescription": "Success",
    "RequestId": "bc7af47bb3933183-a48b48df-4a20409f-a98e94ff-cb2fc220329c12952364009b",
    "Payload": {
        "Account": {
            "CardBrand": "Visa",
            "LastFour": "0094"
        },
        "Issuer": {
            "SupportedVersions": [
                {
                    "Version": "2.1.0",
                    "Capabilities": [
                        "AuthenticationAvailableAtACS",
                        "DAF"
                    ],
                    "MethodURLPresent": true
                },
                {
                    "Version": "2.2.0",
                    "Capabilities": [
                        "AuthenticationAvailableAtACS",
                        "DecoupledAuthentication",
                        "DataOnly",
                        "DelegatedAuthentication",
                        "IssuerTRA",
                        "DelegateTrustedAuthenticationDAF"
                    ],
                    "MethodURLPresent": true
                }
            ]
        },
        "ReferenceId": "51ca6679-12ed-47c4-8982-1a29e10d4587"
    }
}