Versions Compared

Key

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

This is the Encrypted Data Exchange API endpoint for information on how to encrypt see our Data Exchange API integration guide. Included on this page are all the required fields and objects to run a registration check for either an enrollment or authentication flow using VPPS.

Connection URL’s

Request

Signature Number

Status
colourRed
titlerequired

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


TimeStamp String or Number

Status
colourRed
titlerequired

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

Status
colourRed
titlerequired

API Key Identifier or Name value


OrgUnitId String

Status
colourRed
titlerequired

Processor/Merchant level OrgUnitId


Algorithm String

Status
colourRed
titlerequired

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

  • SHA-256

  • SHA-512


Payload Object

Status
colourRed
titlerequired

The Payload containing fields and a payment object.

Expand
titlePayload definitions

AccountNumber String

Status
colourRed
titlerequired

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

Note

Do not send a partial PAN in this field.


CardBrand String

Status
colourRed
titlerequired

Types of cards used for purchase. Currently VISA is the only supported card brand for FIDO.


ReferenceID String

Status
colourRed
titlerequired

A Cardinal generated identifier used to ensure that a data remains accurate during the various calls.


AcquirerCountryCode String

Status
colourRed
titlerequired

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


LanguagePreference Array

Status
colourRed
titlerequired

A list of preferred languages used during an authentication prompt. The preferred option will be the left most option.

Example:  ["en", "es"]


Email String

Status
colourRed
titlerequired

The cardholder’s email.


Payment Object

Status
colourRed
titlerequired

Contains payment fields.

Expand
titlePayment Object (Within Payload Object)

Amount String

Status
colourRed
titlerequired

The total transaction amount with decimalization.


CurrencyCode String

Status
colourRed
titlerequired

A 3-digit alpha ISO 4217 currency code for the sale amount.


MerchantName String

Status
colourRed
titlerequired

The name of the merchant requesting the FIDO transaction. This value will be presented to the merchant during the authentication step.

Code Block
languagejson
 {
   "Signature": "KmL2SLBeTRRU9TlxA6XfnAYg5yWn1QwEO0GL1RtP8mg=",
   "Timestamp": "2024-02-21T20:10:20.872Z",
   "Identifier": "59c282d02f3e7357b4aa6f13",
   "OrgUnitId": "59c2745f2f3e7357b4aa516a",
   "Algorithm": "SHA-256",
   "Payload": {
      "AccountNumber": "400009******0800",
      "CardBrand":"Visa",
      "ReferenceId": "12345-1234-123145-1423",
      "AcquirerCountryCode": "840",
      "LanguagePreference": ["en", "es"],
      "Email": "someone@somewhere.com",
      "Payment": {
        "Amount": "12.34",
        "CurrencyCode": "USD",
        "MerchantName": "Amazon",
      }
   }
}

Response

ErrorNumber String

Status
colourRed
titlerequired

An identifier of who is issuing the JWT. Used to contain the Api Key identifier or name.


Error Description String

Status
colourRed
titlerequired

Processor/Merchant level OrgUnitId


RequestId String

Status
colourRed
titlerequired

The session identifier for the merchant to pass on all subsequent requests.


Payload Object

Status
colourRed
titlerequired

The Payload containing fields and a payment object

Expand
titlePayload Details

Account Object

Status
colourRed
titlerequired

Indicates information related to the Account.


Issuer Object

Status
colourRed
titlerequired

Indicates information related to the Issuer.


ReferenceId String

Status
colourRed
titlerequired

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


Expand
titleAccount Object Details

CardBrand String

Status
colourRed
titlerequired

Types of cards used for purchase. Currently VISA is the only supported card brand for FIDO.


LastFour String

Status
colourRed
titlerequired

Unformatted total transaction amount without any decimalization.


FIDO Object

Status
colourYellow
titleConditional

An object with FIDO specific fields

Note

Required for FIDO transactions

Expand
titleFIDO Object Details (within Account Object)

FlowType String

Status
colourRed
titleRequired

Indicates the flow type of the FIDO process with three possible values:

  • ENROLLMENT- Move forward with a 3DS authentication to continue the enrollment flow.

  • AUTHENTICATION- Move forward with FIDO authentication by running the /FIDO/Challenge request.

  • FAILURE- Move forward with 3DS authentication without FIDO.


ReasonCode String

Status
colourYellow
titleConditional

The error code for the FIDO attempt. Only returned in an error scenario


ReasonDescription String

Status
colourYellow
titleConditional

The error description for the FIDO attempt. Only returned in an error scenario

Expand
titleIssuer Object

SupportedVersions Array of Objects

Status
colourYellow
titleConditonal

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


SupportedVersions.Version String

Status
colourYellow
titleConditonal

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


SupportedVersions.Capabilities Array

Status
colourYellow
titleConditonal

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


SupportedVersions.MethodURLPresent Object

Status
colourYellow
titleConditonal

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.

Code Block
languagejson
 {
    "ErrorNumber": 0,
    "ErrorDescription": "Success",
    "RequestId": "b3933183-48df-409f-94ff-12952364009b",
    "Payload": {
        "Account": {
            "CardBrand": "Visa",
            "LastFour": "0094",
            "FIDO": {
                "FlowType": "ENROLLMENT", 
                "ReasonCode": "1001",
                "ReasonDescription": "Error"
            }
        },
        "Issuer": {
            "SupportedVersions": [
                {
                    "Version": "2.1.0",
                    "Capabilities": [
                        "AuthenticationAvailableAtACS",
                        "DAF"
                    ],
                    "MethodURLPresent": true
                },
                {
                    "Version": "2.2.0",
                    "Capabilities": [
                        "AuthenticationAvailableAtACS",
                        "DecoupledAuthentication",
                        "DataOnly",
                        "DelegatedAuthentication",
                        "IssuerTRA",
                        "DAF"
                    ],
                    "MethodURLPresent": true
                }
            ]
        },
        "ReferenceId": "51ca6679-12ed-47c4-8982-1a29e10d4587"
    }
}