Visa Secure Remote Commerce

Software Developer Kit

Effective: 23 April 2024

Version 24.04

© 2019 - 2024 Visa. All Rights Reserved.

Visa Confidential
Important Information on Confidentiality and Copyright

Notice: This information is proprietary and CONFIDENTIAL to Visa. It is distributed to Visa participants for use
exclusively in managing their Visa programs. It must not be duplicated, published, distributed or disclosed, in
whole or in part, to DSAs, cardholders or any other person without prior written permission from Visa.

The Visa Confidential label signifies that the information in this document is confidential and proprietary to Visa
and is intended for use only by Visa Clients subject to the confidentiality restrictions in the Visa Core Rules and
Visa Product and Service Rules, non-Client Third-Party Processors that have an executed and valid VisaNet Letter
of Agreement on file with Visa, and other third parties that have a current participation agreement, including
confidentiality provisions, or other non-disclosure agreement with Visa that covers disclosure and use of the
information contained herein.

This document is protected by copyright restricting its use, copying, distribution, and decompilation. No part of
this document may be reproduced in any form by any means without prior written authorization of Visa.

The trademarks, logos, trade names and service marks, whether registered or unregistered (collectively the
“Trademarks”) are Trademarks owned by Visa. All other trademarks not attributed to Visa are the property of
their respective owners

Note:

This document is not part of the Visa Rules. In the event of any conflict between any content in this
document, any document referenced herein, any exhibit to this document, or any communications
concerning this document, and any content in the Visa Rules, the Visa Rules shall govern and control.

THIS PUBLICATION IS PROVIDED ON AN “AS IS, WHERE IS” BASIS, “WITH ALL FAULTS” KNOWN AND UNKNOWN.
THIS PUBLICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE
PERIODICALLY ADDED TO THE INFORMATION HEREIN: THESE CHANGES WILL BE INCORPORATED IN NEW
EDITIONS OF THE PUBLICATION. VISA MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S)
AND/OR THE PROGRAM(S) DESCRIBED IN THIS PUBLICATION AT ANY TIME. WHERE POTENTIAL FUTURE
FUNCTIONALITY IS HIGHLIGHTED, VISA DOES NOT PROVIDE ANY WARRANTY ON WHETHER SUCH
FUNCTIONALITY WILL BE AVAILABLE OR IF IT WILL BE DELIVERED IN ANY PARTICULAR MANNER OR MARKET. TO
THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, VISA EXPLICITLY DISCLAIMS ALL WARRANTIES,
EXPRESS OR IMPLIED, REGARDING THE INFORMATION CONTAINED HEREIN, INCLUDING ANY IMPLIED
WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.

If you have technical questions or questions regarding a Visa service or questions about this document, please
contact your Visa representative.
Contents
What’s New in This Version

Chapter 1 • SDK Overview

Visa Secure Remote Commerce SDK Overview. . . . . . . . . . . . . . . . . . . . . .9

Relationship Between the Visa SRC System and Other SRC Systems. . . . . . . . . .10

Checkout Journeys. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Setting Up the JavaScript API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Providing Keys and Certificates. . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Authenticated Data Token for Checkout Response. . . . . . . . . . . . . . . . . . . 12

Chapter 2 • JavaScript API

Initialize SRC SDK (init). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Init Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

DPA Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

DPA Transaction Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Init Returns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Init Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Init Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Is Recognized (isRecognized). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Is Recognized Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Is Recognized Returns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Is Recognized Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Is Recognized Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Get SRC Profile (getSrcProfile). . . . . . . . . . . . . . . . . . . . . . . . . . . . .26

Get SRC Profile Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Get SRC Profile Returns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

SRC Profile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Get SRC Profile Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

2 May 2024 Visa Confidential 3

 Visa Secure Remote Commerce – Software Developer Kit

Get SRC Profile Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Identity Lookup Account by Consumer ID (identityLookup). . . . . . . . . . . . . . . 37

Identity Lookup Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . .38

Identity Lookup Returns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Identity Lookup Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . .39

Identity Lookup Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Initiate Identity Validation (initiateIdentityValidation). . . . . . . . . . . . . . . . . . 40

Initiate Identity Validation Parameters. . . . . . . . . . . . . . . . . . . . . . . 40

Initiate Identity Validation Returns. . . . . . . . . . . . . . . . . . . . . . . . . 40

Initiate Identity Validation Examples. . . . . . . . . . . . . . . . . . . . . . . . 40

Initiate Identity Validation Errors. . . . . . . . . . . . . . . . . . . . . . . . . 41

Complete Identity Validation (completeIdentityValidation). . . . . . . . . . . . . . . . 41

Complete Identity Validation Parameters. . . . . . . . . . . . . . . . . . . . . . 42

Complete Identity Validation Returns. . . . . . . . . . . . . . . . . . . . . . . 42

Complete Identity Validation Examples. . . . . . . . . . . . . . . . . . . . . . .42

Complete Identity Validation Errors. . . . . . . . . . . . . . . . . . . . . . . . 43

Checkout (checkout). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Checkout Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

DPA Transaction Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Consumer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Card. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Compliance Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Authentication Context. . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Authentication Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Assurance Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Checkout Returns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Checkout Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Masked Card. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65

Masked Consumer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

2 May 2024 Visa Confidential 4

 Visa Secure Remote Commerce – Software Developer Kit

Assurance Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Event History. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76

Checkout Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Checkout Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Authenticate (authenticate). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Authenticate Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Account Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Authentication Context. . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Authentication Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Authenticate Returns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Authenticate Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Assurance Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

Authenticate Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Authenticate Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Unbind App Instance (unbindAppInstance). . . . . . . . . . . . . . . . . . . . . . .97

Unbind App Instance Parameters. . . . . . . . . . . . . . . . . . . . . . . . . 97

Unbind App Instance Returns. . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Unbind App Instance Example. . . . . . . . . . . . . . . . . . . . . . . . . . .98

Unbind App Instance Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

JavaScript API Error Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Chapter 3 • Unencrypted Payload Contents

Payload. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Card. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Payment Token. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Address. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Phone Number. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Dynamic Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Consumer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Phone Number. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

2 May 2024 Visa Confidential 5

 Visa Secure Remote Commerce – Software Developer Kit

Consumer Identity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Decrypted PAN Payload Example. . . . . . . . . . . . . . . . . . . . . . . . . . 109

Decrypted Token Payload Example. . . . . . . . . . . . . . . . . . . . . . . . . .110

Chapter 4 • Get Payload

Get Payload Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Get Payload Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Path and Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Required Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114

Query Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Request Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116

Get Payload Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Response Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Masked Card. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Masked Consumer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Assurance Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Get Payload API Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Get Payload API Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Get Payload PAN Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Get Payload Token Example. . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Chapter 5 • Confirmation Service

About the Confirmation Service . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Confirmation Service Request. . . . . . . . . . . . . . . . . . . . . . . . . . 132

Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Required Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Query Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135

POST Request Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

2 May 2024 Visa Confidential 6

 Visa Secure Remote Commerce – Software Developer Kit

Confirmation Service Response. . . . . . . . . . . . . . . . . . . . . . . . . 137

Response Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Confirmation Service API Errors. . . . . . . . . . . . . . . . . . . . . . . . . 138

Confirmation Service Example. . . . . . . . . . . . . . . . . . . . . . . . . . 138

Appendix A • Decrypting the SRC Payload

Java Example for SRC Payload Symmetric Decryption. . . . . . . . . . . . . . . . . 139

Node.js Example for SRC Payload Symmetric Decryption. . . . . . . . . . . . . . . . 140

Appendix B • Generating a JWE for PAN Encryption

Encrypting the PAN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Appendix C • JWE Composition Details

JSON Web Encryption (JWE) Using Shared Secret. . . . . . . . . . . . . . . . . . . .143

Appendix D • What’s New in Prior Versions

What's New in Version 20.01. . . . . . . . . . . . . . . . . . . . . . . . . . . . .146

What's New in Version 20.03. . . . . . . . . . . . . . . . . . . . . . . . . . . . .146

What's New in Version 20.10. . . . . . . . . . . . . . . . . . . . . . . . . . . . .146

What's New in Version 21.02. . . . . . . . . . . . . . . . . . . . . . . . . . . . .147

What's New in Version 21.06. . . . . . . . . . . . . . . . . . . . . . . . . . . . .147

What’s New in Version 22.04. . . . . . . . . . . . . . . . . . . . . . . . . . . . .147

What’s New in Version 22.07. . . . . . . . . . . . . . . . . . . . . . . . . . . . .148

What’s New in Version 23.04. . . . . . . . . . . . . . . . . . . . . . . . . . . . .148

What’s New in Version 23.08. . . . . . . . . . . . . . . . . . . . . . . . . . . . .149

What’s New in This Version. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

2 May 2024 Visa Confidential 7

What’s New in This Version

Interface Changes
The following changes were made to the interface:
l Clarified that the mobileNumber field in the checkout() parameters is required when
adding a new card.
l Changed the name of the mobileNumber field in the Masked Consumer structure to
maskedMobileNumber and noted that it is not returned by the getSrcProfile()
method.
l Added an optional encryptedBillingAddress field to the checkout() method's
parameters.
l Added the IDENTITY_VALIDATION_REQUIRED error to the checkout() method.

2 May 2024 Visa Confidential 8

Chapter 1
SDK Overview

Visa Secure Remote Commerce SDK

Overview
The Visa Secure Remote Commerce (SRC) SDK provides JavaScript APIs to be used by a Digital
Terminal SRC initiator (SRCi) to communicate between the Digital Payment Application (DPA)
and the Visa SRC system.
The Digital Terminal (DT) 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:
l Determine whether the consumer is recognized on the device (isRecognized)

l Determine whether the consumer is recognized by email address in the SRC system
(identityLookup)

l Initiate validation of the consumer on the device (initiateIdentityValidation)

l Complete the validation of the consumer (completeIdentityValidation)

2 May 2024 Visa Confidential 9

 Visa Secure Remote Commerce – Software Developer Kit
SDK Overview

l Get the consumer’s profile, which contains payment instruments for selection
(getSrcProfile)

l Checkout (ability to return authentication results) and report DCF status (checkout)

l Disassociate the DPA or device from the consumer’s SRC Profile (unbindAppInstance)

Relationship Between the Visa SRC System and

Other SRC 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:
l 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.
l 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.
l 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.
l 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.

Checkout Journeys
Detailed instructions and guidance for creating various consumer checkout journeys are
provided in the Visa Click to Pay Digital Terminal Implementation Guide. For more information,
contact your Visa representative.

2 May 2024 Visa Confidential 10

 Visa Secure Remote Commerce – Software Developer Kit
SDK Overview

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

Production
https://assets.secure.checkout.visa.com/
checkout-widget/resources/js/src-i-adapter/
visaSdk.js

The following example shows how to load the SDK and create an adaptor:

<head>
...
</head>
<body>
<script src="https://sandbox-assets.secure.checkout.visa.com/
checkout-widget/resources/js/src-i-adapter/visaSdk.js">
</script>
<script>
let vSrcAdapter = window.vAdapters.VisaSRCI;
let vSrc = new vSrcAdapter();
</script>
</body>

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

2 May 2024 Visa Confidential 11

 Visa Secure Remote Commerce – Software Developer Kit
SDK Overview

encryption; however, asymmetric data encryption keys require a public certificate from the
entity performing the decryption.

Key Description Purpose Key Type

Payload Verification SRCi participant verifies the signature. Visa signs the Asymmetric
payload.

PAN JWE Encryption SRCi participant encrypts PAN JWE via browser with Visa Asymmetric
public key.
It is required only for DT.

Payload Decryption SRCi participant decrypts full payload from back-end Asymmetric
server-to-server.

API Key Shared Secret SRCi participant authenticates using x-pay-token. Symmetric
Authentication

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

l The authenticated data is valid only for one particular request

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

2 May 2024 Visa Confidential 12

 Visa Secure Remote Commerce – Software Developer Kit
SDK Overview

Authenticated Data Token JWS Header

Field Description
kid Key identifier for the signing key.
When Visa generates this header, the signing key is used to lookup
the Outbound Message Authentication key.
When Visa verifies the signature of this header, the signing key is
used to lookup the Inbound Message Authentication key.
Format: Alphanumeric

alg Algorithm used to sign this ID token

Format: It is one of the following values:

l RS256 – RSASSA-PKCS1-v1_5 using SHA-256

l HS256 – HMAC using SHA-256

iat Issuance time in UTC

Time at which the JWT was issued. This should not be before the
expiration time (exp).
Format: UNIX Epoch timestamp, in milliseconds

jti Unique identifier for the token. The jti can be used as a nounce.

Format: Case-sensitive string

2 May 2024 Visa Confidential 13

Chapter 2
JavaScript API

Initialize SRC SDK (init)

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

Syntax

init(initData)

2 May 2024 Visa Confidential 14

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Init Parameters
initData is a structure that contains the following fields:

Field Description
srciTransactionId (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.
Format: Alphanumeric, maximum 100 characters

srciDpaId (Conditional) A unique ID provided by the SRCi for the DPA, which
can be used as an external client ID.
Required if srciDpaId in dpaData is not provided.

Format: String

srcInitiatorId (Required) SRCi identifier generated by an SRC system during the

onboarding process.
Format: String

dpaData (Conditional) DPA registration data.

Required if srciDpaId is not provided.

Format: DpaData structure

dpaTransactionOptions (Required) DPA configuration data, which overrides the configu­

ration on the SRC system that was created during DPA registration.
Format: DpaTransactionOptions structure

DPA Data

Field Description
srciDpaId (Conditional) DPA identifier, which is generated by the SRC system
during DPA registration. Required if srciDpaId is not provided in
the top-level structure of the request body; optional unless you
want to specify a display presentation name, the website address,
or the preferred 3DS behavior.
Format: String, 64 bytes

dpaPresentationName (Conditional) Display name of the DPA. Required to facilitate

transaction authentication.
Format: String,
Example: Mycompany Online

2 May 2024 Visa Confidential 15

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Field Description
dpaUri (Optional) The URI for the website.
Example: http://www.Mycompanyonline.com

dpaThreeDsPreference (Optional) Contact your Visa representative for information about

using this field to receive authentication data.
Deprecated
Format: It is one of the following values:

l ONBEHALF

l SELF

l NONE

l UNKNOWN (default)

DPA Transaction Options

This structure represents the config parameters that are common across all transactions,
originates from the Digital Payment Application (DPA).

Field Description
dpaLocale (Optional) DPA’s preferred locale. This can be the same as the locale
in the init parameters or can be different.

Format: Based on ISO format for language (ISO 639-1) and alpha-2
country code (ISO 3166-1 alpha-2). The language and country
should be separated using an underscore ( _ ).

Example: en_US, fr_CA

dpaAcceptedBillingCountries (Optional) Billing countries. Payments from the listed billing

countries are accepted. If this list is empty, all countries are
accepted.
Format: Array of country codes in ISO 3166-1 alpha-2 format
Example: ["US”, “CA”, “AU”]

dpaAcceptedShippingCountries (Optional) Shipping countries; shipping region country codes that

limit the selection of eligible shipping addresses. If this list is empty,
all countries are accepted.
Format: Array of country codes in ISO 3166-1 alpha-2 format

dpaBillingPreference (Optional) Verbosity of billing address required by the DPA.

Format: It is one of the following values:

l FULL (default)

l POSTAL_COUNTRY

l NONE

2 May 2024 Visa Confidential 16

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Field Description
dpaShippingPreference (Optional) Extent to which DPA wants to have shipping address
collected. Not required for Merchant Orchestrated Checkout; if
passed, it will be changed to NONE.

Format: It is one of the following values:

l FULL (default)

l POSTAL_COUNTRY

l NONE

consumerNameRequested (Optional) Whether the name of the consumer has been requested.
Format: It is one of the following values:

l true (default)

l false

consumerEmailAddressRequested (Optional) Whether the email address of the consumer has been
requested.
Format: It is one of the following values:

l true (default)

l false

consumerPhoneNumberRequested (Optional) Whether the Phone number of the consumer has been
requested.
Format: It is one of the following values:

l true (default)

l false

consumerNationalIdentifier (Optional) Whether the Consumer National identifier for the

Requested consumer is requested.
Format: It is one of the following values:

l true

l false

paymentOptions (Optional) Payment options requested by the DPA.

Format: PaymentOptions structure

reviewAction (Optional) Whether the payment will be processed immediately

after selection or after confirmation.
Format: It is one of the following values:

l pay -- proceed after selection

l continue -- proceed after confirmation (default)

2 May 2024 Visa Confidential 17

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Field Description
checkoutDescription (Optional) Review message to go with action.
Format: String

transactionType (Optional) Type of the transaction.

Format: It is one of the following values:

l PURCHASE (default)

l BILL_PAYMENT

l MONEY_TRANSFER

orderType (Optional) Type of orders.

Deprecated Format: It is one of the following values:

l REAUTHORIZATION

l RECURRING

l INSTALLMENT

transactionInstruction (Optional) Transaction instruction.

Format: Enum; it is one of the following values:

l RECURRING_PAYMENTS

l SUBSCRIPTION_SERVICES

l INSTALLMENTS

numberOfPayments (Conditional) Maximum number of authorizations for installment

payments. Required when transactionInstruction is specified.

Format:
purchaseDate (Conditional) Original purchase date. Required when
transactionInstruction is specified.

Format: UNIX Epoch timestamp. The value is in milliseconds.

recurringEndDate (Conditional) The date after which no further recurring authori­
zations should be performed. Required when
transactionInstruction is specified.

Format: UNIX Epoch timestamp. The value is in milliseconds.

recurringFrequency (Conditional) Minimum number of days between recurring authori­
zations. Required when transactionInstruction is specified.

Format: Integer

2 May 2024 Visa Confidential 18

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Field Description
payloadTypeIndicator (Optional) The verbosity of payload requested.
Format: Enum, it is one of the following values:

l FULL - includes everything; all PCI & PII data (card/token, billing,
shipping, consumer)
l SUMMARY - (default) no JWE. If FULL needed during checkout,
SRCi needs to make a request for it explicitly.
l PAYMENT - same as FULL

l NON_PAYMENT - only PII (billing, shipping, consumer). It has both

SUMMARY and encryptedPayload without card, token, or
dynamicData.

l NONE - just srcCorrelationId (with COMPLETE

dcfActionCode)

transactionAmount (Conditional) Amount of the transaction.

Required when transaction authentication is performed.
Format: TransactionAmount structure

merchantOrderId (Optional) The order identifier generated by the DPA. Typically used
for reconciliation process by the DPA.
Format: Universally Unique Identifier (UUID)

merchantCategoryCode (Optional) Code associated with Merchant Category

Format: 4-digit string

merchantCountryCode (Optional) The country code associated with the merchant’s billing
or shipping address.
Format: ISO-3166 - 1 alpha-2 standard code
Example: US – United States

threeDsInputData (Deprecated) If 3DS is requested for the transaction, this attribute is

required.
Format: ThreeDSInputData structure

dpaThreeDsPreference (Deprecated) Do not specify a value here. Set

dpaThreeDsPreference in the dpaData structure instead.

2 May 2024 Visa Confidential 19

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Field Description
authenticatedCredentialRequested (Optional) SRCi preference to perform authentication and to receive
authentication data for the transaction.
Format: It is one of the following values:

l true

l false (default)

customInputData (Optional) Custom input data elements presented to the SRC

System.
Format: CustomInputData structure; see "Custom Input Data."

Payment Options

Parameter Description
dpaDynamicDataTtlMinutes (Optional) The minimum requested validity period for the
transaction credentials, such as a cryptogram, returned by the SRC
system, in minutes.
If this is not provided, the values are determined by the SRCs.
Format: integer
Example: 2

dynamicDataType (Optional) The dynamic data type.

Format: It is one of the following values:

l CARD_APPLICATION_CRYPTOGRAM_LONG_FORM – Transaction
Authentication Verification Value
l DYNAMIC_CARD_SECURITY_CODE – Dynamic Token Verification
Value
l TAVV Deprecated – Transaction Authentication Verification Value

l DTVV Deprecated – Dynamic Token Verification Value

dpaPanRequested (Optional) Whether PAN data is requested.

Format: It is one of the following values:

l true

l false (default)

2 May 2024 Visa Confidential 20

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Transaction Amount

Field Description
transactionAmount (Required) Amount associated with transaction.
Format: Numeric string; maximum 9 digits before an optional
decimal point and 4 decimal digits after

transactionCurrencyCode (Required) Currency code used for the transaction amount.

Format: ISO 4217 alpha-3 currency code

Custom Input Data

Field Description
checkoutOrchestrator (Optional) Checkout orchestrator. Must be "merchant" for
Merchant Orchestrated Checkout.
Format: String

customFlowType (Optional) Flow type indicator for SRC orchestrated flows.

Format: It is one of the following values:

l paymentsetting

l withincheckout

paymentCardTypeSelected (Optional) Identifies the cardholder selection to process the

transaction as either debit or credit at checkout. Applicable only
when the card product supports both credit and debit (Combo)
options.
Format: It is one of the following values:

l CREDIT

l DEBIT

Init Returns
void

2 May 2024 Visa Confidential 21

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Init Examples

Code

var initParams = {
"srciTransactionId": "...",
"srcInitiatorId": "F14...YE",
"srciDpaId": "F14...YE",
"dpaData": {
"srcDpaId": "F14...YE",
"dpaPresentationName": "...",
"dpaUri": "http://www.---.com",
"dpaThreeDsPreference": "UNKNOWN"
},
"dpaTransactionOptions": {
"dpaLocale": "en_US",
"dpaAcceptedBillingCountries": [
"US",
"CA"
],
"dpaAcceptedShippingCountries": [
"US",
"CA"
],
"dpaBillingPreference": "FULL",
"dpaShippingPreference": "FULL",
"consumerNameRequested": true,
"consumerEmailAddressRequested": true,
"consumerPhoneNumberRequested": true,
"paymentOptions": {
"dynamicDataType":
"CARD_APPLICATION_CRYPTOGRAM_LONG_FORM",
"dpaPanRequested": false
},
"reviewAction": "continue",
"checkoutDescription": "Sample checkout",
"transactionType": "PURCHASE",
"orderType": "REAUTHORIZATION",
"payloadTypeIndicator": "PAYMENT",
"transactionAmount": {
"transactionAmount": "99.95",
"transactionCurrencyCode": "USD"
},
"merchantOrderId": "...",
"merchantCategoryCode": "...",
"merchantCountryCode": "US",
"customInputData": {
//For Merchant Orchestrated Checkout experience:
"checkoutOrchestrator": "merchant"
}
}
};

2 May 2024 Visa Confidential 22

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

async function init(initParams, cb) {

const promiseData = await
vSrc.init(initParams).then(function(response) {
return response;
})
.catch(function(error) {
return error;
});
cb(promiseData);
}
function callInit() {
init(initParams, function(result) {
console.log(result);
if (!Object.keys(result).length) {
console.log("init() successful");
//Next -> call isRecognized()
callIsRecognized();
} else {
console.log("init() failure");
// Some error in init, validate input or retry
}
});
}

Note: Merchant Orchestrated Checkout is indicated by the following JSON structure in

the initParams variable of this example:

"customInputData": {
"checkoutOrchestrator": "merchant"
}

Returns

{}

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

Also, see Standard Error Codes.

2 May 2024 Visa Confidential 23

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Is Recognized (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.

Syntax

isRecognized()

Is Recognized Parameters
None

Is Recognized Returns

Field Description
recognized Whether the consumer is recognized.
Format: It is one of the following values:

l true — recognized

l false — not recognized

idTokens 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.
Required if the consumer is recognized; Not need to be present if
the consumer is not recognized.
Format: List of ID Tokens in JWT format.

2 May 2024 Visa Confidential 24

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Is Recognized Examples

Code

async function isRecognized(cb) {

const promiseData = await vSrc.isRecognized()
.then(function (data) {
return data;
})
.catch(function (err) {
return err;
});
cb(promiseData);
}

function callIsRecognized() {
isRecognized((response) => {
console.log(response);
if (response.recognized) {
// Store the token -> response.idTokens
// User is recognized. Call getSrcProfile with tokens,
// get masked card details, present in UI
callGetSrcProfile(response.idTokens);
} else {
// User is not recognized -> Call identityLookup
callIdentityLookup();
}
});
}

Returns
Recognized:

{
"recognized": true,
"idTokens": [
"eyJ...0g"
]
}
Not recognized:

{"recognized": false,
"idTokens": []
}

2 May 2024 Visa Confidential 25

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Is Recognized Errors
Reason Code Description
ACCT_INACCESSIBLE The account exists but is not currently accessible, e.g., it is locked.

See Standard Error Codes.

Get SRC Profile (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.

Syntax

getSrcProfile(idTokens)

Get SRC Profile Parameters

Field Description
idTokens (Optional) A unique identifier associated with the masked token,
mostly used for multi-SRC systems. If not specified, the SRC system
may fetch cards based on cookie recognition or not return any
cards. The SRCi can provide token IDs received from SRC systems
based on consumer recognition performed via OTP (for
unrecognized customer flow) or cookie (for recognized customer
flow).
Format: List of ID Tokens in JWT format

2 May 2024 Visa Confidential 26

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Get SRC Profile Returns

Field Description
profiles SRC profiles associated with each recognized user using JWT
(idToken).

Format: List of SrcProfile structures

srcCorrelationId The unique identifier generated by SRC system to track and link
SRC messages. This is used as a transaction identifier assigned by
the SRC system for this particular transaction.
Returned when the cards are returned successfully.
Format: Universally Unique Identifier (UUID)

SRC Profile

Field Description
idToken A unique identifier associated with the masked token. The ID token
is returned only for the consumer recognized by this SRC system.
Format: IdToken in JWT format

maskedCards Card list of recognized/authenticated consumer.

Format: List of MaskedCard structures

maskedConsumer Recognized consumer.

Format: MaskedConsumer structure

Masked Consumer

Field Description
firstName The first name of the consumer.
Format: Alphanumeric; between 2–80 characters.

lastName The last name of the consumer.

Format: Alphanumeric; between 2–80 characters.

fullName The full name of the consumer.

Format: Alphanumeric; between 2–80 characters.

2 May 2024 Visa Confidential 27

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Field Description
emailAddress The email address of the consumer.

Note: This field supports internationalization using UTF-8

characters.
Format: A valid email address; maximum 32 bytes

maskedMobileNumber The mobile number of the consumer.

Note: Not returned by the getSrcProfile() method.

Format: MaskedPhoneNumber structure

countryCode Country code associated with the masked address of consumer

country in the SRC system.
Format: ISO-3166-1 alpha-2 standard code

languageCode Consumer's locale.

Format: Locale, based on ISO format for language (ISO 639-1) and
alpha-2 country code (ISO 3166-1 alpha-2). The language and
country should be separated using a (_).

Example: en_US

Masked Phone Number

Field Description
countryCode Phone number country code.
Format: Alphabetic, numeric; maximum 4 characters.

phoneNumber Phone number of the consumer.

Format: A valid phone number; maximum 32 bytes.

Masked Card

Field Description
srcDigitalCardId A unique ID associated with the digital card.
Format: Universally Unique Identifier (UUID)

panBin The bank ID number associated with the card.

Format: String

panLastFour Last 4 digits of the card.

Format: Numeric; maximum 4 digits

tokenBinRange Token's BIN range.

Format: String

2 May 2024 Visa Confidential 28

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Field Description
paymentAccountReference The Payment Account Reference (PAR) associated with the
cardholder account that uniquely identifies the account to which
the payment card is associated
Format: String

tokenLastFour Last 4 digits of the token.

Format: Numeric; maximum 4 digits

panExpirationMonth The month when the account number is set to expire.

Format: Numeric; 2 digits

panExpirationYear The year when the account number is set to expire.

Format: Numeric; 4 digits

digitalCardData The metadata about the card, which contains digital card
information used in the acceptance environment and in the user
interface. This data provides a reference to the actual PAN or
Payment Token without actually disclosing either.
Digital Card Data is grouped together based on the following
categories:

l Digital Card Information: data used in request and response

messages
l UI/UX Presentation Data: the data in user interfaces to provide
the consumer with a recognizable descriptor
l Digital Card Art: image that accompanies Digital Card
information for user interface purposes.
Format: DigitalCardData structure

dateOfCardCreated Timestamp that identifies when this card was enrolled.

Format: UNIX Epoch timestamp. The value is in milliseconds.
Example: 1536926400

dateOfCardLastUsed Timestamp that identifies when this card was last used.
Format: UNIX Epoch timestamp. The value is in milliseconds.
Example: 1536926400

dcf The Digital Card Facilitator (DCF) system. It is present only when
the MaskedCard data structure is used in the checkout or payload
response.
Card experience provider. It is present only when the MaskedCard
data structure is used in the checkout or payload response.
Format: DCF structure

maskedBillingAddress Billing address, which is masked for display purposes.

Format: MaskedAddress structure

2 May 2024 Visa Confidential 29

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Field Description
tokenId Reference identifier to the Token that enables the SRC System to
communicate with the Token Service Provider without transmitting
the actual PAN/Token; Present when PAN is eligible for tokeni­
zation. The reference identifier is associated with the SRC Profile to
which the Payment Card belongs and is unique within an SRC
System.
Format:
String. Alphabetic, numeric [A-Z][a-z][0-9,-], and hyphens ( - ), e.g.,
spaces are not allowed; maximum 36.

paymentCardType Indicates whether the card supports both credit and debit options.
Format: It is a list of one or more of the following values:

l COMBO

Digital Card Data

Field Description
status The digital card status any given time in the SRC system.
Format: It is one of the following values:

l ACTIVE

l SUSPENDED

l EXPIRED

l PENDING

l CANCELLED

presentationName Presentation text created by the consumer to enable recognition of

the PAN entered into the DCF. This value is unique to the DCF and
defined by the consumer.
Format: String; maximum 64 characters

descriptorName Presentation text defined by the SRC programme that describes

the PAN presented as a digital card. This descriptor is the same
across all DCFs.
Format: String; maximum 64 characters

artUri URI of the Art card application. Can be provided by SRC Issuer
(SRCPI) .
Format: A valid URI; maximum 100 characters

artHeight Height of the Art card image, in pixels.

Format: Numeric value between 1 and 4096, inclusive
Example: artHeight: ...

2 May 2024 Visa Confidential 30

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Field Description
artWidth Width of the Art card image, in pixels.
Format: Numeric value between 1 and 4096, inclusive
Example: artWidth : ...

pendingEvents Set of events that are pending completion such as Card Holder
Verification, AVS, SCA, Device Binding, etc. Required when the
value of status is set to PENDING.

Format: It is an array of one or more of the following strings:

l "PENDING_CONSUMER_IDV"

l "PENDING_CONSUMER_DEVICE_BINDING"

l "PENDING_CARDHOLDER_AUTHENTICATION"

authenticationMethod Authentication method indicated by the SRCi to the SRC System.

Format: AuthenticationMethod structure.

Authentication Method

Field Description
authenticationMethodType (Required) SRCi to indicate for a particular transaction if Click to Pay
needs to perform managed authentication or not.
Format: It is one of the following values:

l SMS_OTP

l EMAIL_OTP

l APP_AUTHENTICATION

l MANAGED_AUTHENTICATION

authenticationSubject (Optional) Authentication subject. This should be set to

CARDHOLDER.

Format: It is one of the following values:

l CARDHOLDER

l CONSUMER

l CARD

uriData (Optional) URI associated with the authentication method, if

available.
Format: A UriData structure

2 May 2024 Visa Confidential 31

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Field Description
authenticationCredentialReference (Optional) Authentication credential reference, which may be
provided by the identity provider once an authentication is initiated
to qualify the nature of the authentication method. For example,
SMS_OTP may use the masked mobile number "***-***-1234",
which can be displayed to the Consumer to aid method selection.
Format: String

methodAttributes (Optional) Attributes related to the authentication method; see

"Method Attributes."
Format: JSON object

URI Data

Field Description
uri (Required) Specifies the URI for the given authentication method.
Format: String; maximum 2048 characters

uriType (Required) URI type.

Format: It is one of the following values:

l APP_URI

l WEB_URI

2 May 2024 Visa Confidential 32

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Method Attributes

Field Description
challengeIndicator (Optional) A challenge indicator value related to 3DS authentication.
Format: It is one of the following values:

l 01 - No preference

l 02 - No challenge requested

l 03 - Challenge requested (3DS Requestor Preference)

l 04 - Challenge requested (Mandate)

l 05 - No challenge requested (transactional risk analysis is

already performed)
l 06 - No challenge requested (Data share only)

l 07 - No challenge requested (strong consumer authentication is

already performed)
l 08 - No challenge requested (utilize trust list exemption if no
challenge required)
l 09 - Challenge requested (trust list prompt requested if
challenge required)

otpValue (Conditional) One time password; required when

authenticationMethodType in the authenticationMethod
structure is SMS_OTP or EMAIL_OTP.

Format: String; max. 16 characters

stepUpIdentifier (Conditional) Step-up identification; required when

authenticationMethodType in the authenticationMethod
structure is SMS_OTP, EMAIL_OTP, or APP_AUTHENTICATION.

Digital Card Facilitator (DCF)

Field Description
uri Uniform Resource Identifier (URI), a valid web address or URL
Format: String of characters; maximum 256 characters

logoUri Uniform Resource Identifier (URI) for your company logo.

Format: String of characters; maximum 256 characters
Example: http://test.com

name The name on the digital card.

Format: Alphanumeric; maximum 256 characters

2 May 2024 Visa Confidential 33

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Masked Address
The allowed characters for the address line 1, 2, and 3 are: .',:_#/
()ÁáÀàÂâÄäÃãÇçÉéÈèÊêËëÍíÎîÏïÑñÓóÔôÕõŒœÚúÙùÛûÜüŸÿÆæĄąĆćĘꣳŃńŚśŹźŻż/

Field Description
addressId The ID associated with the masked address in the SRC system.
Format: String

line1 Line 1 of the masked address in the SRC system. Required for
shipping address.
Format: Alphanumeric, Maximum 140 characters. For country
specific information, see Visa Checkout Address Formats by Country.
Example: 1** M*** St

line2 Line 2 of the masked address in the SRC system. Required for
shipping address.
Format: Alphanumeric, Maximum 140 characters.

line3 Line 3 of the masked address in the SRC system. Required for
shipping address.
Format: Alphanumeric, Maximum 140 characters.

city City name associated with the masked address in the SRC system.
The address must have the city name in the valid address format
for the country.
Format: Alphanumeric, UTF-8 white space; maximum 100
characters

state State code associated with the masked address in the SRC system.
The address must have the state name in the valid address format
for the country.
Must be a valid 2-characters code for US and CA and a valid 3-
characters code for AU.

Format: String
Example: VA

zip The zip code associated with the masked address.

Format: Alphanumeric, maximum 3–16 characters.

countryCode Country code associated with the masked address in the SRC
system.
Format: ISO-3166-1 alpha-2 standard code
Example: US

2 May 2024 Visa Confidential 34

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Field Description
createTime Date and time the masked address was created.
Format: String; 25 characters

lastUsedTime Date and time the masked address was last used.
Format: UNIX Epoch timestamp. The value is in milliseconds.

Get SRC Profile Examples

Code

async function getSrcProfile(input, cb) {

let promiseData = await vSrc.getSrcProfile(input)
.then(function (data) {
return data;
})
.catch(function (err) {
return err;
});
cb(promiseData);
}

function callGetSrcProfile(_idTokens) {
getSrcProfile(_idTokens, function (result) {
console.log(result);
// Present the list of cards to user for selection
// List of Cards -> result.profiles[0].maskedCards
});
}

Returns

{
"profiles": [
{
"idToken": "eyJ...g",
"maskedCards": [
{
"cardError": null,
"dateofCardCreated": 1556589662806,
"dateofCardLastUsed": 1563181766426,
"dcf": {
"type": null
},
"digitalCardData": {

"artHeight": 105,
"artUri":"https://sandbox.secure.checkout.visa.com/
VmeCardArts/....png",

2 May 2024 Visa Confidential 35

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

"artWidth": 164,
"status": "ACTIVE"
},
"eligible": true,
"maskedBillingAddress": {
"addressId": "e0d...01",
"city": "*****",
"countryCode": "US",
"line1": "Asd*****",
"line2": null,
"line3": null,
"state": "VA",
"zip": "*****"
},
"panBin": null,
"panExpirationMonth": "12",
"panExpirationYear": "2023",
"panLastFour": "1111",
"srcDigitalCardId": "c96...01"
},
{
"cardError": null,
"dateofCardCreated": 1512433695415,
"dateofCardLastUsed": 1562743621206,
"dcf": {
"type": null
},
"digitalCardData": {
"artHeight": 105,
"artUri": "https://sandbox.secure.checkout.visa.com/
VmeCardArts/....png"
"artWidth": 164,
"status": "ACTIVE"
},
"eligible": true,
"maskedBillingAddress": {
"addressId": "89e...01",
"city": "*****",
"countryCode": "CA",
"line1": "Can*****",
"line2": null,
"line3": null,
"state": "ON",
"zip": "*****"
},
"panBin": null,
"panExpirationMonth": "09",
"panExpirationYear": "2019",
"panLastFour": "2958",
"srcDigitalCardId": "301...01"
}
],
"maskedConsumer": {
"firstName": "T*****",
"lastName": "K*****",
"fullName": "T***** K*****",
"emailAddress": "the**@gmail.com",
"countryCode": "US",

2 May 2024 Visa Confidential 36

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

"languageCode": "en-US"
}
}
],
"srcCorrelationId": "750...01"
}

Get SRC Profile Errors

Reason Code Description

AUTH_INVALID Invalid authorization.

ACCT_INACCESSIBLE Account exists but is not currently accessible, e.g. is locked

Also, see Standard Error Codes.

Identity Lookup Account by

Consumer ID (identityLookup)
Obtains the user account associated with the consumer’s identity (an email address or phone
number).

Syntax

identityLookup(consumerIdentity)

2 May 2024 Visa Confidential 37

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Identity Lookup Parameters

Field Description
identityProvider (Optional) The Identity provider.
The default value is SRC.

Format: String

identityValue (Required) Value of the consumer identity, which is used to locate

information within the SRC profile.

Note: This is a Consumer-provided value, not a SRC

Consumer Reference Identifier.
Format: String
Example: [email protected]

type (Required) The type of the consumer identity.

It is one of the following values:

l EMAIL

l MOBILE_NUMBER

l CUSTOM_IDENTIFIER

l FUTURE

Format: String

Identity Lookup Returns

Field Description
consumerPresent Whether the consumer exists in the SRC system.
Format: It is one of the following values:

l true – the consumer is present

l false – the consumer is not present

2 May 2024 Visa Confidential 38

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Identity Lookup Examples

Code

async function identityLookup(input, cb) {

let promiseData = await vSrc.identityLookup(input)
.then(function (data) {
return data;
})
.catch(function (err) {
return err;
});
cb(promiseData);
}
function callIdentityLookup() {
var consumerIdentity = {
identityProvider: 'SRC',
identityValue: '[email protected]',
type: 'EMAIL'
}
identityLookup(consumerIdentity, function (result) {
console.log(result);
if (result.consumerPresent) {
// Consumer present -> call initiateIdentityValidation
callInitiateIdentityValidation();
} else {
...
};
});
}

Returns

{
"consumerPresent": true
}

Identity Lookup Errors

Reason Code Description

FRAUD The user account was locked or disabled.

ID_FORMAT_UNSUPPORTED Unsupported ID format.

CONSUMER_ID_MISSING Consumer identity is missing in the request.

ACCT_INACCESSIBLE The account exists but is not currently accessible, e.g. it is locked.

2 May 2024 Visa Confidential 39

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Also, see Standard Error Codes.

Initiate Identity Validation

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

Syntax

initiateIdentityValidation()

Initiate Identity Validation Parameters

None

Initiate Identity Validation Returns

Field Description
maskedValidationChannel Masked email and phone number, if available, used to deliver the
validation code (like OTP).
Example: "u**@example.com,*********67"

Initiate Identity Validation Examples

Code

async function initiateIdentityValidation(cb) {

let promiseData = await vSrc.initiateIdentityValidation()
.then(function (data) {
return data;
})
.catch(function (err) {
return err;

2 May 2024 Visa Confidential 40

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

});
cb(promiseData);
}

function callInitiateIdentityValidation() {
initiateIdentityValidation(function (result) {
console.log(result);
if(result.maskedValidationChannel){
// Present UI and get the OTP from user
}
});
}

Returns

{
"maskedValidationChannel": "u**@example.com,*********67"
}

Initiate Identity Validation Errors

Reason Code Description

OTP_SEND_FAILED The OTP could not be sent to the recipient.

RETRIES_EXCEEDED The number of retries for generating the OTP exceeded the limit.
ID_INVALID Invalid ID.
UNRECOGNIZED_CONSUMER_ID Consumer ID could not be recognized.

ACCT_INACCESSIBLE The account exists but is not currently accessible, e.g. it is locked.

Also, see Standard Error Codes.

Complete Identity Validation

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

2 May 2024 Visa Confidential 41

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Syntax

completeIdentityValidation(validationData)

Complete Identity Validation Parameters

Field Description
validationData (Required) One Time Password (OTP) code, submitted by the
consumer.
Format: String containing a 6-digit OTP code.

Complete Identity Validation Returns

Field Description
idToken SRC ID token created by the SRC system after successful consumer
authentication.
Format: The ID Token in JWT format

Complete Identity Validation Examples

Code

function callCompleteIdValidationClicked(){
var otp = document.getElementById('otpBtnVal').value;
validationData = {
validationData: otp
};
callCompleteIdValidation(validationData);
}

async function completeIdentityValidation(input, cb) {

let promiseData = await vSrc.completeIdentityValidation(input)
.then(function (data) {
return data;
})
.catch(function (err) {
return err;
});

2 May 2024 Visa Confidential 42

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

cb(promiseData);
}

function callCompleteIdValidation(otp) {
completeIdentityValidation(otp, function (result) {
console.log(result);
if(!result.error){
// Store the token -> result.idToken
// call getSrcProfile with tokens,
// get masked card details, present in UI
var idTokens = []; // Or get previous idTokens array, if any
idTokens.push(result.idToken);
callGetSrcProfile(idTokens);
}else{
// validation error
}
});
}

Returns

{
"idToken": "eyJ...0g"
}

Complete Identity Validation Errors

Reason Code Description

CODE_INVALID The supplied OTP value was invalid. Try again.

CODE_EXPIRED The OTP is expired. Regenerate the OTP and try again.

RETRIES_EXCEEDED The limit for the number of retries for OTP generation was
exceeded.

VALIDATION_DATA_MISSING Validation data missing.

ACCT_INACCESSIBLE The account exists but is not currently accessible, e.g. it is locked.

Also, see Standard Error Codes.

2 May 2024 Visa Confidential 43

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Checkout (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, such as 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.

Requirements When Checking Out With a New Card

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

l primaryAccountNumber

l panExpirationMonth

l panExpirationYear

l cardSecurityCode

l cardholderFullName

You must also pass the mobileNumber field in the consumer parameter.

Optionally, you can include the billing address in the encryptedCard parameter and the
emailAddress field in the consumer parameter.

Requirements When Checking Out With an Existing Card

You must specify the ID of the selected card in the srcDigitalCardId parameter.

Syntax

checkout(data)

2 May 2024 Visa Confidential 44

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Checkout Parameters

Field Description
srcCorrelationId (Optional) Correlation ID generated by the SRC system and
returned by getSrcProfile.

Format: Universally Unique Identifier (UUID)

srciTransactionId (Required) A unique ID created by the SRCi

Format: Alphanumeric, maximum 100 characters
srcDigitalCardId (Conditional) ID of the selected card.
Required if any card is selected from the SRC profile, returned by
the SRC system.
Format: String
encryptedCard (Conditional) An encrypted card object, which describes the card to
be enrolled with the SRC system. The public key of the target SRC
system is used for encryption.
This is a JWE with a single composite JSON Card object at the root
with card as the claimset element.

Required if a new card is added to the SRC profile. For details, see
Generating a JWE for PAN Encryption .
Format: JWE Card structure

idToken (Conditional) A 3rd party federated identity token that allows the
SRC systems to communicate with each other for SRC user identity
verification. When a card is selected, it might be necessary to pass
the ID token corresponding to the selected card, if this information
is available in SRCi.
Required when a consumer enters a new card, particularly in the
following scenarios:

l Multiple ID tokens are returned by an SRC system

l The SRC system never returned SRC profile
Format: The ID Token in JWT format
windowRef (Conditional) The window handle to open a custom URI in the
popup/iframe window. This window hosts the user interface.
Required if open a custom URI in the popup or iframe window. This
window hosts:

l If the window reference is provided, the DCF will be launched in

the same window.
l If the window reference is not provided, the DCF will be
launched in a new window.
Format: window

2 May 2024 Visa Confidential 45

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Field Description
dpaTransactionOptions (Conditional) DPA configuration data, which overrides the configu­
ration on the SRC system that was created during DPA registration.
Required if not supplied in the init call.

Format: DpaTransactionOptions structure

consumer (Optional) Consumer identity or profile information collected by an

SRCi, payment service provider, or merchant.
Format: Consumer structure.

complianceSettings (Optional) Compliance settings that provide data needed for DCF
suppression in the add card flow.
Format: ComplianceSettings structure.

authenticationContext (Conditional) Transaction context data that SRC System uses to

perform authentication; required for some Visa regions, such as
Europe.
Format: AuthenticationContext structure.

authenticationMethod (Conditional) Authentication method indicated by the SRCi to the

SRC System.
Format: AuthenticationMethod structure.

shippingAddress (Optional) Shipping address. Recommended when SRCi preference

to perform authentication and to receive authentication data for
the transaction is true; determined by the
authenticatedCredentialRequested field in the
dpaTransactionOptions structure.

Format: Address structure.

assuranceData (Optional) Information about any risk assessment operations

performed by the SRC system.
Format: AssuranceData structure.

encryptedBillingAddress (Optional) Billing address; it is recommended to include this field

when a billing address has not been associated with the selected
card.
Format: JWE Address structure

2 May 2024 Visa Confidential 46

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

DPA Transaction Options

This structure represents the config parameters that are common across all transactions,
originates from the Digital Payment Application (DPA).

Field Description
dpaLocale (Optional) DPA’s preferred locale. This can be the same as the locale
in the init parameters or can be different.

Format: Based on ISO format for language (ISO 639-1) and alpha-2
country code (ISO 3166-1 alpha-2). The language and country
should be separated using an underscore ( _ ).

Example: en_US, fr_CA

dpaAcceptedBillingCountries (Optional) Billing countries. Payments from the listed billing

countries are accepted. If this list is empty, all countries are
accepted.
Format: Array of country codes in ISO 3166-1 alpha-2 format
Example: ["US”, “CA”, “AU”]

dpaAcceptedShippingCountries (Optional) Shipping countries; shipping region country codes that

limit the selection of eligible shipping addresses. If this list is empty,
all countries are accepted.
Format: Array of country codes in ISO 3166-1 alpha-2 format

dpaBillingPreference (Optional) Verbosity of billing address required by the DPA.

Format: It is one of the following values:

l FULL (default)

l POSTAL_COUNTRY

l NONE

dpaShippingPreference (Optional) Extent to which DPA wants to have shipping address

collected. Not required for Merchant Orchestrated Checkout; if
passed, it will be changed to NONE.

Format: It is one of the following values:

l FULL (default)

l POSTAL_COUNTRY

l NONE

consumerNameRequested (Optional) Whether the name of the consumer has been requested.
Format: It is one of the following values:

l true (default)

l false

2 May 2024 Visa Confidential 47

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Field Description
consumerEmailAddressRequested (Optional) Whether the email address of the consumer has been
requested.
Format: It is one of the following values:

l true (default)

l false

consumerPhoneNumberRequested (Optional) Whether the Phone number of the consumer has been
requested.
Format: It is one of the following values:

l true (default)

l false

consumerNationalIdentifier (Optional) Whether the Consumer National identifier for the

Requested consumer is requested.
Format: It is one of the following values:

l true

l false

paymentOptions (Optional) Payment options requested by the DPA.

Format: PaymentOptions structure

reviewAction (Optional) Whether the payment will be processed immediately

after selection or after confirmation.
Format: It is one of the following values:

l pay -- proceed after selection

l continue -- proceed after confirmation (default)

checkoutDescription (Optional) Review message to go with action.

Format: String

transactionType (Optional) Type of the transaction.

Format: It is one of the following values:

l PURCHASE (default)

l BILL_PAYMENT

l MONEY_TRANSFER

orderType (Optional) Type of orders.

Deprecated Format: It is one of the following values:

l REAUTHORIZATION

l RECURRING

l INSTALLMENT

2 May 2024 Visa Confidential 48

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Field Description
transactionInstruction (Optional) Transaction instruction.
Format: Enum; it is one of the following values:

l RECURRING_PAYMENTS

l SUBSCRIPTION_SERVICES

l INSTALLMENTS

numberOfPayments (Conditional) Maximum number of authorizations for installment

payments. Required when transactionInstruction is specified.

Format:
purchaseDate (Conditional) Original purchase date. Required when
transactionInstruction is specified.

Format: UNIX Epoch timestamp. The value is in milliseconds.

recurringEndDate (Conditional) The date after which no further recurring authori­
zations should be performed. Required when
transactionInstruction is specified.

Format: UNIX Epoch timestamp. The value is in milliseconds.

recurringFrequency (Conditional) Minimum number of days between recurring authori­
zations. Required when transactionInstruction is specified.

Format: Integer

payloadTypeIndicator (Optional) The verbosity of payload requested.

Format: Enum, it is one of the following values:

l FULL - includes everything; all PCI & PII data (card/token, billing,
shipping, consumer)
l SUMMARY - (default) no JWE. If FULL needed during checkout,
SRCi needs to make a request for it explicitly.
l PAYMENT - same as FULL

l NON_PAYMENT - only PII (billing, shipping, consumer). It has both

SUMMARY and encryptedPayload without card, token, or
dynamicData.

l NONE - just srcCorrelationId (with COMPLETE

dcfActionCode)

transactionAmount (Conditional) Amount of the transaction.

Required when transaction authentication is performed.
Format: TransactionAmount structure

merchantOrderId (Optional) The order identifier generated by the DPA. Typically used
for reconciliation process by the DPA.
Format: Universally Unique Identifier (UUID)

2 May 2024 Visa Confidential 49

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Field Description
merchantCategoryCode (Optional) Code associated with Merchant Category
Format: 4-digit string

merchantCountryCode (Optional) The country code associated with the merchant’s billing
or shipping address.
Format: ISO-3166 - 1 alpha-2 standard code
Example: US – United States

threeDsInputData (Deprecated) If 3DS is requested for the transaction, this attribute is

required.
Format: ThreeDSInputData structure

dpaThreeDsPreference (Deprecated) Do not specify a value here. Set

dpaThreeDsPreference in the dpaData structure instead.

authenticatedCredentialRequested (Optional) SRCi preference to perform authentication and to receive

authentication data for the transaction.
Format: It is one of the following values:

l true

l false (default)

customInputData (Optional) Custom input data elements presented to the SRC

System.
Format: CustomInputData structure; see "Custom Input Data."

2 May 2024 Visa Confidential 50

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Payment Options

Parameter Description
dpaDynamicDataTtlMinutes (Optional) The minimum requested validity period for the
transaction credentials, such as a cryptogram, returned by the SRC
system, in minutes.
If this is not provided, the values are determined by the SRCs.
Format: integer
Example: 2

dynamicDataType (Optional) The dynamic data type.

Format: It is one of the following values:

l CARD_APPLICATION_CRYPTOGRAM_LONG_FORM – Transaction
Authentication Verification Value
l DYNAMIC_CARD_SECURITY_CODE – Dynamic Token Verification
Value
l TAVV Deprecated – Transaction Authentication Verification Value

l DTVV Deprecated – Dynamic Token Verification Value

dpaPanRequested (Optional) Whether PAN data is requested.

Format: It is one of the following values:

l true

l false (default)

Transaction Amount

Field Description
transactionAmount (Required) Amount associated with transaction.
Format: Numeric string; maximum 9 digits before an optional
decimal point and 4 decimal digits after

transactionCurrencyCode (Required) Currency code used for the transaction amount.

Format: ISO 4217 alpha-3 currency code

2 May 2024 Visa Confidential 51

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Custom Input Data

Field Description
checkoutOrchestrator (Optional) Checkout orchestrator. Must be "merchant" for
Merchant Orchestrated Checkout.
Format: String

customFlowType (Optional) Flow type indicator for SRC orchestrated flows.

Format: It is one of the following values:

l paymentsetting

l withincheckout

paymentCardTypeSelected (Optional) Identifies the cardholder selection to process the

transaction as either debit or credit at checkout. Applicable only
when the card product supports both credit and debit (Combo)
options.
Format: It is one of the following values:

l CREDIT

l DEBIT

Consumer

Field Description
firstName (Optional) Consumer’s first name.
Format: String; maximum 30 characters

lastName (Optional) Consumer’s last name.

Format: Alphanumeric; between 2–80 characters

fullName (Optional) Consumer’s full name.

Format: Alphanumeric; between 2–80 characters

mobileNumber (Conditional) Consumer's phone number. Required when adding a

new card.
Format: PhoneNumber structure

countryCode (Optional) The country code associated with the address.

Format: ISO-3166-1 alpha-2 standard code
Example: AU - Australia

2 May 2024 Visa Confidential 52

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Field Description
languageCode (Optional) Consumer's locale.
Format: Locale, based on ISO format for language (ISO 639-1) and
alpha-2 country code (ISO 3166-1 alpha-2). The language and
country should be separated using a (_).
Example: en_US

consumerIdentity (Optional) Primary verifiable consumer identifier within an SRC

Profile; for example, an email address.

Note: Mobile phone numbers are not supported.

Format: A consumerIdentity structure

nationalIdentifier (Optional) Geographic­specific, nationally-provided identifier for the

Consumer.
Format: String; max. 20 characters

Phone Number

Field Description
countryCode The country code associated with the consumer phone number.
Format: String
Example: 380 for Ukraine

phoneNumber Phone number without country code.

Format: String; numeric, 4 to 14 digits.

2 May 2024 Visa Confidential 53

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Consumer Identity

Field Description
identityProvider (Optional) The Identity provider.
The default value is SRC

Format: String

identityValue (Required) Value of the consumer identity, which is used to locate

information within the SRC profile.

Note: Only an email address is supported.

Format: String
Example: [email protected]

identityType (Required) The type of the consumer identity.

It is one of the following values:

l EMAIL_ADDRESS

Format: String

Card

Field Description
primaryAccountNumber (Required) The account number of the card to be enrolled and
provisioned.
Format: Numeric

panExpirationMonth (Required) The account number expiration month.

Format: Numeric, 2 digits, MM

panExpirationYear (Required) The account number expiration year.

Format: Numeric, 4 digits, YYYY

cardSecurityCode (Conditional) The card security code (CVV2) value associated with
the account number on the card, if available. Required for those
cards that a card security code.
Format: Numeric, 3-4 digits

cardholderFullName (Conditional) The full name of the cardholder on the card. Required
if the billingAddress name field or the cardHolderFirstName
and cardHolderLastName are not passed.

Format: String
cardholderFirstName (Optional) The first name of the cardholder.
Format: String

2 May 2024 Visa Confidential 54

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Field Description
cardholderLastName (Optional) The last name of the cardholder.
Format: String

billingAddress (Optional) Billing address.

Format: An address structure.

paymentAccountReference (Conditional) The Payment Account Reference (PAR) associated with

the cardholder account that uniquely identifies the account to
which the payment card is associated.

Format: String

Address
The allowed characters for the address line 1, 2, and 3 are: .',:_#/
()ÁáÀàÂâÄäÃãÇçÉéÈèÊêËëÍíÎîÏïÑñÓóÔôÕõŒœÚúÙùÛûÜüŸÿÆæĄąĆćĘꣳŃńŚśŹźŻż/

Field Description
addressId (Conditional) The address identifier in the SRC system.
Format: Universally Unique Identifier (UUID)

name (Conditional) The recipient name for the address, if known.

Required when known to the SRC system for this address
Format: Alphanumeric; maximum 140 characters

line1 (Conditional) Line 1 of the address. Required if this is a shipping

address in a valid format for the country.
Format: Maximum 140 characters. Alphanumeric

line2 (Optional) Line 2 of the address.

Format: Maximum 140 characters. Alphanumeric

line3 (Optional) Line 3 of the address.

Format: Maximum 140 characters. Alphanumeric

city (Conditional) The city associated with the address. Required if this is
a shipping address in a valid format for the country.
Format: Alphanumeric, maximum 100 characters.

state (Conditional) The state associated with the address. Required if this
is a shipping address in a valid format for the country.
Format: String

2 May 2024 Visa Confidential 55

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Field Description
zip (Conditional) The zip code associated with the address. Required if
this is a shipping address in a valid format for the country and has
a postal code or zip code.
Format: Alphabetic, numeric; 3–16 characters.

countryCode (Required) The country code associated with the address.

Format: ISO-3166-1 alpha-2 standard code
Example: AU - Australia

Compliance Settings

Field Description
complianceResources (Conditional) One or more compliance resources, which consists of
a single compliance type and URI. Required when
complianceSettings is specified.

Format: Array of complianceType and uri pairs.

complianceType (Required) Compliance type.

Format: String. It is one of the following values:

l TERMS_AND_CONDITIONS

l PRIVACY_POLICY

l REMEMBER_ME

uri (Required) Uniform Resource Identifier (URI), a valid web address or

URL
Format: String of characters; maximum 1024 characters

2 May 2024 Visa Confidential 56

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Authentication Context

Field Description
authenticationReasons (Required) SRCi-provided authentication reasons used by the SRC
System to perform authentication.
Format: They are one or more of the following enumerated values:

l TRANSACTION_AUTHENTICATION

l NOT_PREFERRED

srciDpaId (Conditional) DPA identifier, which is generated by the SRC system

during DPA registration. Either srciDpaId or a dpaData structure
must be provided when authenticationReasons is
TRANSACTION_AUTHENTICATION.

Format: String, 64 bytes

dpaData (Conditional) DPA registration data.

Format: A DpaData structure.

dpaTransactionOptions (Optional) DPA configuration data, which overrides the configu­

ration on the SRC system that was created during DPA registration.
Ignored if supplied in the init call or elsewhere in the checkout
call.
Format: DpaTransactionOptions structure

acquirerMerchantId (Required) Acquirer-assigned Merchant identifier. Value must be

provided to perform transaction authentication by the SRC System.
Format: String

acquirerBIN (Required) Acquirer identification code as assigned by the Directory

Server. Value must be provided to perform transaction authenti­
cation by the SRC System.
Format: String

merchantName (Required) Merchant name assigned by the Acquirer or Payment

System. Value must be provided to perform transaction authenti­
cation by the SRC System.
Format: String

2 May 2024 Visa Confidential 57

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Authentication Method

Field Description
authenticationMethodType (Required) SRCi to indicate for a particular transaction if Click to Pay
needs to perform managed authentication or not.
Format: It is one of the following values:

l SMS_OTP

l EMAIL_OTP

l APP_AUTHENTICATION

l MANAGED_AUTHENTICATION

authenticationSubject (Optional) Authentication subject. This should be set to

CARDHOLDER.

Format: It is one of the following values:

l CARDHOLDER

l CONSUMER

l CARD

uriData (Optional) URI associated with the authentication method, if

available.
Format: A UriData structure

authenticationCredentialReference (Optional) Authentication credential reference, which may be

provided by the identity provider once an authentication is initiated
to qualify the nature of the authentication method. For example,
SMS_OTP may use the masked mobile number "***-***-1234",
which can be displayed to the Consumer to aid method selection.
Format: String

methodAttributes (Optional) Attributes related to the authentication method; see

"Method Attributes."
Format: JSON object

2 May 2024 Visa Confidential 58

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

URI Data

Field Description
uri (Required) Specifies the URI for the given authentication method.
Format: String; maximum 2048 characters

uriType (Required) URI type.

Format: It is one of the following values:

l APP_URI

l WEB_URI

Method Attributes

Field Description
challengeIndicator (Optional) A challenge indicator value related to 3DS authentication.
Format: It is one of the following values:

l 01 - No preference

l 02 - No challenge requested

l 03 - Challenge requested (3DS Requestor Preference)

l 04 - Challenge requested (Mandate)

l 05 - No challenge requested (transactional risk analysis is

already performed)
l 06 - No challenge requested (Data share only)

l 07 - No challenge requested (strong consumer authentication is

already performed)
l 08 - No challenge requested (utilize trust list exemption if no
challenge required)
l 09 - Challenge requested (trust list prompt requested if
challenge required)

otpValue (Conditional) One time password; required when

authenticationMethodType in the authenticationMethod
structure is SMS_OTP or EMAIL_OTP.

Format: String; max. 16 characters

stepUpIdentifier (Conditional) Step-up identification; required when

authenticationMethodType in the authenticationMethod
structure is SMS_OTP, EMAIL_OTP, or APP_AUTHENTICATION.

2 May 2024 Visa Confidential 59

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Assurance Data

Field Description
verificationData (Required) Set of verification data structures relating to distinct
types of assurance.
Format: List of VerificationData structures.

eci (Optional) If present, a value indicating the result of the authenti­

cation performed or attempted during a transaction. Use this value
in the e-commerce authorization message to VisaNet.
Format: String; maximum 2 digits. It is one of the following values:

l 05 – Successful authentication

l 06 – Authentication attempted

l 07 – Authentication not performed

Verification Data

Field Description
verificationType (Required) Type of verification data.
Format: It is one of the following values:

l CARDHOLDER

verificationEntity (Required) Entity performing the verification.

Format: It is one of the following values:

l 01 - SRC Initiator

l 03 – SRCPI

verificationEvents (Optional) Event causing the verification to occur.

Format: Array that can contain the following values:

l 01 – Payment transaction

l 02 – Add card/Card enrollment

l 03 – SRC Profile access

l 04 – Account verification

2 May 2024 Visa Confidential 60

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Field Description
verificationMethod (Required) Method of verification.
Format: It is one of the following values:

l 02 – App-based authentication

l 04 – One-time passcode

l 21 – Visa Token Service step–up: Device binding

l 22 – Visa Token Service step–up: Cardholder verification

verificationResults (Required) Result of the verification.

Format: It is one of the following values:
01 – Verified

02 – Not Verified

03 – Not performed

04 – Not required

21 – Not allowed

verificationTimestamp (Required) Date and time in UTC that the verification was
conducted.
Format: UNIX Epoch timestamp.

methodResults (Optional) Method results.

Format: JSON object

Method Results
Attributes related to the results of a given authentication method.

2 May 2024 Visa Confidential 61

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Field Description
transStatus (Optional) Whether a transaction qualifies as an authenticated
transaction (for 3DS authentication).
Format: It is one of the following string values:

l "Y"

l "R"

l "C"

l "N"

l "U"

l "A"

l "D"

l "I"

dsTransId (Optional) ID assigned by the DS to identify the transaction (for 3DS

authentication).
Format: String; UUID

acsTransId (Optional) ID assigned by the ACS to identify the transaction (for

3DS authentication).
Format: String; UUID

Note:
Refer to the EMVCo 3DS Specification for more details on the 3DS­specific attributes and
definitions.

2 May 2024 Visa Confidential 62

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Checkout Returns

Field Description
checkoutResponse The JWS of the checkout response.
Format: JWS of Checkout Response. For details, see Authenticated
Data Token for Checkout Response

dcfActionCode Indicates the action code received from the DCF.

Format: String, it is one of the following values:

l COMPLETE — DCF processing completed normally

l CHANGE_CARD — consumer selected an alternative card

l ADD_CARD — consumer added a new card

l SWITCH_CONSUMER — consumer changed account profile /

identity
l CANCEL — consumer cancelled the flow

l ERROR — an error was detected and the DCF processing could

not be continued

unbindAppInstance Disassociates the consumer’s application and device from the

consumer’s SRC profile on each network.
Format: String, it is one of the following values:

l false — the consumer checks out and the payload is passed

back to the DPA.(default)
l true — returns SWITCH_CONSUMER and disassociates the
consumer from the app and device

idToken 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.
Format: List of ID Tokens in JWT format

2 May 2024 Visa Confidential 63

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Checkout Response

Field Description
srcCorrelationId The unique identifier generated by SRC system to track and link
SRC messages. This is used as a transaction identifier assigned by
the SRC system for this particular transaction.
Returned when cards are returned.
Format: Universally Unique Identifier (UUID)

srciTransactionId 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.
Format: Alphanumeric, maximum 100 characters

maskedCard Masked card information.

Format: MaskedCard structure.

shippingAddressZip Zip code of the address being shipped to. The zip code must have
been requested in DPA shipping preferences.
Format: String

shippingCountryCode Country code of the address being shipped to. The country must
have been requested in the DPA shipping preferences.
Format: Country Code2, ISO-3166-1, alpha-2 standard code
Example: AU - Australia

maskedConsumer Masked information about the consumer for display purposes.

Format: MaskedConsumer structure.

encryptedPayload Encrypted payload to be given to the merchant. It is returned only

when PCI/PII data is requested by the DPA during a SRC
transaction.
Format: String

assuranceData Information about any risk assessment operations performed by

the SRC system.
Format: AssuranceData structure.

2 May 2024 Visa Confidential 64

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Field Description
isGuestCheckout Whether the consumer checked out as a guest.
Format: It is One of the following values:

l true – the consumer checked out as a guest

l false – the consumer did not check out as a guest (default)

isNewUser Whether the consumer enrolled during checkout in this

transaction.
Format: It is one of the following values:

l true – the consumer enrolled during checkout in this

transaction
l false – the consumer did not enroll during checkout in this
transaction (default)

Masked Card

Field Description
srcDigitalCardId A unique ID associated with the digital card.
Format: Universally Unique Identifier (UUID)

panBin The bank ID number associated with the card.

Format: String

panLastFour Last 4 digits of the card.

Format: Numeric; maximum 4 digits

tokenBinRange Token's BIN range.

Format: String

paymentAccountReference The Payment Account Reference (PAR) associated with the

cardholder account that uniquely identifies the account to which
the payment card is associated
Format: String

tokenLastFour Last 4 digits of the token.

Format: Numeric; maximum 4 digits

panExpirationMonth The month when the account number is set to expire.

Format: Numeric; 2 digits

panExpirationYear The year when the account number is set to expire.

Format: Numeric; 4 digits

2 May 2024 Visa Confidential 65

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Field Description
digitalCardData The metadata about the card, which contains digital card
information used in the acceptance environment and in the user
interface. This data provides a reference to the actual PAN or
Payment Token without actually disclosing either.
Digital Card Data is grouped together based on the following
categories:

l Digital Card Information: data used in request and response

messages
l UI/UX Presentation Data: the data in user interfaces to provide
the consumer with a recognizable descriptor
l Digital Card Art: image that accompanies Digital Card
information for user interface purposes.
Format: DigitalCardData structure

dateOfCardCreated Timestamp that identifies when this card was enrolled.

Format: UNIX Epoch timestamp. The value is in milliseconds.
Example: 1536926400

dateOfCardLastUsed Timestamp that identifies when this card was last used.
Format: UNIX Epoch timestamp. The value is in milliseconds.
Example: 1536926400

dcf The Digital Card Facilitator (DCF) system. It is present only when
the MaskedCard data structure is used in the checkout or payload
response.
Card experience provider. It is present only when the MaskedCard
data structure is used in the checkout or payload response.
Format: DCF structure

maskedBillingAddress Billing address, which is masked for display purposes.

Format: MaskedAddress structure

tokenId Reference identifier to the Token that enables the SRC System to
communicate with the Token Service Provider without transmitting
the actual PAN/Token; Present when PAN is eligible for tokeni­
zation. The reference identifier is associated with the SRC Profile to
which the Payment Card belongs and is unique within an SRC
System.
Format:
String. Alphabetic, numeric [A-Z][a-z][0-9,-], and hyphens ( - ), e.g.,
spaces are not allowed; maximum 36.

paymentCardType Indicates whether the card supports both credit and debit options.
Format: It is a list of one or more of the following values:

l COMBO

2 May 2024 Visa Confidential 66

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Digital Card Data

Field Description
status The digital card status any given time in the SRC system.
Format: It is one of the following values:

l ACTIVE

l SUSPENDED

l EXPIRED

l PENDING

l CANCELLED

presentationName Presentation text created by the consumer to enable recognition of

the PAN entered into the DCF. This value is unique to the DCF and
defined by the consumer.
Format: String; maximum 64 characters

descriptorName Presentation text defined by the SRC programme that describes

the PAN presented as a digital card. This descriptor is the same
across all DCFs.
Format: String; maximum 64 characters

artUri URI of the Art card application. Can be provided by SRC Issuer
(SRCPI) .
Format: A valid URI; maximum 100 characters

artHeight Height of the Art card image, in pixels.

Format: Numeric value between 1 and 4096, inclusive
Example: artHeight: ...

artWidth Width of the Art card image, in pixels.

Format: Numeric value between 1 and 4096, inclusive
Example: artWidth : ...

pendingEvents Set of events that are pending completion such as Card Holder
Verification, AVS, SCA, Device Binding, etc. Required when the
value of status is set to PENDING.

Format: It is an array of one or more of the following strings:

l "PENDING_CONSUMER_IDV"

l "PENDING_CONSUMER_DEVICE_BINDING"

l "PENDING_CARDHOLDER_AUTHENTICATION"

authenticationMethod Authentication method indicated by the SRCi to the SRC System.

Format: AuthenticationMethod structure.

2 May 2024 Visa Confidential 67

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Authentication Method

Field Description
authenticationMethodType (Required) SRCi to indicate for a particular transaction if Click to Pay
needs to perform managed authentication or not.
Format: It is one of the following values:

l SMS_OTP

l EMAIL_OTP

l APP_AUTHENTICATION

l MANAGED_AUTHENTICATION

authenticationSubject (Optional) Authentication subject. This should be set to

CARDHOLDER.

Format: It is one of the following values:

l CARDHOLDER

l CONSUMER

l CARD

uriData (Optional) URI associated with the authentication method, if

available.
Format: A UriData structure

authenticationCredentialReference (Optional) Authentication credential reference, which may be

provided by the identity provider once an authentication is initiated
to qualify the nature of the authentication method. For example,
SMS_OTP may use the masked mobile number "***-***-1234",
which can be displayed to the Consumer to aid method selection.
Format: String

methodAttributes (Optional) Attributes related to the authentication method; see

"Method Attributes."
Format: JSON object

2 May 2024 Visa Confidential 68

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

URI Data

Field Description
uri (Required) Specifies the URI for the given authentication method.
Format: String; maximum 2048 characters

uriType (Required) URI type.

Format: It is one of the following values:

l APP_URI

l WEB_URI

Method Attributes

Field Description
challengeIndicator (Optional) A challenge indicator value related to 3DS authentication.
Format: It is one of the following values:

l 01 - No preference

l 02 - No challenge requested

l 03 - Challenge requested (3DS Requestor Preference)

l 04 - Challenge requested (Mandate)

l 05 - No challenge requested (transactional risk analysis is

already performed)
l 06 - No challenge requested (Data share only)

l 07 - No challenge requested (strong consumer authentication is

already performed)
l 08 - No challenge requested (utilize trust list exemption if no
challenge required)
l 09 - Challenge requested (trust list prompt requested if
challenge required)

otpValue (Conditional) One time password; required when

authenticationMethodType in the authenticationMethod
structure is SMS_OTP or EMAIL_OTP.

Format: String; max. 16 characters

stepUpIdentifier (Conditional) Step-up identification; required when

authenticationMethodType in the authenticationMethod
structure is SMS_OTP, EMAIL_OTP, or APP_AUTHENTICATION.

2 May 2024 Visa Confidential 69

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Digital Card Facilitator (DCF)

Field Description
uri Uniform Resource Identifier (URI), a valid web address or URL
Format: String of characters; maximum 256 characters

logoUri Uniform Resource Identifier (URI) for your company logo.

Format: String of characters; maximum 256 characters
Example: http://test.com

name The name on the digital card.

Format: Alphanumeric; maximum 256 characters

Masked Address
The allowed characters for the address line 1, 2, and 3 are: .',:_#/
()ÁáÀàÂâÄäÃãÇçÉéÈèÊêËëÍíÎîÏïÑñÓóÔôÕõŒœÚúÙùÛûÜüŸÿÆæĄąĆćĘꣳŃńŚśŹźŻż/

Field Description
addressId The ID associated with the masked address in the SRC system.
Format: String

line1 Line 1 of the masked address in the SRC system. Required for
shipping address.
Format: Alphanumeric, Maximum 140 characters. For country
specific information, see Visa Checkout Address Formats by Country.
Example: 1** M*** St

line2 Line 2 of the masked address in the SRC system. Required for
shipping address.
Format: Alphanumeric, Maximum 140 characters.

line3 Line 3 of the masked address in the SRC system. Required for
shipping address.
Format: Alphanumeric, Maximum 140 characters.

city City name associated with the masked address in the SRC system.
The address must have the city name in the valid address format
for the country.
Format: Alphanumeric, UTF-8 white space; maximum 100
characters

2 May 2024 Visa Confidential 70

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Field Description
state State code associated with the masked address in the SRC system.
The address must have the state name in the valid address format
for the country.
Must be a valid 2-characters code for US and CA and a valid 3-
characters code for AU.

Format: String
Example: VA

zip The zip code associated with the masked address.

Format: Alphanumeric, maximum 3–16 characters.

countryCode Country code associated with the masked address in the SRC
system.
Format: ISO-3166-1 alpha-2 standard code
Example: US

createTime Date and time the masked address was created.

Format: String; 25 characters

lastUsedTime Date and time the masked address was last used.
Format: UNIX Epoch timestamp. The value is in milliseconds.

Masked Consumer

Field Description
firstName The first name of the consumer.
Format: Alphanumeric; between 2–80 characters.

lastName The last name of the consumer.

Format: Alphanumeric; between 2–80 characters.

fullName The full name of the consumer.

Format: Alphanumeric; between 2–80 characters.

emailAddress The email address of the consumer.

Note: This field supports internationalization using UTF-8

characters.
Format: A valid email address; maximum 32 bytes

maskedMobileNumber The mobile number of the consumer.

Note: Not returned by the getSrcProfile() method.

Format: MaskedPhoneNumber structure

2 May 2024 Visa Confidential 71

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Field Description
countryCode Country code associated with the masked address of consumer
country in the SRC system.
Format: ISO-3166-1 alpha-2 standard code

languageCode Consumer's locale.

Format: Locale, based on ISO format for language (ISO 639-1) and
alpha-2 country code (ISO 3166-1 alpha-2). The language and
country should be separated using a (_).

Example: en_US

Masked Phone Number

Field Description
countryCode Phone number country code.
Format: Alphabetic, numeric; maximum 4 characters.

phoneNumber Phone number of the consumer.

Format: A valid phone number; maximum 32 bytes.

2 May 2024 Visa Confidential 72

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Assurance Data

Field Description
cardVerificationResults Verification status of the PAN.
Deprecated Format: It is one of the following values:
01 - Verified

02 - Not Verified

03 - Not performed

04 - 20 - EMVCo future use

21 - 99 - SRC system­specific

cardholderAuthenticationResults SRC cardholder verification results, performed by the SRC system,

which indicates whether the cardholder was verified or not, and
Deprecated
whether the results have been verified.
Format: It is one of the following values:
01 - Verified

02 - Not Verified

03 - Not performed

04 - 20 - EMVCo future use

21 - 99 - SRC system­specific

consumerVerificationResults Whether the consumer was verified or not, and the results if the
consumer has been verified.
Deprecated
Format: It is one of the following values:
01 - Verified

02 - Not Verified

03 - Not performed

04 - 20 - EMVCo future use

21 - 99 - SRC system­specific

2 May 2024 Visa Confidential 73

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Field Description
verificationData Set of verification data structures relating to distinct types of
assurance.
Format: List of VerificationData structures.

eci If present, a value indicating the result of the authentication

performed or attempted during a transaction. Use this value in the
e-commerce authorization message to VisaNet.
Format: String; maximum 2 digits. It is one of the following values:

l 05 – Successful authentication

l 06 – Authentication attempted

l 07 – Authentication not performed

Verification Data

Field Description
verificationType Type of verification data.
Format: It is one of the following values:

l CARDHOLDER

verificationEntity Entity performing the verification.

Format: It is one of the following values:

l 01 - SRC Initiator

l 03 – SRCPI

verificationEvents Event causing the verification to occur.

Format: Array that can contain the following values:

l 01 – Payment transaction

l 02 – Add card/Card enrollment

l 03 – SRC Profile access

l 04 – Account verification

verificationMethod Method of verification.

Format: It is one of the following values:

l 02 – App-based authentication

l 04 – One-time passcode

l 21 – Visa Token Service step–up: Device binding

l 22 – Visa Token Service step–up: Cardholder verification

2 May 2024 Visa Confidential 74

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Field Description
verificationResults Result of the verification.
Format: It is one of the following values:
01 – Verified

02 – Not Verified

03 – Not performed

04 – Not required

21 – Not allowed

verificationTimestamp Date and time in UTC that the verification was conducted.
Format: UNIX Epoch timestamp.

methodResults Method results.

Format: JSON object

Method Results
Attributes related to the results of a given authentication method.

Field Description
transStatus Whether a transaction qualifies as an authenticated transaction
(for 3DS authentication).
Format: It is one of the following string values:

l "Y"

l "R"

l "C"

l "N"

l "U"

l "A"

l "D"

l "I"

dsTransId ID assigned by the DS to identify the transaction (for 3DS authenti­

cation).
Format: String; UUID

acsTransId ID assigned by the ACS to identify the transaction (for 3DS authenti­
cation).
Format: String; UUID

Note:

2 May 2024 Visa Confidential 75

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Refer to the EMVCo 3DS Specification for more details on the 3DS­specific attributes and
definitions.

Event History

Field Description
ageOfSrcPanEnrolmentSinceCreated The number of days the enrollment has existed in the SRC system.

Format: String

srcAgeSinceLastTransaction The number of days since the last transaction took place.
Format: String

ageOfSrcRelationship The number of days.

Format: String

ageOfConsumerRelationship The number of days, since the consumer profile was created in the
SRC system.
Format: string

billingAndShippingRelationship Describes the relationship between the cardholder billing and

shipping information.
Format: It is one of the following values:
01 — Same as cardholder’s billing address

02 — Consumer's preferred shipping address

03 — Consumer’s other address

shippingAddressUsageNew Date when the shipping address for this transaction was first used
with the SRCi.
Format: Alphanumeric, mm/dd/yyyy

ageOfShippingAddressUsage The number of days since the shipping address for this transaction
was first used.
Format: String

Checkout Examples

Code

async function checkout(input,cb)

const promiseData = await vSrc.checkout(input)

.then(function (data) {
return data;
})

2 May 2024 Visa Confidential 76

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

.catch(function (err) {
return err;
});
cb(promiseData);
}

function callCheckout() {
var checkoutInput = {}; // Check SDK Specs for input format
checkout(checkoutInput, function (result) {
console.log(result);
// Check response for payload or for any errors
});
}

Checkout input when existing card is selected:

{
"srciActionCode": "",
"srcCorrelationId": "376...01",
"srciTransactionId": "ns9...WJ",
"srcDigitalCardId": "e83...01",
"encryptedCard": "",
"idToken": "eyJ...eA",
"windowRef": "",
"dpaTransactionOptions": {
"dpaLocale": "en_US",
"dpaAcceptedBillingCountries": [
"US",
"CA"
],
"dpaAcceptedShippingCountries": [
"US",
"CA"
],
"dpaBillingPreference": "FULL",
"dpaShippingPreference": "FULL",
"consumerNameRequested": true,
"consumerEmailAddressRequested": true,
"consumerPhoneNumberRequested": true,
"paymentOptions": {
"dynamicDataType":
"CARD_APPLICATION_CRYPTOGRAM_LONG_FORM",
"dpaPanRequested": false
},
"reviewAction": "continue",
"checkoutDescription": "Sample checkout",
"transactionType": "PURCHASE",
"orderType": "REAUTHORIZATION",
"payloadTypeIndicator": "FULL",
"transactionAmount": {
"transactionAmount": "99.95",
"transactionCurrencyCode": "USD"
},
"merchantOrderId": "ABC12345",
"merchantCategoryCode": "...",
"merchantCountryCode": "US"

2 May 2024 Visa Confidential 77

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

}
}

Checkout input when existing card is selected – 3DS version:

{
"srciActionCode": "",
"srcCorrelationId": "376...01",
"srciTransactionId": "ns9...WJ",
"srcDigitalCardId": "e83...01",
"encryptedCard": "",
"idToken": "eyJ...eA",
"windowRef": "",
"dpaTransactionOptions": {
"dpaLocale": "en_US",
"dpaAcceptedBillingCountries": [
"US",
"CA"
],
"dpaAcceptedShippingCountries": [
"US",
"CA"
],
"dpaBillingPreference": "FULL",
"dpaShippingPreference": "FULL",
"consumerNameRequested": true,
"consumerEmailAddressRequested": true,
"consumerPhoneNumberRequested": true,
"paymentOptions": {
"dynamicDataType": "CARD_APPLICATION_CRYPTOGRAM_LONG_FORM",
"dpaPanRequested": false
},
"reviewAction": "continue",
"checkoutDescription": "Sample checkout",
"transactionType": "PURCHASE",
"orderType": "REAUTHORIZATION",
"payloadTypeIndicator": "FULL",
"transactionAmount": {
"transactionAmount": "99.95",
"transactionCurrencyCode": "USD"
},
"merchantOrderId": "ABC12345",
"merchantCategoryCode": "...",
"merchantCountryCode": "US"
},
"authenticationContext": {
"authenticationReasons": [
"TRANSACTION_AUTHENTICATION"
],
"srcDpaId": "94317cbf-b1a1-53b9-6228-11fbb1f07301",
"acquirerMerchantId": "12345678",
"acquirerBIN": "455555",
"merchantName": "NewM"
},
"authenticationMethod": {
"authenticationMethodType": "MANAGED_AUTHENTICATION",

2 May 2024 Visa Confidential 78

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

"authenticationSubject": "CARDHOLDER",
"methodAttributes": {
"challengeIndicator": "01"
}
}
}

Checkout input when new card is added:

{
"srcCorrelationId": "376...01",
"srciTransactionId": "416...16",
"srcDigitalCardId": "",
"encryptedCard": "eyJ...mQ",
"idToken": "",
"windowRef": "",
"dpaTransactionOptions": {
"dpaLocale": "en_US",
"dpaAcceptedBillingCountries": [
"US",
"CA"
],
"dpaAcceptedShippingCountries": [
"US",
"CA"
],
"dpaBillingPreference": "FULL",
"dpaShippingPreference": "FULL",
"consumerNameRequested": true,
"consumerEmailAddressRequested": true,
"consumerPhoneNumberRequested": true,
"paymentOptions": {
"dynamicDataType":
"CARD_APPLICATION_CRYPTOGRAM_LONG_FORM",
"dpaPanRequested": false
},
"reviewAction": "continue",
"checkoutDescription": "Sample checkout",
"transactionType": "PURCHASE",
"orderType": "REAUTHORIZATION",
"payloadTypeIndicator": "FULL",
"transactionAmount": {
"transactionAmount": "99.95",
"transactionCurrencyCode": "USD"
},
"merchantOrderId": "ABC12345",
"merchantCategoryCode": "...",
"merchantCountryCode": "US"
}
}

Checkout input when new card is added – 3DS version:

{
"srcCorrelationId": "376...01",

2 May 2024 Visa Confidential 79

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

"srciTransactionId": "416...16",
"srcDigitalCardId": "",
"encryptedCard": "eyJ...mQ",
"idToken": "",
"windowRef": "",
"dpaTransactionOptions": {
"dpaLocale": "en_US",
"dpaAcceptedBillingCountries": [
"US",
"CA"
],
"dpaAcceptedShippingCountries": [
"US",
"CA"
],
"dpaBillingPreference": "FULL",
"dpaShippingPreference": "FULL",
"consumerNameRequested": true,
"consumerEmailAddressRequested": true,
"consumerPhoneNumberRequested": true,
"paymentOptions": {
"dynamicDataType": "CARD_APPLICATION_CRYPTOGRAM_LONG_FORM",
"dpaPanRequested": false
},
"reviewAction": "continue",
"checkoutDescription": "Sample checkout",
"transactionType": "PURCHASE",
"orderType": "REAUTHORIZATION",
"payloadTypeIndicator": "FULL",
"transactionAmount": {
"transactionAmount": "99.95",
"transactionCurrencyCode": "USD"
},
"merchantOrderId": "ABC12345",
"merchantCategoryCode": "...",
"merchantCountryCode": "US"
},
"authenticationContext": {
"authenticationReasons": [
"TRANSACTION_AUTHENTICATION"
],
"srcDpaId": "943...01",
"acquirerMerchantId": "12345678",
"acquirerBIN": "455555",
"merchantName": "NewM"
},
"authenticationMethod": {
"authenticationMethodType": "MANAGED_AUTHENTICATION",
"authenticationSubject": "CARDHOLDER",
"methodAttributes": {
"challengeIndicator": "01"
}
}
}

2 May 2024 Visa Confidential 80

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Unencrypted Card Information in the Request

{
"card": {
"billingAddress": {
"addressId": "",
"name": "Firstname Lastname ",
"line1": "1 Streetname Street",
"line2": "",
"line3": "",
"city": "Miami",
"state": "FL",
"countryCode": "US",
"zip": "33126",
"createTime": "",
"lastUsedTime": ""
},
"cardSecurityCode": "099",
"cardholderFullName": "Firstname Lastname ",
"panExpirationMonth": 10,
"panExpirationYear": 2025,
"primaryAccountNumber": "...",
"cardholderFirstName": "Firstname",
"cardholderLastName": "Lastname",
"paymentAccountReference": ""
}
}

Consumer Information in the Request

{
"consumer": {
"emailAddress": "[email protected]",
"consumerIdentity": {
"identityProvider": "SRC",
"identityType": "EMAIL_ADDRESS",
"identityValue": "[email protected]"
},
"mobileNumber": {
"phoneNumber": "...",
"countryCode": "1"
},
"countryCode": "US",
"languageCode": "EN",
"firstName": "Psp",
"lastName": "Tester",
"fullName": "Psp Tester"
}
}

Compliance Settings in the Request

{
"srcCorrelationId": "",

2 May 2024 Visa Confidential 81

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

"srciTransactionId": "c3a...9c",
"srcDigitalCardId": "",
"encryptedCard": "eyJ...Gw",
"idToken": "",
"windowRef": "",
"consumer": {
"emailAddress": "foi...r.com",
"consumerIdentity": {
"identityProvider": "SRC",
"identityType": "EMAIL_ADDRESS",
"identityValue": "foi...r.com"
},
"mobileNumber": {
"phoneNumber": "408...22",
"countryCode": "1"
},
"nationalIdentifier": "USA",
"countryCode": "US",
"languageCode": "EN",
"firstName": "PSP",
"lastName": "Tester",
"fullName": "Test"
},
"dpaTransactionOptions": {
"dpaLocale": "US",
"dpaAcceptedBillingCountries": [
"US",
"CA"
],
"dpaAcceptedShippingCountries": [
"US",
"CA"
],
"dpaBillingPreference": "FULL",
"dpaShippingPreference": "FULL",
"consumerNameRequested": true,
"consumerEmailAddressRequested": true,
"consumerPhoneNumberRequested": true,
"paymentOptions": {
"dpaDynamicDataTtlMinutes": 2,
"dynamicDataType":
"CARD_APPLICATION_CRYPTOGRAM_LONG_FORM",
"dpaPanRequested": false
},
"reviewAction": "continue",
"checkoutDescription": "Sample checkout",
"transactionType": "PURCHASE",
"orderType": "REAUTHORIZATION",
"payloadTypeIndicator": "SUMMARY",
"transactionAmount": {
"transactionAmount": "99.95",
"transactionCurrencyCode": "USD"
},
"merchantOrderId": "ABC12345",
"merchantCategoryCode": "merchantCategoryCode",
"merchantCountryCode": "US"
},
"payloadTypeIndicatorCheckout": "SUMMARY",

2 May 2024 Visa Confidential 82

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

"recipientIdCheckout": "",
"payloadTypeIndicatorPayload": "SUMMARY",
"recipientIdPayload": "",
"assuranceData": {
"verificationData": [
{
"verificationType": "CARDHOLDER",
"verificationEntity": "01",
"verificationMethod": "01",
"verificationResults": "01",
"verificationTimestamp": "1646416550"
}
]
},
"srciActionCode": "NEW_USER",
"complianceSettings": {
"complianceResources": [
{
"complianceType": "TERMS_AND_CONDITIONS",
"uri": "usa.visa.com/legal/checkout/terms-of-service.html"
},
{
"complianceType": "PRIVACY_POLICY",
"uri": "usa.visa.com/legal/global-privacy-notice.html"
},
{
"complianceType": "REMEMBER_ME",
"uri": "visa.checkout.com/privacy"
}
]
}
}

Full Checkout Returns

{
"checkoutResponse": "eyJ...Q=",
"dcfActionCode": "COMPLETE",
"unbindAppInstance": false
}

Summary Checkout Returns

{
"checkoutResponse": "eyJ..DQ",
{
"isnewuser": true,
"src_system_name": "VISA",
"cardBrand": "VISA"
},
"dcfActionCode": "COMPLETE"
}

2 May 2024 Visa Confidential 83

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Decrypted Full Checkout Response

The full checkout response includes the encrypted payload string, which provides the
consumer’s information listed in the Payload chapter when the string is decrypted:

{
"srcCorrelationId": "023...02",
"srciTransactionId": "hIZ...u7",
"maskedCard": {
"srcDigitalCardId": "efb...02",
"panBin": "430753",
"panLastFour": "0008",
"panExpirationMonth": "12",
"panExpirationYear": "2023",
"digitalCardData": {
"status": "ACTIVE",
"presentationName": "... ...",
"descriptorName": "... ..."
},
"dateofCardCreated": 1583133529903,
"dateofCardLastUsed": 1585274333914,
"maskedBillingAddress": {
"addressId": "e43...02",
"countryCode": "US"
},
"eligible": true
},
"shippingAddressZip": "94404",
"shippingCountryCode": "US",
"maskedConsumer": {
"srcConsumerId": "H5p...A=",
"firstName": "...",
"lastName": "...",
"fullName": "... ...",
"emailAddress": "xyz**@visa.com",
"mobileNumber": {},
"countryCode": "US",
"languageCode": "en-US",
"status": "ACTIVE"
},
"encryptedPayload": "eyJ...nA",
"assuranceData": {
"cardVerificationResults": "01"
},
"isGuestCheckout": false,
"isNewUser": false
}

Decrypted Summary Checkout Response

The summary checkout response does not include the encrypted payload string.

{
"srcCorrelationId": "ed6...01",
"srciTransactionId": "5cc...8e",
"maskedCard": {

2 May 2024 Visa Confidential 84

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

"srcDigitalCardId": "857...01",
"panBin": "400552",
"panLastFour": "3375",
"panExpirationMonth": "12",
"panExpirationYear": "2023",
"digitalCardData": {
"status": "ACTIVE",
"presentationName": "New Last",
"artUri": "https://sandbox.secure.checkout.visa.com
/VmeCardArts/....png",
"artHeight": 105,
"artWidth": 164
},
"pendingEvents": [
"PENDING_CARDHOLDER_AUTHENTICATION",
"PENDING_CONSUMER_IDV",
"PENDING_CONSUMER_DEVICE_BINDING"
],
"dateofCardCreated": 1564445093245,
"dateofCardLastUsed": 1565813106869,
"maskedBillingAddress": {
"addressId": "5c4...01",
"line1": "901*****",
"city": "*****",
"state": "CA",
"zip": "*****",
"countryCode": "US"
},
"eligible": true
},
"shippingAddressZip": "94404",
"shippingCountryCode": "US",
"maskedConsumer": {
"srcConsumerId": "H5p...uA=",
"firstName": "F*****",
"lastName": "L*****",
"fullName": "F***** L*****",
"emailAddress": "din**@visa.com",
"mobileNumber": {},
"countryCode": "US",
"languageCode": "en-US",
"status": "ACTIVE"
},
"assuranceData": {
"cardVerificationResults": "01"
},
"isGuestCheckout": false,
"isNewUser": false
}

Assurance Data for 3DS in the Decrypted Checkout Response:

3DS provides additional fields in the response.

"assuranceData": {
"verificationData": [

2 May 2024 Visa Confidential 85

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

{
"methodResults": {
"transStatus": "Y",
"dsTransId": "06c...16",
"acsTransId": "6f5...09"
}
}
],
"eci": "05"
}

Checkout Errors

Reason Code Description

CARD_ADD_FAILED Unable to add card.

CARD_SECURITY_CODE_MISSING Card security must be supplied.

CARD_INVALID Invalid card number.

CARD_EXP_INVALID Invalid card expiration date.

CARDID_MISSING The card ID was required but is missing.

CARD_NOT_RECOGNIZED The specified card was not recognized.

ACCT_INACCESSIBLE The account exists but is not currently accessible,

e.g., is locked.

MERCHANT_DATA_INVALID Merchant data is invalid.

UNABLE_TO_CONNECT Unable to connect to or launch card experience.

AUTH_INVALID Invalid federated ID token.

TERMS_AND_CONDITIONS_NOT_ACCEPTED Terms and conditions not accepted.

IDENTITY_VALIDATION_REQUIRED Consumer identity validation is required.

Also, see Standard Error Codes.

Authenticate (authenticate)
Syntax

authenticate()

2 May 2024 Visa Confidential 86

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Authenticate Parameters

Field Description
srcClientId (Optional) Reference identifier.
Format: Universally Unique Identifier (UUID)

serviceId (Optional) Service identifier associated to an SRC system­specific

configuration.
Format: Universally Unique Identifier (UUID)

srcCorrelationId (Optional) Correlation ID generated by the SRC system and

returned by getSrcProfile.

Format: Universally Unique Identifier (UUID)

srciTransactionId (Required) A unique ID created by the SRCi

Format: Alphanumeric, maximum 100 characters

authenticationSessionId (Conditional) Authentication session ID. Required if available from a

previously initiated authentication event.
Format: String
accountReference (Conditional) Account reference. Required if
authenticationSessionId is not available.

Format: An AccountReference structure.

authenticationContext (Conditional) Transaction context data that SRC System uses to

perform authentication. Required if authenticationSessionId
is not available.
Format: AuthenticationContext structure.

authenticationMethod (Required) Authentication method indicated by the SRCi to the SRC

System.
Format: AuthenticationMethod structure.

2 May 2024 Visa Confidential 87

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Account Reference

Field Description
srcDigitalCardId (Conditional) ID of the selected card.
Required if consumerIdentity is not present.

Format: String

consumerIdentity (Conditional) Primary verifiable consumer identifier within an SRC

Profile; for example, an email address.
Required if srcDigitalCardId is not present.

Note: Mobile phone numbers are not supported.

Format: A consumerIdentity structure

Consumer Identity

Field Description
identityProvider (Optional) The Identity provider.
The default value is SRC

Format: String

identityValue (Required) Value of the consumer identity, which is used to locate

information within the SRC profile.

Note: Only an email address is supported.

Format: String
Example: [email protected]

identityType (Required) The type of the consumer identity.

It is one of the following values:

l EMAIL_ADDRESS

Format: String

2 May 2024 Visa Confidential 88

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Authentication Context

Field Description
authenticationReasons (Required) SRCi-provided authentication reasons used by the SRC
System to perform authentication.
Format: They are one or more of the following enumerated values:

l TRANSACTION_AUTHENTICATION

l NOT_PREFERRED

srciDpaId (Conditional) DPA identifier, which is generated by the SRC system

during DPA registration. Either srciDpaId or a dpaData structure
must be provided when authenticationReasons is
TRANSACTION_AUTHENTICATION.

Format: String, 64 bytes

dpaData (Conditional) DPA registration data.

Format: A DpaData structure.

dpaTransactionOptions (Optional) DPA configuration data, which overrides the configu­

ration on the SRC system that was created during DPA registration.
Ignored if supplied in the init call or elsewhere in the checkout
call.
Format: DpaTransactionOptions structure

acquirerMerchantId (Required) Acquirer-assigned Merchant identifier. Value must be

provided to perform transaction authentication by the SRC System.
Format: String

acquirerBIN (Required) Acquirer identification code as assigned by the Directory

Server. Value must be provided to perform transaction authenti­
cation by the SRC System.
Format: String

merchantName (Required) Merchant name assigned by the Acquirer or Payment

System. Value must be provided to perform transaction authenti­
cation by the SRC System.
Format: String

2 May 2024 Visa Confidential 89

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Authentication Method

Field Description
authenticationMethodType (Required) SRCi to indicate for a particular transaction if Click to Pay
needs to perform managed authentication or not.
Format: It is one of the following values:

l SMS_OTP

l EMAIL_OTP

l APP_AUTHENTICATION

l MANAGED_AUTHENTICATION

authenticationSubject (Optional) Authentication subject. This should be set to

CARDHOLDER.

Format: It is one of the following values:

l CARDHOLDER

l CONSUMER

l CARD

uriData (Optional) URI associated with the authentication method, if

available.
Format: A UriData structure

authenticationCredentialReference (Optional) Authentication credential reference, which may be

provided by the identity provider once an authentication is initiated
to qualify the nature of the authentication method. For example,
SMS_OTP may use the masked mobile number "***-***-1234",
which can be displayed to the Consumer to aid method selection.
Format: String

methodAttributes (Optional) Attributes related to the authentication method; see

"Method Attributes."
Format: JSON object

2 May 2024 Visa Confidential 90

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

URI Data

Field Description
uri (Required) Specifies the URI for the given authentication method.
Format: String; maximum 2048 characters

uriType (Required) URI type.

Format: It is one of the following values:

l APP_URI

l WEB_URI

Method Attributes

Field Description
challengeIndicator (Optional) A challenge indicator value related to 3DS authentication.
Format: It is one of the following values:

l 01 - No preference

l 02 - No challenge requested

l 03 - Challenge requested (3DS Requestor Preference)

l 04 - Challenge requested (Mandate)

l 05 - No challenge requested (transactional risk analysis is

already performed)
l 06 - No challenge requested (Data share only)

l 07 - No challenge requested (strong consumer authentication is

already performed)
l 08 - No challenge requested (utilize trust list exemption if no
challenge required)
l 09 - Challenge requested (trust list prompt requested if
challenge required)

otpValue (Conditional) One time password; required when

authenticationMethodType in the authenticationMethod
structure is SMS_OTP or EMAIL_OTP.

Format: String; max. 16 characters

stepUpIdentifier (Conditional) Step-up identification; required when

authenticationMethodType in the authenticationMethod
structure is SMS_OTP, EMAIL_OTP, or APP_AUTHENTICATION.

2 May 2024 Visa Confidential 91

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Authenticate Returns

Authenticate Response

Field Description
srcCorrelationId The SRC Correlation ID returned by the SRC system
Format: Universally Unique Identifier (UUID)

srciTransactionId A unique ID created by the SRCi

Format: Alphanumeric, maximum 100 characters

authenticationResult Authentication status.

Format: It is one of the following values:

l AUTHENTICATED

l NOT_AUTHENTICATED

authenticationStatus Authentication status.

Format: It is one of the following values:

l COMPLETE

l PENDING

l PENDING_CHALLENGE

l CANCELLED

l EXPIRED

l NOT_SUPPORTED

assuranceData Information about any risk assessment operations performed by

the SRC system.
Format: AssuranceData structure

methodResults Method results.

Format: JSON object

2 May 2024 Visa Confidential 92

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Assurance Data

Field Description
cardVerificationResults Verification status of the PAN.
Deprecated Format: It is one of the following values:
01 - Verified

02 - Not Verified

03 - Not performed

04 - 20 - EMVCo future use

21 - 99 - SRC system­specific

cardholderAuthenticationResults SRC cardholder verification results, performed by the SRC system,

which indicates whether the cardholder was verified or not, and
Deprecated
whether the results have been verified.
Format: It is one of the following values:
01 - Verified

02 - Not Verified

03 - Not performed

04 - 20 - EMVCo future use

21 - 99 - SRC system­specific

consumerVerificationResults Whether the consumer was verified or not, and the results if the
consumer has been verified.
Deprecated
Format: It is one of the following values:
01 - Verified

02 - Not Verified

03 - Not performed

04 - 20 - EMVCo future use

21 - 99 - SRC system­specific

2 May 2024 Visa Confidential 93

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Field Description
verificationData Set of verification data structures relating to distinct types of
assurance.
Format: List of VerificationData structures.

eci If present, a value indicating the result of the authentication

performed or attempted during a transaction. Use this value in the
e-commerce authorization message to VisaNet.
Format: String; maximum 2 digits. It is one of the following values:

l 05 – Successful authentication

l 06 – Authentication attempted

l 07 – Authentication not performed

Verification Data

Field Description
verificationType Type of verification data.
Format: It is one of the following values:

l CARDHOLDER

verificationEntity Entity performing the verification.

Format: It is one of the following values:

l 01 - SRC Initiator

l 03 – SRCPI

verificationEvents Event causing the verification to occur.

Format: Array that can contain the following values:

l 01 – Payment transaction

l 02 – Add card/Card enrollment

l 03 – SRC Profile access

l 04 – Account verification

verificationMethod Method of verification.

Format: It is one of the following values:

l 02 – App-based authentication

l 04 – One-time passcode

l 21 – Visa Token Service step–up: Device binding

l 22 – Visa Token Service step–up: Cardholder verification

2 May 2024 Visa Confidential 94

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Field Description
verificationResults Result of the verification.
Format: It is one of the following values:
01 – Verified

02 – Not Verified

03 – Not performed

04 – Not required

21 – Not allowed

verificationTimestamp Date and time in UTC that the verification was conducted.
Format: UNIX Epoch timestamp.

methodResults Method results.

Format: JSON object

Method Results
Attributes related to the results of a given authentication method.

Field Description
transStatus Whether a transaction qualifies as an authenticated transaction
(for 3DS authentication).
Format: It is one of the following string values:

l "Y"

l "R"

l "C"

l "N"

l "U"

l "A"

l "D"

l "I"

dsTransId ID assigned by the DS to identify the transaction (for 3DS authenti­

cation).
Format: String; UUID

acsTransId ID assigned by the ACS to identify the transaction (for 3DS authenti­
cation).
Format: String; UUID

Note:

2 May 2024 Visa Confidential 95

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Refer to the EMVCo 3DS Specification for more details on the 3DS­specific attributes and
definitions.

Authenticate Example

Request Payload

{
"srciTransactionId": "c21...9e",
"srcCorrelationId": "de2...01",
"authenticationMethod": {
"authenticationMethodType": "EMAIL_OTP",
"authenticationSubject": "CARDHOLDER",
"methodAttributes": {
"otpValue": "553401",
"stepUpIdentifier": "MGE...="
}
}
}

Response Payload

{
"srcCorrelationId": "de2...01",
"srciTransactionId": "c21...9e",
"authenticationResult": "AUTHENTICATED",
"authenticationStatus": "COMPLETE",
"assuranceData": {
"verificationData": [
{
"verificationType": "CARDHOLDER",
"verificationEntity": "03",
"verificationEvents": [
"01"
],
"verificationMethod": "04",
"verificationResults": "01",
"verificationTimestamp": "1692781875"
}
]
}

2 May 2024 Visa Confidential 96

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Authenticate Errors
Reason Code Description
ACCT_REF_FORMAT_UNSUPPORTED Unsupported accountReference
ACCT_REF_MISSING The accountReference parameter is missing
AUTHENTICATION_METHOD_ The supplied authentication method doesn’t match the authenti­
NOT_SUPPORTED cation context
OTP_SEND_FAILED The OTP could not be sent to the recipient
RETRIES_EXCEEDED The limit for the number of retries exceeded
VAL_DATA_MISSING The validationData parameter is missing
VAL_DATA_EXPIRED The validationData is expired
VAL_DATA_INVALID The supplied validationData is invalid
AUTHENTICATE_FAILURE Default error case for all other reasons of authenticate failure.

Unbind App Instance

(unbindAppInstance)
Disassociates the Consumer application or Device from the Consumer’s SRC Profile.

Syntax

unbindAppInstance(idToken)

Unbind App Instance Parameters

Field Description
idToken The token ID returned by the checkout method that indicates
which SRC Profile and SRC System the app instance should be
unbound from. If not provided, the app instance will be unbound
from the Visa SRC System.
Format: ID Token in JWT format

2 May 2024 Visa Confidential 97

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Unbind App Instance Returns

Field Description
srcCorrelationId The SRC Correlation ID returned by the SRC system
Format: Universally Unique Identifier (UUID)

Unbind App Instance Example

Code

async function unbindAppInstance(input, cb) {

let promiseData = await vco.unbindAppInstance(input)
.then(function(data) {
return data;
})
.catch(function(err) {
return err;
});
cb(promiseData);
}

function callUnbind(idToken) {
unbindAppInstance(idToken, function(result) {
console.log(result);
if (!result.error) {
// Prompt user that the device has been disassociated
} else {
// Prompt error
}
});
}

Input

{
"idToken": "eyJ...eA"
}

Returns

{
"srcCorrelationId": "1b3...01"
}

2 May 2024 Visa Confidential 98

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Unbind App Instance Errors

Reason Code Description
AUTH_INVALID Invalid federated ID token.

ACCT_INACCESSIBLE The account exists but is not currently accessible, e.g. it is locked.

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:

2 May 2024 Visa Confidential 99

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

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.

2 May 2024 Visa Confidential 100

 Visa Secure Remote Commerce – Software Developer Kit
JavaScript API

Reason Description
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:

l Base64 decoding failed

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

l Decrease the rate of sending API requests; wait before sending

the next request.
l 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).

2 May 2024 Visa Confidential 101

Chapter 3
Unencrypted Payload Contents

2 May 2024 Visa Confidential 102

 Visa Secure Remote Commerce – Software Developer Kit
Unencrypted Payload Contents

Payload
Payload provides metadata that includes the information based on if the consumer uses the
PAN, or token.

Field Description
card Card data associated with the PAN used for the purchase. Supplied
if the indicated payload type is FULL or PAYMENT and the SRC
system determines that a PAN-based payload is returned.

Note: Either a Card or a Payment Token credential is

returned, never both
Format: Card structure

token Payment Token data associated with the PAN used for the
purchase. Supplied if the indicated payload type is FULL or
PAYMENT and the SRC system determines that a Payment Token-
based payload is returned.

Note: Either a Card or a Payment Token credential is

returned, never both
Format: PaymentToken structure

paymentAccountReference The Payment Account Reference (PAR) associated with the

cardholder account that uniquely identifies the account to which
the payment card is associated.
Format: String

dynamicData Dynamic data (cryptograms) applicable for transactions. If Click to

Pay facilitates Issuer Authentication (3DS), then CAVV will be
provided in the dynamic data.
Format: List of DynamicData structures

billingAddress Billing address of the selected card.

Format: Address structure

shippingAddress Shipping address of the consumer; supplied when available, for

example:

l Identified Shipping Address is available in the SRC Profile

l Shipping address is requested (based on dpaShippingPre­
ference)
l PayloadTypeIndicator is “FULL” or “NON_PAYMENT”
Format: Address structure

consumer Consumer's information.

Format: Consumer structure

2 May 2024 Visa Confidential 103

 Visa Secure Remote Commerce – Software Developer Kit
Unencrypted Payload Contents

Field Description
panExpirationYear The year when the account number is set to expire.
Format: Numeric; 4 digits

threeDsOutputData (Deprecated) Result of 3DS payment authentication.

Card

Field Description
primaryAccountNumber The account number of the card to be enrolled and provisioned.
Format: Numeric

panExpirationMonth The account number expiration month.

Format: Numeric, 2 digits, MM

panExpirationYear The account number expiration year.

Format: Numeric, 4 digits, YYYY

cardSecurityCode The card security code (CVV2) value associated with the account
number on the card, if available.
Format: Numeric, 3-4 digits

cardholderFullName The full name of the cardholder on the Visa card.

Format: String
cardholderFirstName The first name of the cardholder.
Format: String
cardholderLastName The last name of the cardholder.
Format: String

billingAddress Billing address.

Format: An address structure.

paymentAccountReference The Payment Account Reference (PAR) associated with the

cardholder account that uniquely identifies the account to which
the payment card is associated. Present in the response of
checkout or payload.

Format: String

2 May 2024 Visa Confidential 104

 Visa Secure Remote Commerce – Software Developer Kit
Unencrypted Payload Contents

Payment Token

Field Description
paymentToken The tokenized payment instrument.
Format: String; ISO/IEC 7812 format

tokenExpirationMonth Tokenized payment instrument expiration month.

Format: Numeric, 2 digits; MM

tokenExpirationYear Tokenized payment instrument expiration year.

Format: Numeric, 4 digits; YYYY

paymentAccountReference A non­financial reference assigned to each unique PAN and used to

link a Payment Account represented by that PAN to affiliated
Payment Tokens.
Format: Alphanumeric, maximum 29 characters

Address

Field Description
addressId The address identifier in the SRC system.
Format: Universally Unique Identifier (UUID)

name The recipient name for the address, if known.

Format: Alphanumeric; maximum 60 characters.

line1 Line 1 of the address. Required for shipping address.

Format: Alphanumeric; maximum 75 characters

line2 Line 2 of the address.

Format: Alphanumeric; maximum 75 characters

line3 Line 3 of the address.

Format: Alphanumeric; maximum 75 characters

city The city associated with the address. A shipping address must have
the city name in the valid address format for the country.
Format: Alphanumeric; maximum 500 characters.

state The state associated with the address. A shipping address must
have the state name in the valid address format for the country.
Format: String; maximum 30 characters

2 May 2024 Visa Confidential 105

 Visa Secure Remote Commerce – Software Developer Kit
Unencrypted Payload Contents

Field Description
zip The zip code associated with the address.
Required for all those countries that have zip or zip code and if this
is a shipping address.
Other postal codes must be valid for their respective countries, if a
code exists.
Format: Alphanumeric; 3–16 characters.

countryCode The country code associated with the address.

Format: ISO-3166-1 alpha-2 standard code
Example: AU - Australia

createTime Date and time, in controlled Universal Time, (UTC) that identifies
when the address was created.
Format: UNIX Epoch timestamp. The value is in milliseconds

lastUsedTime Date and time , in Controlled Universal Time, (UTC) that identifies
when the address was last used.
Format: UNIX Epoch timestamp. The value is in milliseconds

Phone Number

Field Description
countryCode The country code associated with the consumer phone number.
Format: String
Example: 380 for Ukraine

phoneNumber Phone number without country code.

Format: String; numeric, 4 to 14 digits.

2 May 2024 Visa Confidential 106

 Visa Secure Remote Commerce – Software Developer Kit
Unencrypted Payload Contents

Dynamic Data

Field Description
dynamicDataValue The value of the dynamic data. Must be provided when
dynamicDataType is not NONE.

Format: String

dynamicDataType Type of dynamic data required in the payload.

Format: It is one of the following values:

l CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM

l CARD_APPLICATION_CRYPTOGRAM_LONG_FORM

l DYNAMIC_CARD_SECURITY_CODE

l CARDHOLDER_AUTHENTICATION_CRYPTOGRAM

l NONE

dynamicDataExpiration The requested validity period for the dynamic data in Coordinated
Universal Time (UTC).
Format: String, 25 characters
Example: Wed Jan 15 23:40:23 GMT 2020

Consumer

Field Description
firstName Consumer’s first name.
Format: String; maximum 30 characters

lastName Consumer’s last name.

Format: Alphanumeric; between 2–80 characters

fullName Consumer’s full name.

Format: Alphanumeric; between 2–80 characters

emailAddress Consumer's email address if mobile phone is not available.

Format: A valid email address; maximum 255 characters

mobileNumber Consumer's phone number if email is not available.

Format: PhoneNumber structure

2 May 2024 Visa Confidential 107

 Visa Secure Remote Commerce – Software Developer Kit
Unencrypted Payload Contents

Field Description
countryCode The country code associated with the address.
Format: ISO-3166-1 alpha-2 standard code
Example: AU - Australia

languageCode Consumer's locale.

Format: Locale, based on ISO format for language (ISO 639-1) and
alpha-2 country code (ISO 3166-1 alpha-2). The language and
country should be separated using a (_).
Example: en_US

consumerIdentity Primary verifiable consumer identifier within an SRC Profile; for

example, an email address.

Note: Mobile phone numbers are not supported.

Format: A consumerIdentity structure

nationalIdentifier Geographic­specific, nationally-provided identifier for the

Consumer.
Format: String; max. 20 characters

Phone Number

Field Description
countryCode The country code associated with the consumer phone number.
Format: String
Example: 380 for Ukraine

phoneNumber Phone number without country code.

Format: String; numeric, 4 to 14 digits.

2 May 2024 Visa Confidential 108

 Visa Secure Remote Commerce – Software Developer Kit
Unencrypted Payload Contents

Consumer Identity

Field Description
identityProvider The identity provider.
The default value is SRC

Format: String

identityValue Value of the consumer identity, which is used to locate information

within the SRC profile.

Note: Only email address is supported

Format: String; valid email address
Example: [email protected]

type The type of the consumer identity.

It is one of the following values:

l EMAIL_ADDRESS

Format: String

Decrypted PAN Payload Example

{
"card": {
"primaryAccountNumber": "430...08",
"panExpirationMonth": "12",
"panExpirationYear": "2023",
"cardholderFullName": "... ...",
"cardholderFirstName": "...",
"cardholderLastName": "..."
},
"billingAddress": {
"addressId": "e43...02",
"countryCode": "US"
},
"shippingAddress": {
"addressId": "5c4...01",
"line1": "...",
"city": "...",
"state": "...",
"zip": "...",
"countryCode": "US"
},
"consumer": {
"firstName": "...",
"lastName": "...",
"fullName": "... ...",

2 May 2024 Visa Confidential 109

 Visa Secure Remote Commerce – Software Developer Kit
Unencrypted Payload Contents

"emailAddress": "[email protected]",
"mobileNumber": {},
"countryCode": "US",
"languageCode": "en-US"
},
"threeDsOutputData": []
}

Decrypted Token Payload Example

{
"token": {
"paymentToken": "489...69",
"tokenExpirationMonth": "12",
"tokenExpirationYear": "2024"
},
"paymentAccountReference": "V00...23",
"dynamicData": [
{
"dynamicData": "AgA...A=",
"dynamicDataType": "CARD_APPLICATION_CRYPTOGRAM_LONG_FORM",
"dynamicDataExpiration": "Thu Jun 25 03:23:13 GMT 2020"
},
{
"dynamicDataValue": "Y2F...g=",
"dynamicDataType": "CARDHOLDER_AUTHENTICATION_CRYPTOGRAM"
}
],
"billingAddress": {
"addressId": "b3f...02",
"countryCode": "GB"
},
"shippingAddress": {
"addressId": "89e...01",
"line1": "...",
"city": "...",
"state": "ON",
"zip": "K1G 4B5",
"countryCode": "CA"
},
"consumer": {
"firstName": "...",
"lastName": "...",
"fullName": "... ...",
"emailAddress": "[email protected]",
"mobileNumber": {},
"countryCode": "US",
"languageCode": "en-US"
},
"threeDsOutputData": []
}

2 May 2024 Visa Confidential 110

 Visa Secure Remote Commerce – Software Developer Kit
Unencrypted Payload Contents

Decrypted 3DS Assurance Data

3DS provides additional fields in the response.

"assuranceData": {
"verificationData": [
{
"methodResults": {
"transStatus": "Y",
"dsTransId": "06c...16",
"acsTransId": "6f5...09"
}
}
],
"eci": "05"
}

2 May 2024 Visa Confidential 111

Chapter 4
Get Payload

Get Payload Summary

Enables the SRC Initiator to retrieve payload data from the SRC system. Call this API before
submitting a transaction authorization.

Get Payload Request

Path and Endpoints

Resource Path

wallet/src/transaction/credentials

2 May 2024 Visa Confidential 112

 Visa Secure Remote Commerce – Software Developer Kit
Get Payload

Sandbox

https://sandbox.api.visa.com/wallet/src/transaction/credentials?
apikey=key&payloadTypeIndicator=type&srcClientId=clientId
&srcCorrelationId=correlationId&srcDpaId=DPAID

Live

https://api.visa.com/wallet/src/transaction/credentials?
apikey=key&payloadTypeIndicator=type&srcClientId=clientId
&srcCorrelationId=correlationId&srcDpaId=DPAID

Method
GET

2 May 2024 Visa Confidential 113

 Visa Secure Remote Commerce – Software Developer Kit
Get Payload

Required Headers
Header Description
x-pay-token A token identifying the transaction and its contents.
Format: Alphanumeric; maximum 100 characters in the form of
xv2:UTC_Timestamp:HMAC-SHA256_hash, where

l UTC_Timestamp is a UNIX Epoch timestamp

l HMAC-SHA256_hash is an HMAC-SHA256 hash using the shared
secret associated with your API key and the following
unseparated items:

1. Timestamp from the transaction; exactly the same as

UNIX_UTC_Timestamp
2. Resource path (API name)
3. This HTTPS request's query string, if it exists

Note: To create the query string, concatenate

all query string components (names and
values) as UTF-8 characters, which are URL-
encoded per RFC 3986. Hex characters must be
uppercase. Multiple parameters must be
sorted using lexicographic byte ordering and
separated from each other by an ampersand
(&) character (ASCII code 38). Parameter names
are separated from their values by the =
character (ASCII character 61), which must be
present even if the value is empty.
“Unreserved" characters specified in Section
2.3 of RFC 3986 , including dash -, dot .,
underscore _, and tilde ~ should not be URL-
encoded.
4. Complete request body, when a request body exists
Example: x-pay-token: xv2:1440199445:HMAC-
SHA256_hash result

Accept Acceptable response format.

Format: Must include the following value:
application/json

Example: Accept: application/json

Content-Type Format of the content.

Format: Must include the following value:
application/json

Example: Content-Type: application/json

2 May 2024 Visa Confidential 114

 Visa Secure Remote Commerce – Software Developer Kit
Get Payload

Query Parameters

Field Description
apikey (Required) Inbound Authentication Key used for generating X-Pay-
Token
Format: Alphanumeric; maximum 64 characters

payloadTypeIndicator (Optional) Identifies the type of encrypted payload to be returned..

Format: It is one of the following values:

l FULL — Includes everything; all PCI & PII data (card/token,

billing, shipping, consumer)
l PAYMENT — Same as FULL

l NON_PAYMENT — Include only PII data (billing, shipping,

consumer)
l NONE — Returns empty payload.

srcClientId (Required) The value of the API key that identifies the connecting
client, e.g. SRCi, DCF, or SRC Issuer (SRCPI)
Format: Alphanumeric; maximum 64 characters

srcCorrelationId (Conditional) This is the unique identifier generated by the SRC

system to track and link SRC messages. This is used as the
transaction identifier assigned by the SRC system for this particular
transaction.
If a previous srcCorrelationId is not available from an earlier
response, a new correlation ID is provided to indicate a new
transaction
Format: Universally Unique Identifier (UUID)

srcDpaId (Conditional) DPA identifier, which is generated by the.SRC system

during DPA registration. Required if calling client is not an SRC
issuer (SRCPI).
Format: String; 64 bytes

receipientId (Optional) Identifies the recipient of the encrypted payload known

to the SRC system.
The SRC system decides about the key used for encryption of the
payload for the recipient.
Format: String

srciTransactionId (Optional) 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.
Format: Alphanumeric, maximum 100 characters

serviceId Future

2 May 2024 Visa Confidential 115

 Visa Secure Remote Commerce – Software Developer Kit
Get Payload

Request Body
None

Get Payload Response

Response Body

Field Description
maskedCard Masked card information.
Format: MaskedCard structure.

shippingAddressZip ZIP code of the shipping address being shipped to. The
shippingAddressZip will be present depending on the
dpaShippingPreference option in the
dpaTransactionOptions structure and either a
shippingAddressId or shippingAddress object was present in
the Checkout request data.
Format: String

shippingCountryCode Country code associated with the shipping address. The

shippingCountryCode parameter will be present depending on
the dpaShippingPreference option in the
dpaTransactionOptions structure and either a
shippingAddressId or shippingAddress object was present in
the Checkout request data.
Example: AU - Australia

Format: ISO-3166-1 alpha-2 standard code

maskedConsumer Masked information about the consumer for display purposes.

Format: MaskedConsumer structure.

encryptedPayload Encrypted payload to be given to the merchant. For details see

Chapter 3, Payload.
Format: String

assuranceData Information about any risk assessment operations performed by

the SRC system.
Format: AssuranceData structure.

2 May 2024 Visa Confidential 116

 Visa Secure Remote Commerce – Software Developer Kit
Get Payload

Masked Card

Field Description
srcDigitalCardId A unique ID associated with the digital card. Represent the PAN or
payment token.
Format: Universally Unique Identifier (UUID), maximum 36
characters

panBin The bank ID number associated with the card, the first significant
digits of the PAN included in an unmasked form.
Format: Numeric maximum length = PAN length - 10

tokenBinRange Token's BIN range or subset of the BIN range that has been
designated only for the purpose of issuing payment tokens
included in an unmasked form.
Format: Numeric; maximum length = payment token length - 10

paymentAccountReference The Payment Account Reference (PAR) associated with the

cardholder account that uniquely identifies the account to which
the payment card is associated.
Format: String

panLastFour Last 4 digits of the PAN included in an unmasked form.

Format: Numeric; maximum 4 digits

tokenLastFour Last 4 digits of the Payment Token.included in an unmasked form.

Format: Numeric; maximum 4 digits

panExpirationMonth The month when the account number is set to expire.

Format: Numeric; 2 digits

panExpirationYear The year when the account number is set to expire.

Format: Numeric; 4 digits

digitalCardData The metadata about the card, which contains digital card
information used in the acceptance environment and in the user
interface. This data provides a reference to the actual PAN or
Payment token without actually disclosing either.
Digital card data is grouped together based on the following
categories:

l Digital card information: data used in request and response

messages
l UI/UX presentation data: the data in user interfaces to provide
the consumer with a recognizable descriptor
l Digital card art: image that accompanies digital card information
for user interface purposes.
Format: DigitalCardData structure

2 May 2024 Visa Confidential 117

 Visa Secure Remote Commerce – Software Developer Kit
Get Payload

Field Description
dateOfCardCreated Timestamp that identifies when this card was enrolled into the SRC
system.
Format: UNIX Epoch timestamp. The value is in milliseconds.

maskedBillingAddress Billing address associated with the card, masked for display
purposes.
Format: MaskedAddress structure

dateOfCardLastUsed Timestamp that identifies when this card was last used for an SRC
transaction.
Format: UNIX Epoch timestamp. The value is in milliseconds.

dcf The Digital card facilitator (DCF) system associated with the card. It
is present only when the MaskedCard data structure is used in the
checkout or payload response.
Format: DCF structure

paymentCardDescriptor The card brand, defined within an SRC program.

Format: string, maximum 32 characters

paymentCardType Indicates whether the card supports both credit and debit options.
Format: It is a list of one or more of the following values:

l COMBO

digitalCardFeatures Set of Digital Card attributes related to digital card features that
should be displayed to the consumer.
Format: DigitalCardFeatures structure

countryCode Country code of issuance associated with the card issuer’s BIN
license.
Format: ISO 3166-1 alpha 2 country code

2 May 2024 Visa Confidential 118

 Visa Secure Remote Commerce – Software Developer Kit
Get Payload

Digital Card Data

Field Description
status The digital card status any given time in the SRC system.
Format: It is one of the following values:

l ACTIVE

l SUSPENDED

l EXPIRED

l PENDING

l CANCELLED

presentationName Presentation text created by the consumer to enable recognition of

the PAN entered into the DCF. This value is unique to the DCF and
defined by the consumer.
Format: String; maximum 64 characters

descriptorName Presentation text defined by the SRC programme that describes

the PAN presented as a digital card. This descriptor is the same
across all DCFs.
Format: String; maximum 64 characters

artUri URI of the Art card application. Can be provided by SRC Issuer
(SRCPI) .
Format: A valid URI; maximum 100 characters

artHeight Height of the Art card image, in pixels.

Format: Numeric value between 1 and 4096, inclusive
Example: artHeight: ...

artWidth Width of the Art card image, in pixels.

Format: Numeric value between 1 and 4096, inclusive
Example: artWidth : ...

pendingEvents Set of events that are pending completion such as Card Holder
Verification, AVS, SCA, Device Binding, etc. Required when the
value of status is set to PENDING.

Format: It is an array of one or more of the following strings:

l "PENDING_CONSUMER_IDV"

l "PENDING_CONSUMER_DEVICE_BINDING"

l "PENDING_CARDHOLDER_AUTHENTICATION"

authenticationMethod Authentication method indicated by the SRCi to the SRC System.

Format: AuthenticationMethod structure.

2 May 2024 Visa Confidential 119

 Visa Secure Remote Commerce – Software Developer Kit
Get Payload

Authentication Method

Field Description
authenticationMethodType (Required) SRCi to indicate for a particular transaction if Click to Pay
needs to perform managed authentication or not.
Format: It is one of the following values:

l SMS_OTP

l EMAIL_OTP

l APP_AUTHENTICATION

l MANAGED_AUTHENTICATION

authenticationSubject (Optional) Authentication subject. This should be set to

CARDHOLDER.

Format: It is one of the following values:

l CARDHOLDER

l CONSUMER

l CARD

uriData (Optional) URI associated with the authentication method, if

available.
Format: A UriData structure

authenticationCredentialReference (Optional) Authentication credential reference, which may be

provided by the identity provider once an authentication is initiated
to qualify the nature of the authentication method. For example,
SMS_OTP may use the masked mobile number "***-***-1234",
which can be displayed to the Consumer to aid method selection.
Format: String

methodAttributes (Optional) Attributes related to the authentication method; see

"Method Attributes."
Format: JSON object

2 May 2024 Visa Confidential 120

 Visa Secure Remote Commerce – Software Developer Kit
Get Payload

URI Data

Field Description
uri (Required) Specifies the URI for the given authentication method.
Format: String; maximum 2048 characters

uriType (Required) URI type.

Format: It is one of the following values:

l APP_URI

l WEB_URI

Method Attributes

Field Description
challengeIndicator (Optional) A challenge indicator value related to 3DS authentication.
Format: It is one of the following values:

l 01 - No preference

l 02 - No challenge requested

l 03 - Challenge requested (3DS Requestor Preference)

l 04 - Challenge requested (Mandate)

l 05 - No challenge requested (transactional risk analysis is

already performed)
l 06 - No challenge requested (Data share only)

l 07 - No challenge requested (strong consumer authentication is

already performed)
l 08 - No challenge requested (utilize trust list exemption if no
challenge required)
l 09 - Challenge requested (trust list prompt requested if
challenge required)

otpValue (Conditional) One time password; required when

authenticationMethodType in the authenticationMethod
structure is SMS_OTP or EMAIL_OTP.

Format: String; max. 16 characters

stepUpIdentifier (Conditional) Step-up identification; required when

authenticationMethodType in the authenticationMethod
structure is SMS_OTP, EMAIL_OTP, or APP_AUTHENTICATION.

2 May 2024 Visa Confidential 121

 Visa Secure Remote Commerce – Software Developer Kit
Get Payload

Digital Card Facilitator (DCF)

Field Description
applicationType Type of the environment of the DCF.
Format: It is one of the following types:

l WEB_BROWSER

l MOBILE_APP

l IOT_DEVICE

l OTHER

uri Uniform Resource Identifier (URI), which is a valid web address or

URI provided by DCF.
Format: String; maximum 255 characters

logoUri Uniform Resource Identifier (URI) for your company logo.image

provided by the DCF to support presentation.
Format: String; maximum 255 characters

name Legal name of DCF onboarded to the SRC system.

Format: Alphanumeric; maximum 60 characters

Masked Billing Address

Field Description
addressId The ID associated with the masked address in the SRC system.
Format: Universally Unique Identifier (UUID)

name Name of the individual receiving the delivered goods or service.

Only applicable for the shipping address.
Required If known to the SRC system
Format: String; maximum 60 characters

line1 Line 1 of the masked address in the SRC system. Required for
shipping address.
Format: Alphanumeric, Maximum 75 characters. For country
specific information, see Visa Checkout Address Formats by Country.

line2 Line 2 of the masked address in the SRC system. Required for
shipping address.
Format: Alphanumeric,Maximum 75 characters.

line3 Line 3 of the masked address in the SRC system. Required for
shipping address.
Format: Alphanumeric,, maximum 75 characters.

2 May 2024 Visa Confidential 122

 Visa Secure Remote Commerce – Software Developer Kit
Get Payload

Field Description
city City name associated with the masked address in the SRC system.
The address must have the city name in the valid address format
for the country.
Format: String; maximum 30 characters

state State code associated with the masked address in the SRC system.
The address must have the state name in the valid address format
for the country.
Must be a valid 2-characters code for US and CA and a valid 3-
characters code for AU.

Format: String; maximum 30 characters

Example: : CA

zip The zip code associated with the address.

Format: Alphanumeric, maximum 3–16 characters.

countryCode Country code associated with the masked address in the SRC
system.
Format: ISO-3166-1 alpha-2 standard code
Example: US

createTime Date and time the masked address was created.

Format: String; 25 characters

lastUsedTime Date and time the masked address was last used.
Format: UNIX Epoch timestamp. The value is in milliseconds.

Masked Consumer

Field Description
srcConsumerId SRC consumer Reference identifier generated by the SRC system.
Format: Universally Unique Identifier (UUID)

countryCode Country code associated with the masked address of consumer

country in the SRC system.
Format: ISO-3166-1 alpha-2 standard code

languageCode Consumer's locale.

Format: Locale, based on ISO format for language (ISO 639-1) and
alpha-2 country code (ISO 3166-1 alpha-2). The language and
country should be separated using a (_).

2 May 2024 Visa Confidential 123

 Visa Secure Remote Commerce – Software Developer Kit
Get Payload

Field Description
status Signifies the state of the consumer at any given time at the SRC
system.
Format: ConsumerStatus

dateConsumerAdded Timestamp that identifies when the consumer was added to the
SRC system .
Format: UNIX Epoch timestamp. The value is in milliseconds.

maskedConsumerIdentity Masked value of the primary verifiable consumer Identifier within

an SRC profile. For example, an email address or a mobile phone
number.
Format: maskedConsumerIdentity structure

maskedEmailAddress The email address of the consumer.

Note:
This field supports internationalization using UTF-8 characters.
Format: A valid email address; maximum 255 characters

maskedFirstName The first name of the consumer.

Format: Alphanumeric; maximum 30 characters

maskedLastName The last name of the consumer.

Format: Alphanumeric; maximum 30 characters

maskedFullName The full name of the consumer.

Format: Alphanumeric; maximum 60 characters

maskedMobileNumber The mobile number of the consumer

Format: PhoneNumber structure

maskedNationalIdentifier Masked consumer national Identifier

Format: Alphanumeric; maximum 20 characters

complianceSettings Consumer compliance settings

Format: ComplianceSettings structure

dateConsumerLastUsed Timestamp that identifies when the consumer last transacted to

the SRC system.
Format: UNIX Epoch timestamp. The value is in milliseconds.

2 May 2024 Visa Confidential 124

 Visa Secure Remote Commerce – Software Developer Kit
Get Payload

Masked Consumer Identity

Field Description
identityType The type of primary consumer Identifier to an SRC Profile.
Format: It is one of the following values:

l EMAIL_ADDRESS

l MOBILE_PHONE_NUMBER

Example: "identityType": "EMAIL_ADDRESS"

maskedIdentityValue Masked consumer’s email address or mobile phone number.

Example: "maskedIdentityValuee": "xyz**@visa.com"

Masked Phone Number

Field Description
countryCode Phone number country code.
Format: Alphabetic, numeric; maximum 4 characters.

phoneNumber Phone number of the consumer.

Format: A valid phone number; maximum 32 bytes.

2 May 2024 Visa Confidential 125

 Visa Secure Remote Commerce – Software Developer Kit
Get Payload

Assurance Data

Field Description
cardVerificationResults Verification status of the PAN.
Deprecated Format: It is one of the following values:
01 - Verified

02 - Not Verified

03 - Not performed

04 - 20 - EMVCo future use

21 - 99 - SRC system­specific

cardholderAuthenticationResults SRC cardholder verification results, performed by the SRC system,

which indicates whether the cardholder was verified or not, and
Deprecated
whether the results have been verified.
Format: It is one of the following values:
01 - Verified

02 - Not Verified

03 - Not performed

04 - 20 - EMVCo future use

21 - 99 - SRC system­specific

consumerVerificationResults Whether the consumer was verified or not, and the results if the
consumer has been verified.
Deprecated
Format: It is one of the following values:
01 - Verified

02 - Not Verified

03 - Not performed

04 - 20 - EMVCo future use

21 - 99 - SRC system­specific

2 May 2024 Visa Confidential 126

 Visa Secure Remote Commerce – Software Developer Kit
Get Payload

Field Description
verificationData Set of verification data structures relating to distinct types of
assurance.
Format: List of VerificationData structures.

eci If present, a value indicating the result of the authentication

performed or attempted during a transaction. Use this value in the
e-commerce authorization message to VisaNet.
Format: String; maximum 2 digits. It is one of the following values:

l 05 – Successful authentication

l 06 – Authentication attempted

l 07 – Authentication not performed

Verification Data

Field Description
verificationType Type of verification data.
Format: It is one of the following values:

l CARDHOLDER

verificationEntity Entity performing the verification.

Format: It is one of the following values:

l 01 - SRC Initiator

l 03 – SRCPI

verificationEvents Event causing the verification to occur.

Format: Array that can contain the following values:

l 01 – Payment transaction

l 02 – Add card/Card enrollment

l 03 – SRC Profile access

l 04 – Account verification

verificationMethod Method of verification.

Format: It is one of the following values:

l 02 – App-based authentication

l 04 – One-time passcode

l 21 – Visa Token Service step–up: Device binding

l 22 – Visa Token Service step–up: Cardholder verification

2 May 2024 Visa Confidential 127

 Visa Secure Remote Commerce – Software Developer Kit
Get Payload

Field Description
verificationResults Result of the verification.
Format: It is one of the following values:
01 – Verified

02 – Not Verified

03 – Not performed

04 – Not required

21 – Not allowed

verificationTimestamp Date and time in UTC that the verification was conducted.
Format: UNIX Epoch timestamp.

methodResults Method results.

Format: JSON object

Method Results
Attributes related to the results of a given authentication method.

Field Description
transStatus Whether a transaction qualifies as an authenticated transaction
(for 3DS authentication).
Format: It is one of the following string values:

l "Y"

l "R"

l "C"

l "N"

l "U"

l "A"

l "D"

l "I"

dsTransId ID assigned by the DS to identify the transaction (for 3DS authenti­

cation).
Format: String; UUID

acsTransId ID assigned by the ACS to identify the transaction (for 3DS authenti­
cation).
Format: String; UUID

Note:

2 May 2024 Visa Confidential 128

 Visa Secure Remote Commerce – Software Developer Kit
Get Payload

Refer to the EMVCo 3DS Specification for more details on the 3DS­specific attributes and
definitions.

Get Payload API Errors

HTTP Status Code Description
200 OK, transaction credential response details included in the
response body.

400 Bad request, see error object for details.

401 Unauthorized, see error object for details, e.g. authorization token
validation failure.

403 Forbidden, see error object for details, e.g. client identity (origin)
not validated.

500 Internal server error, see error object for details.

Get Payload API Examples

Get Payload PAN Example

Request
None

Response PAN Sample

{
"maskedCard": {
"srcDigitalCardId": "efb...02",
"panBin": "430753",
"panLastFour": "0008",
"panExpirationMonth": "12",
"panExpirationYear": "2023",
"digitalCardData": {
"status": "ACTIVE",
"presentationName": "... ...",
"descriptorName": "... ..."
},

2 May 2024 Visa Confidential 129

 Visa Secure Remote Commerce – Software Developer Kit
Get Payload

"dateOfCardCreated": "197...3Z",
"maskedBillingAddress": {
"addressId": "e43...02",
"countryCode": "US"
}
},
"shippingAddressZip": "94404",
"shippingCountryCode": "US",
"maskedConsumer": {
"srcConsumerId": "H5p...A=",
"countryCode": "US",
"languageCode": "en-US",
"status": "ACTIVE",
"dateConsumerAdded": "2018-04-25T03:20:27.001Z",
"maskedConsumerIdentity": {
"identityType": "EMAIL_ADDRESS",
"maskedIdentityValue": "[email protected]"
},
"maskedEmailAddress": "xyz**@visa.com",
"maskedFirstName": "...",
"maskedLastName": "...",
"maskedFullName": "... ..."
},
"encryptedPayload": "eyJ..._Q",
"assuranceData": {
"cardVerificationResults": "01"
}
}

Decrypted Response
See "Decrypted Payload PAN Example" in Unencrypted Payload Contents chapter.

Get Payload Token Example

Request
None

Response Token Based Sample

{
"maskedCard": {
"srcDigitalCardId": "ebc...01",
"panBin": "462294",
"panLastFour": "0693",
"tokenBinRange": "489...01",
"paymentAccountReference": "V00...23",
"tokenLastFour": "6469",
"panExpirationMonth": "12",
"panExpirationYear": "2021",

2 May 2024 Visa Confidential 130

 Visa Secure Remote Commerce – Software Developer Kit
Get Payload

"digitalCardData": {
"status": "ACTIVE",
"presentationName": "... ...",
"descriptorName": "... ...",
"artUri": "https://test...visa.com/MPC...Ak.png",
"artHeight": 105,
"artWidth": 164
},
"pendingEvents": [
"PENDING_CARDHOLDER_AUTHENTICATION",
"PENDING_CONSUMER_IDV",
"PENDING_CONSUMER_DEVICE_BINDING"
],
"dateOfCardCreated": "1970-01-01T00:00:00.085Z",
"maskedBillingAddress": {
"addressId": "b3f...02",
"countryCode": "GB"
}
},
"shippingAddressZip": "K1G 4B5",
"shippingCountryCode": "CA",
"maskedConsumer": {
"srcConsumerId": "mMK...o=",
"countryCode": "US",
"languageCode": "en-US",
"status": "ACTIVE",
"dateConsumerAdded": "2017-10-28T16:11:42.060Z",
"maskedConsumerIdentity": {
"identityType": "EMAIL_ADDRESS",
"maskedIdentityValue": "[email protected]"
},
"maskedEmailAddress": "xyz**@gmail.com",
"maskedFirstName": "...*",
"maskedLastName": "...",
"maskedFullName": "... ..."
},
"encryptedPayload": "eyJ...Vw",
"assuranceData": {
"cardVerificationResults": "01"
}
}

Decrypted Response
See "Decrypted Token Payload Example " in Unencrypted Payload Contents chapter.

2 May 2024 Visa Confidential 131

Chapter 5
Confirmation Service

About the Confirmation Service

The Confirmation Service enables SRC Initiators and SRC participants to notify the SRC system
about the outcome of a checkout order or payment.

Confirmation Service Request

Endpoints

Resource Path

wallet/src/confirmations

2 May 2024 Visa Confidential 132

 Visa Secure Remote Commerce – Software Developer Kit
Confirmation Service

Sandbox

https://cert.api.visa.com/wallet/src/confirmations?apikey=key

Live

https://api.visa.com/wallet/src/confirmations?apikey=key

Method

POST

2 May 2024 Visa Confidential 133

 Visa Secure Remote Commerce – Software Developer Kit
Confirmation Service

Required Headers

Header Description
x-pay-token A token identifying the transaction and its contents.
Format: Alphanumeric; maximum 100 characters in the form of
xv2:UTC_Timestamp:HMAC-SHA256_hash, where

l UTC_Timestamp is a UNIX Epoch timestamp

l HMAC-SHA256_hash is an HMAC-SHA256 hash using the shared
secret associated with your API key and the following
unseparated items:

1. Timestamp from the transaction; exactly the same as

UNIX_UTC_Timestamp
2. Resource path (API name)
3. This HTTPS request's query string, if it exists

Note: To create the query string, concatenate

all query string components (names and
values) as UTF-8 characters, which are URL-
encoded per RFC 3986. Hex characters must be
uppercase. Multiple parameters must be
sorted using lexicographic byte ordering and
separated from each other by an ampersand
(&) character (ASCII code 38). Parameter names
are separated from their values by the =
character (ASCII character 61), which must be
present even if the value is empty.
“Unreserved" characters specified in Section
2.3 of RFC 3986 , including dash -, dot .,
underscore _, and tilde ~ should not be URL-
encoded.
4. Complete request body, when a request body exists
Example: x-pay-token: xv2:1440199445:HMAC-
SHA256_hash result

Accept Acceptable response format.

Format: Must include the following value:
application/json

Example: Accept: application/json

Content-Type Format of the content.

Format: Must include the following value:
application/json

Example: Content-Type: application/json

2 May 2024 Visa Confidential 134

 Visa Secure Remote Commerce – Software Developer Kit
Confirmation Service

Query Parameters

Field Description
apikey (Required) Inbound Authentication Key used for generating X-Pay-
Token
Format: Alphanumeric String

POST Request Body

Field Description
srcClientId (Required) SRCi identifier generated by an SRC system.
Format: Alphanumeric; maximum 64 characters

srcCorrelationId (Conditional) This is the unique identifier generated by SRC system

to track and link SRC messages. This will be used as the transaction
identifier assigned by the SRC system for this particular
transaction.
Required if available within the present checkout session (e.g.
received in an earlier API response during the present session).
Format: Universally Unique Identifier (UUID)

srciTransactionId (Optional) 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
Format: Alphanumeric, maximum 100 characters

srcDpaId (Required) DPA identifier, which is generated by the SRC system

during DPA registration.
Format: String, 64 bytes

serviceId (Conditional) Form of payment service. For Visa QR, the value must
be SELLER_PRESENTED; otherwise, not used.

confirmationData (Required) Contains all optional confirmation data elements

associated with the confirmation call.
Format: ConfirmationData structure

2 May 2024 Visa Confidential 135

 Visa Secure Remote Commerce – Software Developer Kit
Confirmation Service

Confirmation Data

Field Description
checkoutEventType (Optional) Event type associated with the update.
Format: It is one of the following values:

l 01 - Authorize

l 02 - Capture

l 03 - Refund

l 04 - Cancel

l 05 - Fraud

l 06 - Chargeback

l 07 - Other

checkoutEventStatus (Optional) Event types associated with the order.

Format: It is one of the following values:

l 01 - Created

l 02 - Confirmed

l 03 - Cancelled

l 04 - Fraud Cancelled

l 05 - Other

l 06 – 50 - EMVCo future use

l 51 - 99 - SRC

confirmationStatus (Optional) Status of the event as provided by the SRCi in the Confir­
mation message.
Format: It is one of the following values:

l 01 - Success

l 02 - Failure

l 03 - Other

confirmationReason (Optional) Description of the reason for the event associated with
the order.
Format: String; maximum 64 characters

confirmationTimestamp (Optional) Date and time, in coordinated Universal Time, (UTC) of

the event completion corresponding to the Confirmation event by
the SRCi.
Format: UNIX Epoch timestamp, in milliseconds

2 May 2024 Visa Confidential 136

 Visa Secure Remote Commerce – Software Developer Kit
Confirmation Service

Field Description
networkAuthorizationCode (Optional) Authorization code associated with an approved
transaction.
Format: String; maximum 25 characters

networkTransactionIdentifier (Optional) Unique authorization-related tracing value assigned by a

Payment Network.
Format: String; maximum 25 characters

paymentNetworkReference (Optional) Transaction identifier as provided by a Payment Network

after authorization has been completed.
Format: String; maximum 25 characters

assuranceData Future

transactionAmount (Optional) Amount of the transaction. Supplied if 3DS is performed

by the SRC system.
Format: TransactionAmount structure

Transaction Amount

Field Description
transactionAmount (Required) Amount associated with transaction.
Format: Float. Maximum 18 digits

transactionCurrencyCode (Required) Currency code used for the transaction amount.

Format: ISO 4217 alpha-3 currency code

Confirmation Service Response

Response Body

None

2 May 2024 Visa Confidential 137

 Visa Secure Remote Commerce – Software Developer Kit
Confirmation Service

Confirmation Service API Errors

HTTP Status Code Description

204 No content, the confirmation message was accepted.

400 Bad request, see error object for details.

401 Unauthorized, see error object for details, e.g. authorization token
validation failure.

403 Forbidden, see error object for details, e.g. client identity (origin)
not validated.

500 Internal server error, see error object for details.

Confirmation Service Example

Request

{
"srcClientId": "J6X...MM",
"srcCorrelationId": "811...01",
"confirmationData": {
"checkoutEventType": "02",
"confirmationStatus": "01",
"checkoutEventStatus": "02",
"confirmationReason": "Purchased",
"confirmationTimeStamp": "2019-07-10T22:18:14.802Z",
"networkAuthorizationCode": "123456",
"networkTransactionIdentifier": "660...03",
"paymentNetworkReference": "abc#21",
"transactionAmount": {
"transactionAmount": 200,
"transactionCurrencyCode": "USD"
}
}
}

2 May 2024 Visa Confidential 138

Appendix A
Decrypting the SRC Payload

Java Example for SRC Payload

Symmetric Decryption
The following Java code, using the JOSE4j API jose4j-0.6.5.jar, provides an example of
decrypting the payload.

EXAMPLE

package ...;

import java.security.MessageDigest;

import javax.crypto.spec.SecretKeySpec;
import org.jose4j.jwe.JsonWebEncryption;

public class DecryptJWE {

public static String decryptJWE(String secret, String jwe)

throws Exception {
MessageDigest md = MessageDigest.getInstance("SHA-256");
byte[] digest = md.digest(secret.getBytes("UTF-8"));

2 May 2024 Visa Confidential 139

 Visa Secure Remote Commerce – Software Developer Kit
Decrypting the SRC Payload

JsonWebEncryption jweDecryptor = new JsonWebEncryption();

jweDecryptor.setCompactSerialization(jwe);
jweDecryptor.setKey(new SecretKeySpec(digest, "AES"));

return jweDecryptor.getPlaintextString();
}
}

Node.js Example for SRC Payload

Symmetric Decryption
The following Node.js JavaScript code, using node-jose, provides an example of decrypting
the payload.

EXAMPLE

var jose = require('node-jose');

var crypto = require('crypto');

module.exports = {
decryptJWE: function(secret, payload){
return new Promise(function(resolve, reject){
var SS_Hashed =

crypto.createHash('sha256').update(secret).digest('hex');
jose.JWK.asKey({kty: 'oct', k: Buffer.from(SS_Hashed,
'hex')})
.then(function(key){
jose.JWE.createDecrypt(key)
.decrypt(payload)
.then(function(result){
resolve(result);
})
.catch(function(error){
reject(error);
});
})
.catch(function(error){
reject(error);
});
});
}
};

2 May 2024 Visa Confidential 140

Appendix B
Generating a JWE for PAN
Encryption

Encrypting the PAN

This code snippet is used for creating PAN JWE on the browser side. This example uses the
node-jose library in browserify format.

// getNodeJoseLib(); Get node-jose library in browserify format

// Code to generate JWE using node-jose library
/**
* @param kid kid for public certificate. Contact Visa
representative for this value
* @param keys Public key to be used for encryption.
Contact Visa representative for *
@param payload Card information to be encrypted,

{"card":{
"primaryAccountNumber":"424..2",
"panExpirationMonth":"10",
.."panExpirationYear":"2022",
"cardSecurityCode":"123",
.."cardholderFullName":"cardholder name"}

2 May 2024 Visa Confidential 141

 Visa Secure Remote Commerce – Software Developer Kit
Generating a JWE for PAN Encryption

}
* @param cb Returning encrypted PAN as JWE string
to this callback function */

function generateJWE(kid, keys, payload, cb) {

const keyInput = {
"kty": "RSA",
"e": keys.e, // Public key exponent
"kid": kid,
"use": "enc",
"n": keys.n, // Public key modulus
"alg": "RSA-OAEP-256",
"ext_content": "payload"
};
jose.JWK.asKey(keyInput)
.then((key) => {
console.log("JWK ", JSON.stringify(key));
const contentAlg = 'A25..CM';
let options = {
format: 'compact',
contentAlg: contentAlg,
fields: {
kid: key.kid,
typ: 'JOSE',
iat: Date.now(),
alg: key.alg,
enc: contentAlg
}
};
jose.JWE.createEncrypt(options, key).
update(payload).
final().
then((serializedJWE) => {
console.log("Encrypted data: ",
JSON.stringify(serializedJWE));
cb(serializedJWE);
}, (error) => {
console.log("Error occurred: ",error.message)
cb(null);
});
},(error) => {
console.log("Error occurred: ", error.message);
cb(null);
})
}

2 May 2024 Visa Confidential 142

Appendix C
JWE Composition Details

JSON Web Encryption (JWE) Using

Shared Secret
The encryption key provided during onboarding is used to encrypt and decrypt payloads. JSON
Web Encryption (JWE) content should be signed or encrypted using the shared secret that was
provided to client at the time of onboarding.

Introduction
Visa uses JSON Web Encryption (JWE) to encode sensitive field level information. Encrypted
input parameters should be constructed before sending them in API requests.
Visa Installment Solutions APIs use the following naming convention for fields that require
encryption in this document.
"enc<FIELD>" : "JWE ( ... ) "

See the complete specification for JWE: https://tools.ietf.org/html/draft-ietf-jose-json-web-

encryption-40.

2 May 2024 Visa Confidential 143

 Visa Secure Remote Commerce – Software Developer Kit
JWE Composition Details

JWE Composition and Conventions

BASE64URL (UTF8 (JWE Header)) || ‘.’ ||

BASE64URL (JWE Encrypted Key) || ‘.’ ||
BASE64URL (JWE IV) || ‘.’ ||
BASE64URL (JWE Ciphertext) || ‘.’ ||
BASE64URL (JWE Authentication Tag)

The conventions are as follows:

l BASE64URL encoding with NO padding.

l Compact serialization style (elements separated by “.”)

l Use a CEK (Content Encryption Key) of 256bits size.

l Authentication Tag will be generated as an additional output of the AES-GCM-256

encryption. Size of this field is 128 bits.
l All String to byte and vice-versa conversions are done with UTF-8 charset.

Note: The JWE Protected Header is input as the AAD (Additional Authenticated Data)
parameter of the authenticated encryption (AES-GCM) of the “text to encrypt”.

Sample JWE Header for Asymmetric Encryption

"header": {
"alg": "RSA-OAEP-256"
"typ": "JOSE",
"kid": "50charAPIKey", // API key
"enc": "A256GCM"
}

Sample JWE Header for Symmetric Encryption

"header": {
"alg": "AGCM256KW"
"typ": "JOSE",
"tag": "<128bitvalue>", // HMAC generated from applying
AES-256-GCM-KW to the CEK
"kid": "50charAPIKey", // API key
"enc": "AGCM256"
}

Sample JWE Body

l encrypted_key: base64 encoded form. CEK encrypted using AGCM256KW (alg)
algorithm and the CEK IV
l iv: base64 encoded form. IV for the text encryption. Size of IV is to be 96 bit Base64
encoded form

2 May 2024 Visa Confidential 144

 Visa Secure Remote Commerce – Software Developer Kit
JWE Composition Details

l ciphertext: encrypted blob generated using the AES-GCM encryption (enc) of the text to
encrypt
l tag: base64 encoded form. HMAC generated using the AES-GCM encryption of the text
to encrypt. The size of the tag should be 128 bits

“encrypted_key”: “UghIOgu ... MR4gp_A=”,

“iv”: “AxY8DctDa….GlsbGljb3RoZQ=”,
“ciphertext”: “KDlTthhZTGufMY…….xPSUrfmqCHXaI9wOGY=”,
“tag”: “Mz-VPPyU4…RlcuYv1IwIvzw=”

2 May 2024 Visa Confidential 145

Appendix D
What’s New in Prior Versions

What's New in Version 20.01

Initial release

What's New in Version 20.03

This release fully implements disassociating the DPA or device from the consumer’s SRC profile
device by providing a field in the checkout method that identifies when the
unbindAppInstance method should be called.

What's New in Version 20.10

Added the consumerIdentity field to the consumer structure in the decrypted payload,
which identifies the consumer’s identity from a 3rd-party payment service provider or SRCi. In

2 May 2024 Visa Confidential 146

 Visa Secure Remote Commerce – Software Developer Kit
What’s New in Prior Versions

these cases, the 3rd-party payment service provider or SRCi populates consumer information in
the checkout request. A new consumer structure has been added to the checkout request to
receive this information.

What's New in Version 21.02

This version is primarily a maintenance release. It provides additional information about the
JavaScript checkout() method.

What's New in Version 21.06

This version is primarily a maintenance release. It provides additional information about the
JavaScript SDK endpoints.

What’s New in Version 22.04

Interface Changes
The following changes were made to the interface:
l Added the tokenId field to the MaskedCard structure.

l Added the pendingEvents list to the DigitalCardData structure.

l Added a VerificationData structure.

l Added a verificationData field to the AssuranceData structure and deprecated its

other fields.

Documentation Changes
l Corrected the name of the networkAuthorizationCode field.

2 May 2024 Visa Confidential 147

 Visa Secure Remote Commerce – Software Developer Kit
What’s New in Prior Versions

What’s New in Version 22.07

Interface Changes
The following changes were made to the interface:
l Added the complianceSettings field and related structure to the Checkout request.

l Removed emailAddress field from the consumer structure of the checkout() API.

Documentation Changes
l Clarified that if idToken is not provided in the Unbind App Instance API, the app
instance will be unbound from the Visa SRC System.
l Clarified that the srcClientId query parameter for the Get Payload API accepts only
an API key value.
l Modified the mobileNumber field description in the consumer structure of the
checkout() API. It is optional and used to prefill the DCF, if available.

What’s New in Version 23.04

This version of the SDK enables the following additional features:
l Merchant Orchestrated Checkout—An implementation of Click to Pay checkout in which
the end-to-end user experience is managed and rendered by the merchant.
l Managed Authentication—Authentication required for a given transaction, facilitated by
the SRC System.

Interface Changes
The following changes were made to the interface:
l Added the authenticationContext and authenticationMethod fields and related
structure to the Checkout request.
l Added the following fields to the dpaTransactionOptions structure:
transactionInstruction, numberOfPayments, purchaseDate,
recurringEndDate, and recurringFrequency.

l Added checkoutOrchestrator and customFlowType fields to, and removed the

dpaIntegrationType field from, the customInputData structure in
dpaTransactionOptions.

l Added a methodResults field to the verificationData structure.

2 May 2024 Visa Confidential 148

 Visa Secure Remote Commerce – Software Developer Kit
What’s New in Prior Versions

l Deprecated the threeDSInputData and threeDSOutputData structures.

l Deprecated orderType in DPA Transaction Options.

Documentation Changes
l Provided additional context for "Requirements When Checking Out With an Existing
Card" in the checkout API.

l Clarified that checkout includes the ability to return authentication results.

l Clarified that srcClientId is alphanumeric, maximum 64 characters.

l Updated example for init JavaScript API to show how to indicate Merchant
Orchestrated Checkout.
l Removed the customInputData structure from "Compliance Settings in the Request"
example of the checkout API.

l Removed deprecated 3DS structures from checkout API and Payload examples.

l Updated the assuranceData structure documentation in the Get Payload API response
and added verificationData and methodResults structures to the response.

What’s New in Version 23.08

Interface Changes
The following changes were made to the interface:
l Added the paymentCardTypeSelected field to the customInputData structure in
dpaTransactionOptions.

l Added the consumerNationalIdentifierRequested field to the

dpaTransactionOptions structure.

l Added a nationalIdentifier field to the Consumer object.

l Added the paymentCardType field to the MaskedCard structure.

Documentation Changes
The following changes were made to the interface:
l Clarified that dpaPresentationName is required to facilitate transaction
authentication.
l Noted that you should contact your Visa representative for information about using
dpaThreeDsPreference to receive authentication data.

2 May 2024 Visa Confidential 149

 Visa Secure Remote Commerce – Software Developer Kit
What’s New in Prior Versions

l The dpaShippingPreference field is not required for Merchant Orchestrated

Checkout; if passed, it will be changed to NONE.

l The correct name for dpaDynamicDataTTLMinutes is dpaDynamicDataTtlMinutes.

l Added CARD_APPLICATION_CRYPTOGRAM_LONG_FORM and

DYNAMIC_CARD_SECURITY_CODE values to the dynamicDataType field and deprecated
the TAVV and DTVV values; also, changed code samples to match.

l Changed dateofCardCreated to dateOfCardCreated.

l Changed dateofCardLastUsed to dateOfCardLastUsed.

l Changed the SRC Profile error reason code from ACCT_INACCESSABLE to

ACCT_INACCESSIBLE.

l Clarified that DpaTransactionOptions is dpaTransactionOptions.

l Removed the following authenticationReasons: CARD_VERIFICATION,

CONSUMER_IDENTITY_VALIDATION, ENROL_FINANCIAL_INSTRUMENT, and
CONSUMER_IDENTITY_VALIDATION.

l A value must be provided in the following authenticationContext fields to perform

transaction authentication by the SRC System: acquirerMerchantId, acquirerBIN,
and merchantName.

l Changed enum values for authenticationMethodType to include only the following

ones: SMS_OTP, EMAIL_OTP, APP_AUTHENTICATON, and MANAGED_AUTHENTICATION.

l Added a section for URI Data (uriData field in Checkout Parameters Authentication
Method).
l Provided additional information about Method Results of a given authentication method
and identified transStatus as a sting rather than a boolean value.

l Changed Unbind App Instance return field name from srcCorrelatedId to

srcCorrelationId.

l Changed the threeDSOutputData field name in the payload to threeDsOutputData

and changed code samples to match.
l Changed receipientid to receipientId in the Get Payload query parameters.

l Changed shippingAddressZIP to shippingAddressZip in the Get Payload API

response body.
l Added an additional item to the verificationEntity field in the Get Payload API
response.
l Added additional items to the verificationMethod field in the Get Payload API
response.

2 May 2024 Visa Confidential 150

 Visa Secure Remote Commerce – Software Developer Kit
What’s New in Prior Versions

l Fixed the syntax for the completeIdentityValidation JavaScript method.

l Added a section on "Checkout Journeys." Sections showing the user experience,

flowcharts, and conceptual explanations in the SDK Overview chapter have been
migrated to the Click to Pay Digital Terminal Implementation Guide. For more information,
contact your Visa representative.
l Changed ALL option in dpaShippingPreference and dpaBillingPreference fields
to FULL and changed code samples to match.

l Added new code samples for 3DS: "Checkout input when existing card is selected – 3DS
version," "Checkout input when new card is added – 3DS version," "Assurance Data for
3DS in the Decrypted Checkout Response," "Decrypted Token Payload Example From
Get Payload Operation - 3DS Version," and "Decrypted 3DS Assurance Data From Get
Payload Operation."
l Removed transStatusReason from Method Results.

l Provided additional information about eci values.

What’s New in This Version

Interface Changes
The following changes were made to the interface:
l Added the authenticate JavaScript method.

l Added the authenticatedCredentialRequested field to dpaTransactionOptions

structure.
l Added shippingAddress and assuranceData fields to Checkout Parameters.

l Added the following fields to the methodAttributes structure: otpValue and

stepUpIdentifier.

l Added the PENDING_CARDHOLDER_AUTHENTICATION value to the pendingEvents field

in the digitalCardData structure. Updated Decrypted Summary Checkout Response
in Checkout Examples and Response Token Based Sample in Get Payload to show the
pendingEvents field.

l Added authenticationMethod field to digitalCardData structure.

2 May 2024 Visa Confidential 151

 Visa Secure Remote Commerce – Software Developer Kit
What’s New in Prior Versions

Documentation Changes
The following changes were made to documentation:
l Removed the "Decrypted Token Payload Example From Checkout Operation" and
renamed the "Decrypted Token Payload Example From Get Payload Operation - 3DS
Version" to "Decrypted Token Payload Example." The decrypted token payloads are
essentially the same regardless of the API used to obtain the payload.

2 May 2024 Visa Confidential 152

Revision History

l Version 24.04, April 23, 2024

l Version 23.09, September 26, 2023

l Version 23.08, August 29, 2023

l Version 23.06, July 5, 2023

l Version 23.04, May 9, 2023

l Version 22.07, July 27, 2022

l Version 22.04, May 2, 2022

l Version 21.06, June 30, 2021

l Version 21.02, February 25, 2021

l Version 20.10, November 4, 2020

l Version 20.03, March 25, 2020

l Version 20.02, February 25, 2020

l Version 20.01, January 22, 2020

2 May 2024 Visa Confidential 153