Visa 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 - Visa as a Digital Terminal SRC SDK

Integration Overview

Visa as a Digital Terminal provides quick integration with partners and merchants who want to accept payments from consumers. You can integrate Visa as a Digital Terminal 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, Visa as a Digital Terminal is quite flexible and imposes very few requirements for use.

JavaScript Library

Use the sdk.js Visa as a Digital Terminal JavaScript library to control the operation of Visa as a Digital Terminal 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}&locale={dpaLocale}&cardBrands={cardBrands}&dpaProfileId={dpaProfileId}
Production https://secure.checkout.visa.com/checkout-widget/resources/js/integration/v2/sdk.js?dpaId={dpaId}&locale={dpaLocale}&cardBrands={cardBrands}&dpaProfileId={dpaProfileId}

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 during the DPA registration process.

DPA can either be a merchant or partner.

dpaLocale

Type: String

ISO language country pair. [ISO 639-1 Code]_[ ISO 3166-1 alpha 2 country code]

R

Merchant’s preferred locale.

Example, “en_US”.

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”.

Note: If this field is not passed then card brands will default to Visa.

dpaProfileId

Type: String, Max Length = 50

O

Merchant’s profile identifier which is created during DPA registration. Visa uses this profile to populate settings, such as accepted card brands and shipping regions. A merchant can configure multiple profiles and pass that identifier to load the appropriate properties.

If no profile id is passed, then Visa will pick up the default profile configured for the corresponding merchant.

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({
    required String dpaId;
    optional String dpaTransactionId;
    optional String dpaProfileId;
    conditional String dpaClientId,
    conditional String cardBrands;
    optional DpaTransactionOptions dpaTransactionOptions;
    optional DpaData dpaData;
})

Request Parameters

Name

R/C/O

Description

dpaId

Type: String

R

The reference identifier generated during DPA registration with the Visa SRC System. DPA can either be a merchant or partner.

dpaTransactionId

Type: String, Max Length = 100

O

Merchant’s identifier associated with the request.

dpaProfileId

Type: String, Max Length = 50

 

O

Merchant’s profile identifier which is created during DPA registration. Visa uses this profile to populate settings, such as accepted card brands and shipping regions. A merchant can configure multiple profiles and pass that identifier to load the appropriate properties.

If no profile id is passed, then Visa will pick up the default profile configured for the corresponding merchant.

dpaClientId

Type: String

C

The reference identifier generated during DPA registration with the Visa SRC System. This DPA will always be a merchant and not a partner.

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

cardBrands

Type: List<String>

C

List of card schemes the merchant accepts.

We currently support the following.

  • visa
  • mastercard
  • amex
  • discover

 

Conditionality: Required if card brands parameter is not passed in the query parameters while loading Visa SDK.

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

 

dpaData

Type: DpaData

O

Present in order to dynamically update previously registered DPA data in the SRC System (e.g. presentation name).

Response Attributes

None

Code Example

example

Application Errors

Reason Code

Description

DPA_ID_MISSING

The dpaId parameter is missing.

DPA_CLIENT_ID_MISSING

The dpaClientId parameter is missing.

CARD_BRANDS_MISSING

The cardBrands parameter is missing.

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 or a mobile phone number).

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.

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/phone) 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.

srcCorrelationId

Type: String

Universally Unique Identifier (UUID) Max Length = 256

C

Reference identifier returned by the SRC System.

Conditionality: Required when a card list is returned.

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.

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 srcCorrelationId;
    conditional String srcDigitalCardId;
    conditional JWE<Card> encryptedCard;
    optional JWE<Consumer> encryptedConsumer;
    conditional DpaTransactionOptions dpaTransactionOptions;
    optional PayloadTypeIndicator payloadTypeIndicatorCheckout;
    conditional Window windowRef;
    optional AuthenticationMethod authenticationMethod;
    conditional ComplianceSettings complianceSettings;
})

Request Parameters

Field

R/C/O

Description

srcCorrelationId

Type: String

Universally Unique Identifier (UUID) Max Length = 256

C

Reference identifier returned by the SRC System.

Conditionality: Required when returned it in prior calls within the same transaction.

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.

encryptedCard

Type: JWE<Card>

C

The card being enrolled with the SRC System. Encrypted using a public key of SRC System to which the card is being enrolled.

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

encryptedConsumer

Type: JWE<Consumer>

O

Consumer information related to the card being enrolled. Encrypted using the public key of the SRC System to which the card is being enrolled.

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: Required when encryptedConsumer is supplied related to the card being enrolled.

assuranceData

Type: AssuranceData

O

Assurance data supplied to support risk management.

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.

windowRef

Type: Window

C

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

Conditionality: Required when the DCF needs to open a custom URI or the 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_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/phone) 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.

srcCorrelationId

Type: String

Universally Unique Identifier (UUID) Max Length = 256

C

Reference identifier returned by the SRC System.

Conditionality: Required when a card list is returned.

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.

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.

initiateIdentityValidation

This method initiates a process to validate that the consumer is in possession of, or has access to, the consumer identity claimed after a successful response is received for the id lookup method.

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/phone) 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

Field

R/C/O

Description

srcCorrelationId

Type: String

Universally Unique Identifier (UUID) Max Length = 256

 

O

Reference identifier returned by the SRC System.

Format: Universally Unique Identifier (UUID)

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).