Navigate to...

Integration Overview - Visa SRC SDK

JavaScript SDK Methods Overview

The JavaScript Reference contains more information on how to use each of the methods below in addition to setting up the SDK.

Method	Description
init()	Initializes the app with common state. The init method must be called before any other methods. It is synchronous in operation.
isRecognized()	Determines whether the consumer is recognized, e.g. by detecting the presence of a local cookie in the browser environment. If the user is recognized, this method obtains the JSON Web Token (JWT) to optionally pass to precheckout call to other SRC. This method may then (as an optimization) initiate the Get Precheckout Data request.
getSrcProfile()	Obtains the masked card and other account profile data associated with the userId. The method uses a JWT, or a secure cookie from the browser to identify the user. The returned data can be used for card selection.
identityLookup()	Obtains the user account associated with the consumer’s identity (an email address or phone number).
initiateIdentityValidation()	Sends a validation code to the specified consumer. This method sends a one-time password (OTP) to the consumer to start validation. Call this method before using profile data returned from getSrcProfile.
completeIdentityValidation()	Receives the validation code sent to the specified consumer, which validates the consumer’s identity. This method completes the identity validation by receiving the one-time password (OTP) sent to the consumer to start validation. Check the returned code against maskedValidationChannel. Call this method before using profile data returned from getSrcProfile.
checkout()	This method performs checkout using the selected card. If successful, the response contains summary checkout information and, conditionally, an encrypted payload containing PCI and/or PII data, depending on the configuration of the DpaTransactionOptions. This method is called after the consumer has chosen a masked card for checkout from the SRC's candidate list. Typically, the SRCi calls back DPA to retrieve any additional data that the DPA may have, e.g. updated DpaTransactionOptions, based on the selected card. If the DPA returns some data via this callback, then the SRCi should insert that data without modification into the checkout request. The checkout method also supports a card being provided during the checkout flow. When the combined flow is executed, the client 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.
authenticate()	Performs authentication using the selected card and returns authentication data.
unbindAppInstance()	Disassociates the Consumer application or Device from the Consumer’s SRC Profile.

Digital Terminal Functional Requirements

Requirements	Flows Impacted	Priority
Must support initiation of Click to Pay checkout by selecting an existing DPA Guest Checkout.	All flows	Required
Digital Terminal may load the SDK and trigger its initialization during page load before the consumer navigates to card payment section in order to optimize the user experience.	All flows	Recommended
Based on fraud decisioning, Click to Pay may indicate the need for cardholder authentication/step-up after a card selection for checkout.	All flows	Required
Digital Terminal must support presenting Click to Pay enabled card list within the DPA Guest Checkout experience, along with other payment methods accepted by the DPA.	Recognized/ Unrecognized User flows	Required
Click to Pay card list must be ordered according to EMVCo requirements (See Digital Terminal Aggregates Click to Pay Card List for Presentment.)	Recognized/ Unrecognized User flows	Required
Digital Terminal may present an Add Card option along with Click to Pay card list presented within the DPA checkout flow.	Recognized/ Unrecognized User flows	Recommended
Must support an email entry option for an unrecognized user to initiate lookup. Digital Terminal can use an existing email address field to satisfy this requirement.	Unrecognized User flow	Required
Digital Terminal must support functionality to validate user identity by entering a one-time code. Depending on DPA, this can be an inline option or a modal or a separate page, all hosted by the Digital Terminal.	Unrecognized User flow	Required
For added optimization to DPA integrated checkout experience, Digital Terminal should support additional authentication measures (e.g., CVV) as required by Click to Pay system for selected card. This could be achieved through integration with Click to Pay system’s authentication APIs.	All flows	Recommended
For managed authentication, Digital Terminal must pass all the required information necessary for performing authentication in the checkout call.	All flows	Required
Digital Terminal must present references to Visa Click to Pay Terms and Visa Privacy Notice, taking into account consumer’s country and language preference.	Add Card flow for New and Returning User	Required

Digital Terminal Integrates Click to Pay on DPA Guest Checkout Flows

The Digital Terminal provider integrates Click to Pay checkout experience for participating DPAs. Digital Terminal must ensure DPA eligibility- and acceptance-related settings before initiating Click to Pay checkout flow. To improve card listing experience and responsiveness, Digital Terminal may invoke isRecognized() (See next section) before showing the card listing page.

Digital Terminal Performs Consumer Recognition

Digital Terminal invokes the isRecognized() API on all participating Click to Pay systems for consumer recognition. SDK will send on-device cookie information to Click to Pay systems for consumer recognition. Response includes an isRecognized indicator and ID token list, where each ID token represents a consumer identity recognized by the respective Click to Pay systems. ID tokens can be used as needed to initiate identity lookup with Click to Pay systems (See next section)

Based on fraud risk decisioning, Click to Pay may indicate the need for cardholder step-up

For an ideal user experience, the Digital Terminal should not provide a windowref in the checkout request. In the case where the Digital Terminal does not provide a windowref and the Click to Pay system requests risk step-up or authentication, Click to Pay will launch the respective verification screens, as required.

Digital Terminal Aggregates Click to Pay Card List for Presentment

Digital Terminal aggregates the ID tokens from all Click to Pay systems to compile Click to Pay card list and applies DPA acceptance settings to determine which cards are made available during checkout.

Based on previously received list of ID token, Digital Terminal invokes getSrcProfile() API on all Click to Pay systems to retrieve card list associated with the device. In case the initial recognition attempt failed with a Click to Pay system, an ID token obtained from one of the Click to Pay systems may be used to attempt recognition.
Click to Pay system returns the customer profiles (based on recognized ID token) with a list of cards linked to its user and a unique transaction identifier.
Digital Terminal aggregates and presents all Click to Pay cards to the consumer for card selection. It is recommended the card list presentation is consistent and based on the following logic:
1. Divide the list of cards into usable and unusable sets (based on flags set for each card).
2. Order each set by the date of last use for a Click to Pay payment. If never used for payment, then by ascending order of the date of enrollment in the Click to Pay system.

Digital Terminal can also apply DPA acceptance preferences to present card list to consumers.

Digital Terminal Facilitates Card Selection

A consumer selects a card from the card list provided by the Digital Terminal.
At this point, Digital Terminal either invokes the DCF to complete the checkout journey or performs the role of DCF.
Note: Visa recommends that Digital Terminal also performs the DCF role to achieve a fully integrated checkout user experience.
DCF passes the checkout payload back to the Digital Payment Application via the Digital Terminal.
Digital Payment Application can use the checkout reference identifier from payload to obtain a full payment payload from Click to Pay system after the consumer submits the order.

Digital Terminal Facilitates Add Card for DPA

Digital terminal may present Add Card flow when Click to Pay system fails to recognize the user on a device or when an existing user chooses to add a new card to Click to Pay.

Digital Terminal Facilitates Email Lookup for DPA

The consumer performs an email lookup facilitated by the Digital Terminal.

Consumer enters an email identity and Digital Terminal requests all participating Click to Pay systems to verify it using identityLookup() API call.
Based on the responses, Digital Terminal selects a Click to Pay system that recognizes the consumer and invokes the initiateIdentityValidation() API call to initiate identity validation flow.
Consumer receives a one-time code via email or text (SMS).
Digital Terminal presents a screen to enter the one-time code, embedded within the Digital Payment Application screen. The one-time code entered is sent to Click to Pay system for verification using completeIdentityValidation() API.
Click to Pay system will respond back with an ID token once the consumer identity is verified.
Digital Terminal can use the list of ID token to request a card list from all Click to Pay systems by invoking getSrcProfile() API call.
Digital Terminal aggregates the card list obtained from all Click to Pay systems, orders them, and displays them to consumer for selection.
Based on the card selected, Digital Terminal determines the DCF or performs the role of DCF and calls checkout() API with card ID, transaction data, and DPA data parameters.
Digital Terminal passes payload back to Digital Payment Application. DPA (or its partner DAG) may also use the checkout reference identifier to obtain a full payment payload for transaction processing.

Digital Terminal Presents Visa Click to Pay Terms and Visa Privacy Notice

Digital Terminal must ensure that consumers are redirected to Visa Click to Pay Terms and Visa Privacy Notice depending on their country of residence and language preference.

Digital Terminals should determine the consumer's country based on the country provided in the consumer's billing address. If this information is not available to the Digital Terminal, it should refer to the DPA's country. If the DPA's country is also not available to the Digital Terminal, it should attempt to derive the country from the consumer's browser settings. Otherwise, it should default to the U.S.

Digital Terminal should refer to the consumer's language preference chosen for the Digital Terminal's (or DPA's) checkout experience. If this is not possible for the Digital Terminal, it should set the language based on the defined default language for the given country.

In Europe, Visa defines the default language for markets that have multiple official languages (See table below).

Country with Multiple Official Languages	Default Language
Switzerland	German
Belgium	Dutch
Luxembourg	French
Finland	Finnish
Slovenia	Slovenian

Digital Terminal must use the standardized URLs to display Visa’s Click to Pay Terms and Visa Privacy Notice to the consumer. The Digital Terminal should replace the <locale> with country locale code.

Standardized URL

Page	URL
Terms	https://www.visa.com/<locale>/checkout/legal/terms-of-service.html
Privacy Notice	https://www.visa.com/<locale>/checkout/legal/global-privacy-notice.html

If Visa Click to Pay does not support the resulting language and country combination (for example, es-US, en-CH), Visa Click to Pay will revert the consumer to the English US version of Click to Pay’s Terms or Visa’s Privacy Notice.

Digital Payment Application Functional Requirements

Visa Click to Pay System requirements for DPAs are elaborated in this section. DPA requirements may vary across each participating Click to Pay system.

The Digital Terminal initializes the Click to Pay checkout flow by calling init() SDK API and passing all DPA specific preferences, such as Transaction ID (generated by the Digital Terminal for each unique transaction), DPA ID, Digital Terminal ID, and DPA Transaction Options.

The DPA can pass additional acceptance settings in the Transaction Options object, such as accepted Shipping/Billing countries, collect Shipping/Billing address, contact information (name/email/phone), and transaction authentication data for 3DS.

Requirements	Flows impacted	Priority
DPAs must be onboarded to Click to Pay via their Digital Terminal or Digital Acceptance Gateway systems.	Onboarding	Required
Digital Terminal must support collection of token-based checkout payload from Click to Pay and pass to DAG for further processing.	Checkout Flow	Required
Digital Terminal must collect additional data during checkout including first/last name, email, and phone number and present a review screen based on guidelines provided by respective Click to Pay systems. Note: In Brazil, Digital Terminal can capture CPF number (national identifier).	New User flow	Required
Support collection of billing address within the Digital Terminal. Note: In Brazil, Digital Terminal must support the Postal Code (CEP) for the address format in Brazil.	Recognized/ Unrecognized User flows	Recommended
Digital Terminal can present the Review and Confirm page on behalf of the DPA with the following details: card info, first/last name of the cardholder, phone number, email address, and billing/shipping address. Note: Only masked information may be presented before cardholder verification. Full info can be presented after verification. Note: In Brazil, Digital Terminal must also collect CPF (national identifier) and CEP (Postal Code).	All flows	Recommended
Digital Terminal must have the capability to identify if a merchant supports and wants to display the Review and Confirm page and inform Click to Pay during checkout invocation.	All Flows	Required
Digital Terminal enabled Click to Pay checkout flows must be compliant with local regulations. All flows must be tested and certified in the context of local regulatory requirements. For example, in order to satisfy PSD2 regulations in EU, a Digital Terminal must implement and perform Strong Customer Authentication (SCA) during checkout flow.	All flows	Required
Digital Terminal-enabled Click to Pay checkout flows must enable consumer consent (with default checked) where applicable during the flows based on local regulations.	All flows	Required
Digital Terminal must upgrade to the latest Click to Pay SDK (JS or backend APIs) provided by Visa to enable the integration within 6 months of SDK release. Digital Terminal must support any mandatory changes as per guidance published in the Visa Click to Pay release notes.	All Flows	Required

DPA Sets Custom Attribute to Enable Merchant Orchestrated Checkout

Within DpaTransactionOptions, Digital Terminal is required to pass a custom attribute checkoutOrchestrator with value ‘merchant’. This enables a checkout experience where end to end UX is orchestrated by the merchant. This must be set at initialization of the SDK.

DPA Passes Accepted Billing Countries for Card List Presentment

Digital Terminals have the option to supply a list of DPA accepted billing countries during each checkout transaction, within the DpaTransactionOptions.dpaAcceptedBillingCountries object. Click to Pay system response will flag ineligible cards if the billing address country of the card is not part of DPA accepted billing country list. Digital Terminal must make ineligible cards unusable for selection using visual cues.

Note: Visa recommends displaying all cards returned in the Click to Pay card list to ensure consistency across multiple Digital Terminals on the same device.

DPA Passes Accepted Shipping Countries for Checkout

Digital Terminals have the option to supply a list of DPA accepted shipping countries during each checkout transaction, within the DpaTransactionOptions.dpaAcceptedShippingCountries object. Click to Pay SDK will pass dpaAcceptedShippingCountries attribute to the DCF, so that shipping country fields can be restricted based on the DPA accepted shipping countries.

DPA Collects Shipping Address

For Merchant Orchestrated Checkout, DPA is required to collect shipping address. Digital Terminal can set DpaTransactionOptions.dpaShippingPreference attribute as ‘NONE’. No other values are supported for this type of checkout implementation.

The default value for this field will be ‘NONE’ if no value is provided for Merchant Orchestrated Checkout.

DPA Passes Display and Processing Preferences for Payment Credentials

After a successful Click to Pay checkout flow, a checkout payload is passed back to DCF, which passes it back to DPA (via the Digital Terminal) for transaction processing. DPA (or its partner DAG) may also use the checkout reference identifier to obtain a full payment payload for transaction processing.

Display Only Payment Data: Based on its preference, a DPA could display Order Confirmation page using the attributes from the Visa Click to Pay summary payload response. The following attributes may be used: Transaction Reference ID, Masked Card, and Masked Address information.
Full Payment Payload: DPA or a third party acting on its behalf can request a full payment payload for processing the transaction authorization. Token payload will include a dynamic cryptogram which must be mapped to the appropriate Auth transaction field to VisaNet.

The table below summarizes the options available to a payment application for token validation and consumer authentication.

Cryptogram Option	Supports
TAVV	Payment applications capable of token-based transactions using the TAVV cryptogram.
DTVV	A payment application whose payment gateway or acquirer is not set up to perform token-based transactions using TAVV can use DTVV instead.
DTVV + CAVV	Payment applications using tokens with DTVV that want to use 3DS.
TAVV + CAVV	Payment applications using tokens with TAVV that want to use 3DS.
CTAVV	Payment applications using tokens with TAVV that want to use 3DS. If the payment application’s payment gateway or acquirer cannot process TAVV and CAVV in separate fields (F126.8 and F126.9), Visa provides a hybrid cryptogram which is the combination of the token and CAVV cryptograms. This can be mapped to F126.9 just like a regular TAVV-based cryptogram. Note: Payment applications performing 3DS offline would have to supply the CAVV authentication result to the Visa Click to Pay System. The Visa Click to Pay System would generate a hybrid cryptogram (CTAVV) and provide it as part of the full payment payload.

Visa Click to Pay

Merchants and Payment Service Providers