Unified Click to Pay

Merchants and Payment Service Providers

Start a Project Start a Project API Overview API Overview API Reference API Reference
Navigate to...
keyboard_arrow_down

JavaScript Reference - Unified Click to Pay

Integration Overview

Unified Click to Pay provides quick integration with partners and merchants who want to accept payments from consumers. You can integrate Unified Click to Pay within your existing website pages and implement business and event logic using programming languages, tools, and techniques in the same way you currently do. For this reason, Unified Click to Pay is quite flexible and imposes very few requirements for use.

JavaScript Library

Use the sdk.js Unified Click to Pay JavaScript library to control the operation of Unified Click to Pay on your site.

The Javascript SDK endpoint to use depends on whether you want to run in sandbox or production environment.

Environment Javascript SDK Endpoint
Sandbox
 https://sandbox.secure.checkout.visa.com/checkout-widget/resources/js/integration/v2/sdk.js?dpaId={dpaId}&cardBrands={cardBrands}&dpaClientId={dpaClientId}
Production https://secure.checkout.visa.com/checkout-widget/resources/js/integration/v2/sdk.js?dpaId={dpaId}}&cardBrands={cardBrands}&dpaClientId={dpaClientId}

URL Parameters

The following parameters are required to be passed while invoking the SDK as URL parameters.

Query Parameters

R/C/O

Description

dpaId

Type: String

Max Length = 255

R

Reference identifier of the DPA. Based on the previously generated identifier during the DPA registration process. DPA can either be a merchant or partner.

cardBrands

Type: String

R

List of card schemes the merchant accepts.

It is a comma separated string with the following supported values.

  • visa
  • mastercard
  • amex
  • discover

 

Example, “visa, mastercard, amex, discover”.

dpaClientId

Type: String

C

Reference identifier of the merchant. Based on the previously generated identifier during the DPA registration process. This DPA will always be a merchant and not a partner.

Conditionality: Required when the dpaId is representing a partner and has multiple merchants on boarded via the partner. This reference identifier will represent the merchant on boarded via the partner.

Code Example

//Required query parameters  dpaId and cardBrands
<script src="https://sandbox.secure.checkout.visa.com/checkout-widget/resources/js/integration/v2/sdk.js?dpaId=<JRG47J3KFNIQ7ASQN5DB21NO7TV3uh8_vx1lvzm7Kh8jQahhw>&locale=en_US&cardBrands=visa,mastercard"></script> //based on sandbox url
<script>
    var Vsb = window.VSDK;
</script>

JavaScript Methods

initialize

This method initializes the app with common state. The initialize method must be called before any other methods. It is synchronous in operation.

Syntax

initialize({
    optional DpaTransactionOptions dpaTransactionOptions;
})

Request Parameters

Name

R/C/O

Description

dpaTransactionOptions

Type: DpaTransactionOptions

O

These options can be used to override transaction options for the DPA that were configured during the DPA Registration.

The following DpaTransactionOptions data elements are applicable.

 

Data Element

R/C/O

dpaLocale

Type: String

O

transactionAmount

Type: TransactionAmount

O

dpaBillingPreference

Type: AddressPreference enum

O

dpaAcceptedBillingCountries

Type: List<String>

O

consumerNationalIdentifierRequested

Type: Boolean

O

merchantCategoryCode

Type: String

O

merchantCountryCode

Type: String

O

merchantOrderId

Type: String

O

paymentOptions

Type: List<PaymentOptions>

O

 

Response Attributes

None

Code Example

window.onload = async function () {

    // Create a shorthand reference to the Visa Checkout SDK
    const Vsb = window.VSDK;

    // Define your DpaTransactionOptions
    const dpaTransactionOptions = {
        // Fill in your specific options here
    };

    // Initialize the Visa Checkout SDK with your DpaTransactionOptions
    try {
        await Vsb.initialize({
            dpaTransactionOptions: dpaTransactionOptions
        });

        //Invoke getCards and other apis here onwards

    } catch (error) {
        console.error('Error initializing SDK:', error);
    }
};

Request Example

{
    "dpaTransactionOptions": {
        "transactionAmount": {
            "transactionAmount": "123.94",
            "transactionCurrencyCode": "USD"
        },
        "dpaBillingPreference": "NONE",
        "dpaAcceptedBillingCountries": [
            "US",
            "CA"
        ],
        "consumerNationalIdentifierRequested": false,
        "merchantCategoryCode": "4829",
        "merchantCountryCode": "US",
        "payloadTypeIndicator": "FULL",
        "merchantOrderId": "fd65f14b-8155-47f0-bfa9-65ff9df0f760",
        "paymentOptions": [
            {
                "dpaDynamicDataTtlMinutes": 2,
                "dynamicDataType": "CARD_APPLICATION_CRYPTOGRAM_LONG_FORM"
            }
        ],
        "dpaLocale": "en_US"
    }
};

Response Example

None

Application Errors

None

Also, see Standard Error Codes.

getCards

This method returns SRC profile data from multiple SRC Systems to fetch a complete card list to enable card selection.

Syntax

getCards({
    required ConsumerIdentity consumerIdentity;
    conditional String validationData;
    optional ComplianceSettings complianceSettings;
})

Request Parameters

Field

R/C/O

Description

consumerIdentity

Type: ConsumerIdentity

R

Primary verifiable consumer identity within an SRC profile (e.g. an email address).

Note: If a SRC system recognizes the user then this identity may be ignored.

validationData

Type: String

C

The validation data (e.g. the OTP value) entered by the user.

Conditionality: Required when prior call within the same transaction returned an actionCode of PENDING_CONSUMER_IDV.

Note: When a merchant calls the getCards () API for the first time and a user is not recognized in SRC System then Visa will initiate an identity validation and return actionCode of PENDING_CONSUMER_IDV. This field is required to be passed when the merchant calls getCards () API for the second time after user successfully enters an OTP on the merchant screen.

complianceSettings

Type: ComplianceSettings

O

The compliance settings specifying the consents provided by the consumer for binding in the Remember Me scenario.

Note: When a merchant calls the getCards () API for the first time and a user is not recognized in SRC System then Visa will initiate an identity validation and return actionCode of PENDING_CONSUMER_IDV. This field can be optionally passed when the merchant calls getCards () API for the second time after user successfully enters an OTP on the merchant screen.

Response Attributes

Field

R/C/O

Description

actionCode

Type: ActionCode enum

R

A code indicating the behavior to be handled by the SRC Initiator.

Values applicable:

  • SUCCESS
  • PENDING_CONSUMER_IDV
  • ADD_CARD
  • ERROR

profiles

Type: List<SrcProfile>

R

List of SRC profile(s) associated with each recognized consumer identity.

If actionCode is SUCCESS and no SRC profiles are recognized,

Or

If actionCode is PENDING_CONSUMER_IDV or ADD_CARD,

then an empty list is returned.

maskedValidationChannel

Type: String

C

Masked value of the channel (e.g. email) that the SRC System used to deliver the validation data (e.g. OTP).

Conditionality: Required when actionCode is PENDING_CONSUMER_IDV.

supportedValidationChannels

Type: List<IdentityValidationChannel>

C

List of additional channels that are supported and can be used to perform identity validation.

If returned by the SRC System, these choices may be presented to the consumer.

Conditionality: Optionally returned when actionCode is PENDING_CONSUMER_IDV and returned by the SRC System.

Code Example

// Get cards sample request
let consumerIdentity = {
    identityProvider: "SRC",
    identityValue: "[email protected]",
    identityType: "EMAIL_ADDRESS"
};

let cards = await Vsb.getCards({ consumerIdentity });

let { actionCode } = cards;

switch (actionCode) {
    case 'SUCCESS':
        //handle getCards response in UI
        console.log('Handle getCards response in the UI ', cards);
        break;
    // If cards status is "PENDING_CONSUMER_IDV", call getCards again with validationData
    case 'PENDING_CONSUMER_IDV':
        const validationDataInput = { consumerIdentity, validationData: "654321" }; // Replace with your actual validation data
        cards = await Vsb.getCards(validationDataInput);
        break;
    case 'ERROR':
        console.log('Handle error cases:');
        break;
    default:
        console.log('No cards found >> ', cards.actionCode);
        break;
}

Request Example (Recognized User)

{
    "consumerIdentity": {
        "identityProvider": "SRC",
        "identityValue": "[email protected]",
        "identityType": "EMAIL_ADDRESS"
    }
}

Response Example (Recognized User Flow - Success)

{
    "actionCode": "SUCCESS",
    "profiles": [
        {
            "maskedCards": [
                {
                    "countryCode": "",
                    "dateOfCardCreated": "2024-07-09T17:03:37.785Z",
                    "dateOfCardLastUsed": "2024-07-09T17:04:11.932Z",
                    "dcf": {
                        "logoUri": "http://mastercard.com/",
                        "name": "mastercard",
                        "uri": "https://sandbox.src.mastercard.com/pay/"
                    },
                    "digitalCardData": {
                        "artUri": "https://sbx.assets.mastercard.com/card-art/combined-image-asset/6713d73d-a701-4bd2-bc9b-2e98940de9c7.png",
                        "authenticationMethods": [
                            {
                                "authenticationMethodType": "FIDO2"
                            }
                        ],
                        "descriptorName": "MasterCard Test Bank",
                        "presentationName": "",
                        "status": "ACTIVE"
                    },
                    "digitalCardFeatures": {},
                    "maskedBillingAddress": {},
                    "panBin": "520473",
                    "panExpirationMonth": "12",
                    "panExpirationYear": "2025",
                    "panLastFour": "4818",
                    "paymentCardDescriptor": "mastercard",
                    "paymentCardType": "CREDIT",
                    "srcDigitalCardId": "nE5xhI3jQcSis6Vf7IAH-A000000000000US",
                    "tokenLastFour": "0898"
                },
                {
                    "countryCode": "",
                    "dateOfCardCreated": "2024-07-09T16:58:30.313Z",
                    "dateOfCardLastUsed": "2024-07-09T17:09:15.990Z",
                    "dcf": {
                        "logoUri": "http://mastercard.com/",
                        "name": "mastercard",
                        "uri": "https://sandbox.src.mastercard.com/pay/"
                    },
                    "digitalCardData": {
                        "artUri": "https://sbx.assets.mastercard.com/card-art/combined-image-asset/6713d73d-a701-4bd2-bc9b-2e98940de9c7.png",
                        "authenticationMethods": [
                            {
                                "authenticationMethodType": "FIDO2"
                            }
                        ],
                        "descriptorName": "MasterCard Test Bank",
                        "presentationName": "",
                        "status": "ACTIVE"
                    },
                    "digitalCardFeatures": {},
                    "maskedBillingAddress": {},
                    "panBin": "520473",
                    "panExpirationMonth": "12",
                    "panExpirationYear": "2025",
                    "panLastFour": "3786",
                    "paymentCardDescriptor": "mastercard",
                    "paymentCardType": "CREDIT",
                    "srcDigitalCardId": "lP_KaPX2TmSz7mtdUg4ABQ000000000000US",
                    "tokenLastFour": "5574"
                }
            ]
        },
        {
            "maskedConsumer": {
                "maskedConsumerIdentity": {
                    "identityProvider": "SRC",
                    "identityType": "EMAIL_ADDRESS",
                    "maskedIdentityValue": "p*****[email protected]"
                },
                "maskedEmailAddress": "p*****[email protected]"
            }
        }
    ]
}

Request Example (Unrecognized User Flow - Pending Identity Validation)

{
    "consumerIdentity": {
        "identityProvider": "SRC",
        "identityValue": "[email protected]",
        "identityType": "EMAIL_ADDRESS"
    }
}

Response Example (Recognized User Flow - Pending Identity Validation)

{
    "actionCode": "PENDING_CONSUMER_IDV",
    "profiles": [],
    "maskedValidationChannel": "+1(***) ***-*555"
}

Request Example (Unrecognized User - Pending Identity Validation)

{
    "consumerIdentity": {
        "identityProvider": "SRC",
        "identityValue": "[email protected]",
        "identityType": "EMAIL_ADDRESS"
    },
    "validationData": "654321"
}

Response Example (Unrecognized User - Success)

{
    "actionCode": "SUCCESS",
    "profiles": [
        {
            "maskedCards": [
                {
                    "countryCode": "",
                    "dateOfCardCreated": "2024-07-09T17:03:37.785Z",
                    "dateOfCardLastUsed": "2024-07-09T17:04:11.932Z",
                    "dcf": {
                        "logoUri": "http://mastercard.com/",
                        "name": "mastercard",
                        "uri": "https://sandbox.src.mastercard.com/pay/"
                    },
                    "digitalCardData": {
                        "artUri": "https://sbx.assets.mastercard.com/card-art/combined-image-asset/6713d73d-a701-4bd2-bc9b-2e98940de9c7.png",
                        "authenticationMethods": [
                            {
                                "authenticationMethodType": "FIDO2"
                            }
                        ],
                        "descriptorName": "MasterCard Test Bank",
                        "presentationName": "",
                        "status": "ACTIVE"
                    },
                    "digitalCardFeatures": {},
                    "maskedBillingAddress": {},
                    "panBin": "520473",
                    "panExpirationMonth": "12",
                    "panExpirationYear": "2025",
                    "panLastFour": "4818",
                    "paymentCardDescriptor": "mastercard",
                    "paymentCardType": "CREDIT",
                    "srcDigitalCardId": "nE5xhI3jQcSis6Vf7IAH-A000000000000US",
                    "tokenLastFour": "0898"
                },
                {
                    "countryCode": "",
                    "dateOfCardCreated": "2024-07-09T16:58:30.313Z",
                    "dateOfCardLastUsed": "2024-07-09T17:09:15.990Z",
                    "dcf": {
                        "logoUri": "http://mastercard.com/",
                        "name": "mastercard",
                        "uri": "https://sandbox.src.mastercard.com/pay/"
                    },
                    "digitalCardData": {
                        "artUri": "https://sbx.assets.mastercard.com/card-art/combined-image-asset/6713d73d-a701-4bd2-bc9b-2e98940de9c7.png",
                        "authenticationMethods": [
                            {
                                "authenticationMethodType": "FIDO2"
                            }
                        ],
                        "descriptorName": "MasterCard Test Bank",
                        "presentationName": "",
                        "status": "ACTIVE"
                    },
                    "digitalCardFeatures": {},
                    "maskedBillingAddress": {},
                    "panBin": "520473",
                    "panExpirationMonth": "12",
                    "panExpirationYear": "2025",
                    "panLastFour": "3786",
                    "paymentCardDescriptor": "mastercard",
                    "paymentCardType": "CREDIT",
                    "srcDigitalCardId": "lP_KaPX2TmSz7mtdUg4ABQ000000000000US",
                    "tokenLastFour": "5574"
                }
            ]
        },
        {
            "maskedConsumer": {
                "maskedConsumerIdentity": {
                    "identityProvider": "SRC",
                    "identityType": "EMAIL_ADDRESS",
                    "maskedIdentityValue": "p*****[email protected]"
                },
                "maskedEmailAddress": "p*****[email protected]"
            }
        }
    ]
}

Request Example (Add Card - User Not Present)

{
    "consumerIdentity": {
        "identityProvider": "SRC",
        "identityValue": "[email protected]",
        "identityType": "EMAIL_ADDRESS"
    },
}

Response Example (Add Card - User Not Present)

{
    "actionCode": "ADD_CARD",
    "profiles": [],
    "error": {
        "reason": "ADD_CARD",
        "details": " "
    }
}

Application Errors

Reason Code

Description

AUTH_INVALID

Invalid federated id token.

ACCT_INACCESSIBLE

The user account exists but is not currently accessible.

ACCT_FRAUD

The user account was locked or disabled.

CONSUMER_ID_MISSING

The consumerIdentity parameter is missing.

CONSUMER_ID_FORMAT_UNSUPPORTED

Unsupported consumer identity type.

CONSUMER_ID_FORMAT_INVALID

Invalid consumer identity.

In addition to the common errors mentioned above the following are the potential errors when the API is called first time to get card list.

Reason Code

Description

OTP_SEND_FAILED

The OTP could not be sent to the recipient.

In addition to the common errors mentioned above the following are the potential errors when the API is called for the second time after merchant successfully captures the consumer OTP.

Reason Code

Description

VALIDATION_DATA_MISSING

The validationData parameter is missing.

VALIDATION_DATA_EXPIRED

The validationData is expired.

VALIDATION_DATA_INVALID

The supplied validationData is invalid.

RETRIES_EXCEEDED

The limit for the number of retries exceeded.

Also, see Standard Error Codes.

checkout

This method performs checkout using the specified Digital Card or PAN. If successful, the response contains summary checkout information and, conditionally, an encrypted payload signed by the SRC System containing PCI and/or PII data.

This method is called after the consumer has chosen a card for checkout from the card list or when the consumer enrolls a new card.

To add a card, the partner or merchant should provide the encrypted Card object, instead of ID of the digital card identifier, as an input parameter. The card will be enrolled into the SRC system and used for checkout.

Syntax

checkout({
    conditional String srcDigitalCardId;
    conditional JWE<Card> encryptedCard;
    optional Consumer consumer;
    conditional DpaTransactionOptions dpaTransactionOptions;
    optional PayloadTypeIndicator payloadTypeIndicatorCheckout;
    conditional Window windowRef;
    conditional List<AuthenticationReason> authenticationReasons;
    conditional AuthenticationMethod authenticationMethod;
    conditional ComplianceSettings complianceSettings;
    optional AssuranceData assuranceData;
})

Request Parameters

Field

R/C/O

Description

srcDigitalCardId

Type: String

C

A reference identifier of the card to be used for checkout.

Conditionality: Required for checkout when a card is selected from a candidate list.

Note: If srcDigitalCardId and encryptedCard both are provided then srcDigitalCardId takes precedence.

encryptedCard

Type: JWE<Card>

C

The card being enrolled with the SRC System. Encrypted using a public key that is shared with the partner during onboarding.

Conditionality: Required for a combined flow where this card is being enrolled during checkout.

Note: If srcDigitalCardId and encryptedCard both are provided then srcDigitalCardId takes precedence.

consumer

Type: Consumer

O

Consumer identity or profile information collected by an SRCi, payment service provider, or merchant.

Note: This field is applicable for a combined flow where a card is being enrolled during checkout (presented by the encryptedCard field).

complianceSettings

Type: ComplianceSettings

C

The compliance settings specifying the consents provided by the consumer.

Conditionality: This field is applicable for a combined flow where a card is being enrolled during checkout (presented by the encryptedCard field).

assuranceData

Type: AssuranceData

O

Assurance data supplied to support risk management.

authenticationReasons

Type: List<AuthenticationReason>

 C

Authentication reasons.

Conditionality: Required when prior call within the same transaction returned an actionCode of PENDING_AUTHENTICATION.

Note: When a merchant calls the checkout () API for the first time and the response returns actionCode of PENDING_AUTHENTICATION then the merchant needs to call checkout () API for the second time with the authentication reason. This field is required to be passed with the appropriate value of the authentication reason.

authenticationMethod

Type: AuthenticationMethod

C

The preferred authentication method indicated by the SRCi to the SRC System.

Conditionality: Required when prior call within the same transaction returned an actionCode of PENDING_AUTHENTICATION.

Note: When a merchant calls the checkout () API for the first time and the response returns actionCode of PENDING_AUTHENTICATION then the merchant needs to call checkout () API for the second time with the user selected authentication method. This field is required to be passed with the value of the user selected authentication method.

dpaTransactionOptions

Type: DpaTransactionOptions

C

These options can be used to override transaction options for the DPA that were configured during the DPA Registration

Conditionality: Required when not provided earlier in the initialize() method call and the DPA has not been registered with the SRC System.

The following DpaTransactionOptions data elements are applicable.

 

Data Element

R/C/O

transactionAmount

Type: TransactionAmount

O

paymentOptions

Type: List<PaymentOptions>

O

 

payloadTypeIndicatorCheckout

Type: PayloadTypeIndicator enum

O

Indicates the scope of the encrypted payload, if any, to be provided in the checkoutResponse attribute in the response to this method.

Note: If the parameter is not specified then the default is SUMMARY.

windowRef

Type: Window

C

A reference to a browsing context, e.g. iframe or new pop-up window

Conditionality: Required when the SRCi needs to open a custom URI for SRC System facilitates authentication.

If the window reference is provided, the card experience will be launched in the same window.

If the window reference is not provided, the card experience will be launched in a new window.

Response Attributes

Field

R/C/O

Description

actionCode

Type: ActionCode enum

R

A code indicating the behavior to be handled by the SRC Initiator.

Values applicable:

  • SUCCESS
  • PENDING_AUTHENTICATION
  • ERROR

checkoutResponse

Type: JWS <CheckoutPayloadResponse>

 C

Signed checkout response.

Conditionality: Required when the actionCode is set to SUCCESS or PENDING_AUTHENTICATION.

encryptedPayload will be not present within the checkoutResponse when:

  • payloadTypeIndicatorCheckout is set to SUMMARY or
  • actionCode is set to PENDING_AUTHENTICATION.

bindingStatus

Type: BindingStatus enum

O

Status of the binding/unbinding request.

The value BIND indicates that the consumer has chosen to be “remembered” on the consumer device.

authenticationStatus

Type: AuthenticationStatus enum

C

Current status of the initiated authentication event.

Conditionality: Required when the merchant calls the checkout() API call for the second time after the first call returned actionCode of PENDING_AUTHENTICATION. The second call to checkout() API returns authenticationStatus value.

authenticationResult

Type: AuthenticationResult enum

C

Authentication result.

Conditionality: Required when the merchant calls the checkout() API call for the second time after the first call returned actionCode of PENDING_AUTHENTICATION. Must be provided if authenticationStatus is COMPLETE.

assuranceData

Type: AssuranceData

 C

Information about any risk assessment operations performed by the SRC system.

Conditionality: Required when the merchant calls the checkout() API call for the second time after the first call returned actionCode of PENDING_AUTHENTICATION. Must be provided if authenticationStatus is COMPLETE.

Code Example

//sample checkoutParameters
const checkoutParameters = {
    srcDigitalCardId: 'nE5xhI3jQcSis6Vf7IAH-A000000000000US',
    dpaTransactionOptions: {
        transactionAmount: {
            transactionAmount: '99.95',
            transactionCurrencyCode: 'USD'
        },
        dpaBillingPreference: 'POSTAL_COUNTRY',
        dpaAcceptedBillingCountries: ['US', 'CA'],
        consumerNationalIdentifierRequested: false,
        merchantCategoryCode: '4829',
        merchantCountryCode: 'US',
        merchantOrderId: '8e15ce5c-58a3-4748-acab-71c67432dfa7',
        paymentOptions: [
            {
                dpaDynamicDataTtlMinutes: 2,
                dynamicDataType: 'CARD_APPLICATION_CRYPTOGRAM_LONG_FORM'
            }
        ]
    },
    payloadTypeIndicatorCheckout: 'FULL'
};

// Call checkout
const checkoutResponse = await Vsb.checkout(checkoutParameters);

// Log the checkout response
console.log(checkoutResponse);

Request Example

{
    "srcDigitalCardId": "nE5xhI3jQcSis6Vf7IAH-A000000000000US",
    "encryptedCard": "",
    "encryptedConsumer": "",
    "dpaTransactionOptions": {
        "transactionAmount": {
            "transactionAmount": "99.95",
            "transactionCurrencyCode": "USD"
        },
        "dpaBillingPreference": "POSTAL_COUNTRY",
        "dpaAcceptedBillingCountries": [
            "US",
            "CA",
            "AU"
        ],
        "consumerNationalIdentifierRequested": false,
        "merchantCategoryCode": "4829",
        "merchantCountryCode": "US",
        "merchantOrderId": "8e15ce5c-58a3-4748-acab-71c67432dfa7",
        "paymentOptions": [
            {
                "dpaDynamicDataTtlMinutes": 2,
                "dynamicDataType": "CARD_APPLICATION_CRYPTOGRAM_LONG_FORM"
            }
        ],
        "dpaLocale": "en_US",
        "acquirerMerchantId": "53e5b7ca-534e-4449-b5c1-839680b8f12",
        "acquirerBIN": "01234567890",
        "merchantName": "Sample Merchant"
    },
    "payloadTypeIndicatorCheckout": "FULL"
}

Application Errors

Reason Code

Description

AUTH_INVALID

Invalid federated id token.

ACCT_INACCESSIBLE

The user account exists but is not currently accessible.

CARD_MISSING

The srcDigitalCardId or encryptedCard parameter is required but is missing.

UNABLE_TO_CONNECT

Unable to connect to or launch card experience.

In addition to the common errors mentioned above the following are the potential errors when the API is called after a consumer selects a card during checkout.

Reason Code

Description

CARD_NOT_RECOGNIZED

The provided srcDigitalCardId is not recognized.

In addition to the common errors mentioned above the following are the potential errors when the API is called for adding a card during checkout.

Reason Code

Description

CARD_SECURITY_CODE_MISSING

Card Security Code (CSC) must be supplied in the encryptedCard parameter.

BILLING_ADDRESS_REQUIRED

The billing address must be provided.

CARD_INVALID

Invalid primaryAccountNumber parameter.

CARD_EXP_INVALID

Invalid card expiry date.
CARD_ADD_FAILED Unable to add the card.
TERMS_AND_CONDITIONS_ NOT_ACCEPTED Terms and conditions not accepted.

In addition to the common errors mentioned above the following are the potential errors when the API is called after an authenticate (step up) scenario during checkout.

Reason Code

Description

CARD_NOT_RECOGNIZED

The provided srcDigitalCardId is not recognized.
AUTHENTICATION_METHOD_NOT_SUPPORTED The supplied authentication method is not supported.
OTP_SEND_FAILED The OTP could not be sent to the recipient.
RETRIES_EXCEEDED The limit for the number of retries exceeded.
VALIDATION_DATA_MISSING The validationData parameter is missing.
VALIDATION_DATA_EXPIRED The validationData is expired.
VALIDATION_DATA_INVALID The supplied validationData is invalid.

Also, see Standard Error Codes.

initiateIdentityValidation

This method initiates a process to validate that the consumer is in possession of, or has access to, the consumer identity.

Syntax

initiateIdentityValidation({
    optional String requestedValidationChannelId
})

Request Parameters

Field

R/C/O

Description

requestedValidationChannelId

Type: String

O

Identifier of the channel over which the identity validation should be initiated.

Response Attributes

Field

R/C/O

Description

maskedValidationChannel

Type: String

R

Masked value of the channel (e.g. email) that the SRC System used to deliver the validation data (e.g. OTP)

Example: "sen*****@mailinator.com"

Code Example

example

Application Errors

Reason Code

Description

OTP_SEND_FAILED

The OTP could not be sent to the recipient.

RETRIES_EXCEEDED

The limit for the number of retries exceeded.

ACCT_INACCESSIBLE

The user account exists but is not currently accessible.

Also, see Standard Error Codes.

unbindAppInstance

This method unbinds a device identity (an application instance) from an SRC profile.

Syntax

unbindAppInstance()

Request Parameters

None

Response Attributes

None

Code Example

example

Application Errors

Reason Code

Description

AUTH_INVALID

Invalid federated ID token.

ACCT_INACCESSIBLE

The user account exists but is not currently accessible.

Also, see Standard Error Codes.

JavaScript API Error Handling

An error response notifies the caller that the action relating to the promise has failed. Use the error.reason field to drive your error handling logic. Errors such as INVALID_PARAMETER or INVALID_REQUEST are considered integration errors.

Error Structure and Usage

Error reasons and messages appear in a standard error structure, which is returned when the API request could not be handled. For programmatic actions, you should only rely on the value in error.reason. Errors are also provided with a human readable error description in error.message field; however, this field should be used only to understand the problem. You may prefer to provide your own description based on the value in error.reason. In some cases, the error.details structure provides additional information.

Error Response Fields

Field

Description

message

The internal error message, which should not be displayed or used in the logic of your digital terminal; it is provided as a convenience.

Format: String

reason

Mnemonic identifying the kind of error; use this field to trigger error handling logic in your digital terminal.

Format: String

details

One or more pairs of field name and associated error message that identify validation errors.

Format: details structure.

The details structure provides additional information, if it is returned:

Field

Description

location

The value of this field uses an XPATH expression to point to the field that fails validation.

Format: String

message

The specific error associated with the field.

Format: String

Example

error {
    "message": "Input parameters validation failed.", "reason": "INVALID_PARAMETER",
        "details":
    [// Optional structure, used with input data validation error
        {// Types to specify the fields with errors "location": "creditCard",
            "message": "Should be a numeric value"
        }
    ]
}

Standard Error Codes

API-specific error codes are listed in each API. All APIs can return the following standard error codes in addition to API-specific ones:

Reason

Description

UNKNOWN_ERROR

Unknown error.

REQUEST_TIMEOUT

Request timeout.

SERVER_ERROR

General server error

INVALID_PARAMETER

The value provided for one or more request parameters is considered invalid. This error is also generated in case of a missing required field. Typically, this is an integration error; whenever possible, should provide client-side validation to avoid a round trip to the server.

For user errors, handle this error by prompting the user to change the value.

INVALID_REQUEST

The server could not interpret the request.

Usually, these are the cases, when a data field has to be in a particular format but is not. Examples include:

  • Base64 decoding failed
  • The field is not in a particular format.

The message field may provide additional clarification of what part or field of the request is considered incorrect.

Please, refer to the API specification for the structure, format, and constraints on the API request.

AUTH_ERROR

The server understands the request, but cannot authenticate.

NOT_FOUND

The requested resource/business entity does not exist. The resource might also be hidden for security reasons.

RATE_LIMIT_EXCEEDED

Too many requests have been sent in a given amount of time. Intended for use with rate limiting schemes.

  • Decrease the rate of sending API requests; wait before sending the next request.
  • Consider implementing Exponential Backoff algorithm. In this algorithm, the delay before you retry is defined as:

Retry delay in milliseconds = (2 ^ n) * 1000 + randomDelayMs, where n is your retry count, such as 0, 1, 2, 3, …, and random- DelayMs is random delay in milliseconds, such as an integer between 0 and 1,000.

SERVICE_ERROR

An error occurred on the server.

Either show a generic message, or retry the same request again (it might succeed).