# Visa Click to Pay

## Merchants and Payment Service Providers

## JavaScript Reference - Visa Click to Pay

### Visa Click to Pay SDK Overview

The Visa Click to Pay SDK provides JavaScript APIs to be used by a SRC initiator (SRCi) to communicate between the Digital Payment Application (DPA) and the Visa SRC system.

The SRCi has the responsibility to initialize the SDK for use with a DPA, which includes providing values to control and customize the DPA’s interaction with the Digital Card Facilitator (DCF), and the Visa SRC system. After initialization by calling init, the SDK can be used to:

- Determine whether the consumer is recognized on the device (isRecognized)
- Determine whether the consumer is recognized by email address or mobile number in the SRC system (identityLookup)
- Initiate validation of the consumer on the device (initiateIdentityValidation)
- Complete the validation of the consumer (completeIdentityValidation)
- Get the consumer’s profile, which contains payment instruments for selection (getSrcProfile)
- Checkout (ability to return authentication results) and report DCF status (checkout)
- Perform authentication using the selected card and returns authentication data (authenticate)
- Disassociate the DPA or device from the consumer’s SRC Profile (unbindAppInstance)

### Relationship Between the Visa Click to Pay System and Other Click to Pay Systems

Visa and other participating networks, such as MasterCard or American Express, each provide an SRC system to handle transactions under the EMV® Secure Remote Commerce Standards. Each SRC system provides a JavaScript API to invoke operations on the SRC system.

**Important:** This document only provides information about the Visa Secure Remote Commerce implementation of SRC. Refer to other networks’ documentation for non-Visa implementations of SRC.

You will need to take similar actions or call similarly named methods for each network you choose to support. The specifics of all non-Visa SRC methods and actions are outside the scope of this document; however, the following guidelines might be helpful:

- You must set up the Visa SRC SDK on each page from which you invoke the SDK’s JavaScript method. You will need to take similar actions to set up other networks as well.
- Before a card has been selected, you must call the same JavaScript method for each SRC system; for example, you must call the init method for each SRC system to start a transaction and call the isRecognized method for each SRC system to determine whether the consumer is known to any of the SRC systems.
- After a payment instrument has been selected, you call just the method specific to the associated network; for Visa cards, you call the Visa SRC SDK’s checkout JavaScript method.
- In some cases, you can call any (but only one) network’s method; for example, you could call any network’s implementation of initiateIdentityValidation to initiate passcode validation on a device and not call any other network’s similar method.

### Setting Up the JavaScript API

Before calling init, you must load the SRC SDK. The SDK creates a WindowRef that connects the digital terminal to the DCF.

The JavaScript SDK endpoint to use depends on whether you want to run the Digital Terminal SRC initiator (SRCi) in the sandbox or in production:

| Environment | JavaScript SDK Endpoint |
| --- | --- |
| Sandbox | [https://sandbox-assets.secure.checkout.visa.com/checkout-widget/resources/js/src-i-adapter/visaSdk.js?v2](https://sandbox-assets.secure.checkout.visa.com/checkout-widget/resources/js/src-i-adapter/visaSdk.js?v2) |
| Production | [https://assets.secure.checkout.visa.com/checkout-widget/resources/js/src-i-adapter/visaSdk.js?v2](https://assets.secure.checkout.visa.com/checkout-widget/resources/js/src-i-adapter/visaSdk.js?v2) |

Internally, a WindowRef is used to host the UI. When presenting any SRC UI, the SRC SDK controls the seamless operation of the window as either a pop-up window or an iFrame. The SRC SDK passes the WindowRef to the Digital Card Facilitator (DCF) so that the DCF UI can be rendered in the referenced window.

### Providing Keys and Certificates

You must create keys for source validation, encryption of PANs, decrypting the payload, and providing authentication of your requests. Visa supports both symmetric and asymmetric data encryption; however, asymmetric data encryption keys require a public certificate from the entity performing the decryption.

### Authenticated Data Token for Checkout Response

The purpose of the authentication data token is to provide authentication and integrity protection to the SRC summary payload.

#### Authenticated Data Token Notes

- The authenticated data is valid only for one particular request
- This is recommended to be used as an authorization header with the PoP (Proof-of-Possession) authentication scheme to connect to the SRC Initiator servers to fetch the full payload.

#### Authenticated Data Token JWS Header

| Field | Description |
| --- | --- |
| kid | Key identifier for the signing key.<br>When Visa generates this header, the signing key is used to lookup the Outbound Message Authentication key.<br>When Visa verifies the signature of this header, the signing key is used to lookup the Inbound Message Authentication key.<br>**Format:** Alphanumeric |
| alg | Algorithm used to sign this ID token<br>**Format:** It is one of the following values:<br>- RS256 – RSASSA-PKCS1-v1_5 using SHA-256<br>- HS256 – HMAC using SHA-256 |
| iat | Issuance time in UTC<br>Time at which the JWT was issued. This should not be before the expiration time (exp).<br>**Format:** UNIX Epoch timestamp, in milliseconds |
| jti | Unique identifier for the token. The jti can be used as a nonce.<br>**Format:** Case-sensitive string |

### JavaScript Methods

- init()
- isRecognized()
- getSrcProfile()
- identityLookup()
- initiateIdentityValidation()
- completeIdentityValidation()
- checkout()
- authenticate()
- unbindAppInstance()

#### init()

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

#### Method Signature

#### Parameters

| Field | Type | Mandate | Description |
| --- | --- | --- | --- |
| srciTransactionId | String | _Required_ | A unique transaction ID created by the SRCi, which may be created on the merchant page. It must be passed through to all networks (SRC systems) and DCFs.<br>**Format:** Maximum 100 characters. |
| srciDpaId | String | _Conditional_ | A unique ID provided by the SRCi for the DPA, which can be used as an external client ID.<br>_Conditionality:_ Required if srciDpaId in dpaData is not provided. |
| srcInitiatorId | String | _Required_ | SRCi identifier generated by an SRC system during the onboarding process. |
| dpaData | [DpaData](https://developer.visa.com/capabilities/visa-secure-remote-commerce/docs-structures) | _Conditional_ | DPA registration data.<br>_Conditionality:_ Required if srciDpaId is not provided. |
| dpaTransactionOptions | [DpaTransactionOptions](https://developer.visa.com/capabilities/visa-secure-remote-commerce/docs-structures) | _Required_ | DPA configuration data, which overrides the configuration on the SRC system that was created during DPA registration. |

### Errors

| Reason Code | Description |
| --- | --- |
| SRCI_ID_MISSING | The identifier for the SRCi (scrInitiatorId) is missing. |
| DPA_ID_MISSING | srcDpaId and dpaData both are missing. SRC system cannot identify the DPA. |
| SRCI_TXN_ID_MISSING | srciTransactionId is missing. |

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

### Returns

| Field | Type | Mandate | Description |
| --- | --- | --- | --- |
| recognized | Boolean | _Required_ | Whether the consumer is recognized.<br>It is one of the following values:<br>- true — recognized<br>- false — not recognized |
| idTokens | List<JWT> | _Conditional_ | A token that allows the SRC systems to communicate with each other for SRC consumer identity verification; This SRC ID token should be discarded at the end of an SRC checkout transaction.<br>_Conditionality:_ Required if the consumer is recognized; Not need to be present if the consumer is not recognized. |

### Checkout Requirements

Requirements When Checking Out With a New Card

You must include the following fields in the encrypted card (encryptedCard) parameter:

- primaryAccountNumber
- panExpirationMonth
- panExpirationYear
- cardSecurityCode
- cardholderFullName

An additional field in the consumer parameter is required, depending on the value of the identityType field in the consumerIdentity structure:
- If the identityType field contains EMAIL_ADDRESS, you must pass the mobileNumber field in the consumer parameter.
- If the identityType field contains MOBILE_PHONE_NUMBER, you must pass the emailAddress field in the consumer parameter.
- If no identityType has been defined in getSrcProfile() response, both email address and mobile number must be provided in the consumer parameter.

Optionally, you can include the billing address in the encryptedCard parameter and the appropriate consumer parameter (either mobileNumber or emailAddress).