Visa Token Service

Issuer API Specifications (JSON)

Effective: 6 June 2023

Version 3.7 (23.05)

© 2018 - 2023 Visa. All Rights Reserved.

Visa Confidential
Important Note on Confidentiality and Copyright

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 terms of a current participation agreement and confidentiality
and feedback restrictions in the Visa Core Rules and Visa Product and Service Rules, non-Client Third-Party Processors
that have an executed and valid Exhibit K on file with Visa, and other third-parties that have a current Visa Digital
Enablement Program participation agreement with Visa that covers disclosure and use of the information contained
herein, including confidentiality and feedback restrictions.

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.

Visa and other trademarks are trademarks or registered trademarks of Visa.

All other product names mentioned herein are the trademarks of their respective owners.

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.

About This Guide

This document describes Application Programming Interfaces (APIs) that issuers use to perform various token-related
operations, such as provisioning and notifications.
Contents
Preface

Revision History

Chapter 1 • Getting Started with REST APIs

Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Backward Compatibility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Outbound From Visa. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Inbound to Visa. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

HTTPS Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

HTTPS Request Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

HTTP Response Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

URL Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Error Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Error Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Error Response Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Error Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Error Details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Sample Error Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Standard Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Selected Mappings of TAR ISO Message Fields. . . . . . . . . . . . . . . . . . . . . . 31

Base64URL Encoding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Outbound Notifications from Visa. . . . . . . . . . . . . . . . . . . . . . . . . . . .32

Chapter 2 • Onboarding
Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Key Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

6 June 2023 Visa Confidential 3

Visa Token Service – Issuer API Specifications (JSON)

Client Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33

Connecting to Visa-Exposed Web Services. . . . . . . . . . . . . . . . . . . . . . . . 34

Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Security Requirements for Visa-Exposed Web Services. . . . . . . . . . . . . . . . . 34

Security Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Connecting to Issuer-Exposed Web Services. . . . . . . . . . . . . . . . . . . . . . . 36

Security Requirements for Issuer-Exposed Web Services. . . . . . . . . . . . . . . . 36

Source and Destination Connectivity Information Exchange. . . . . . . . . . . . . . . . .37

Information Exchange. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Chapter 3 • Data Encryption and Decryption

Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Data Encryption/Signature. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

JWE Using RSA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

General Steps for Data Encryption. . . . . . . . . . . . . . . . . . . . . . . . . . 42

JWS Using RSA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Creating a Signature. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Signature Validation/Data Decryption. . . . . . . . . . . . . . . . . . . . . . . . 45

Signature Validation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Data Decryption. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45

Chapter 4 • Encrypted Payload Data Structures

Cardholder Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Address. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Expiration Date. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Token Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Risk Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Device Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Chapter 5 • Inbound API Specifications (To Visa)

6 June 2023 Visa Confidential 4

Visa Token Service – Issuer API Specifications (JSON)

PAN Lifecycle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60

Lifecycle Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

PAN Replacement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Query Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Request Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Unencrypted Payload. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Successful Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Error Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Sample Payloads. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Sample Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Token Inquiry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Query Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Token Inquiry Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

OTP Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77

Discretionary Data Information. . . . . . . . . . . . . . . . . . . . . . . . . 78

Cardholder Verification List. . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Device Binding Info. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Decrypted Payload. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Token Inquiry Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Sample Payloads. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Token Inquiry by PAN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

6 June 2023 Visa Confidential 5

Visa Token Service – Issuer API Specifications (JSON)

Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Query Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Request Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Token Details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Error Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Sample Payloads. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Sample Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Sample Successful Response. . . . . . . . . . . . . . . . . . . . . . . . . . 88

Token Lifecycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88

Lifecycle Actions at Token States. . . . . . . . . . . . . . . . . . . . . . . . . . 89

Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Query Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Request Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Successful Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Error Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Sample Payloads. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Sample Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Sample Successful Response. . . . . . . . . . . . . . . . . . . . . . . . . . 95

Retrieve Network Hub Push Provisioning (NHPP) Profiles. . . . . . . . . . . . . . . . . . 95

Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Query Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Request Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

6 June 2023 Visa Confidential 6

Visa Token Service – Issuer API Specifications (JSON)

Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Successful Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Error Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Sample Payloads. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Sample Successful Request. . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Sample Successful Response. . . . . . . . . . . . . . . . . . . . . . . . . . 99

Update Card Metadata. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101

Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Query Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Request Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Successful Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Error Responses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Sample Payloads. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Sample Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Sample Successful Response. . . . . . . . . . . . . . . . . . . . . . . . . . 110

Sample Business Error Response. . . . . . . . . . . . . . . . . . . . . . . . 110

Token Requestor Report. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111

Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Query Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Request Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Successful Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Error Responses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Sample Payloads. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

6 June 2023 Visa Confidential 7

Visa Token Service – Issuer API Specifications (JSON)

Chapter 6 • Outbound API Specifications (From Visa)

Approve Provisioning. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116

Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Request Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Successful Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Error Responses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Sample Payloads. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Sample Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Sample Successful Response. . . . . . . . . . . . . . . . . . . . . . . . . . 131

Approve Provisioning Stand-In Notification. . . . . . . . . . . . . . . . . . . . . . . 131

Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131

Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Query Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Request Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Successful Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Error Responses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Sample Payloads. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Sample Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Successful Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Card Metadata Update Notification. . . . . . . . . . . . . . . . . . . . . . . . . . 137

Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137

Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Query Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

6 June 2023 Visa Confidential 8

Visa Token Service – Issuer API Specifications (JSON)

Request Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Successful Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Error Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Sample Payloads. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

Sample Successful Request. . . . . . . . . . . . . . . . . . . . . . . . . . 140

Sample Successful Request With Business Error. . . . . . . . . . . . . . . . . . 140

Check Eligibility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .141

Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Request Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Successful Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Error Responses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Sample Payloads. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Sample Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

Sample Successful Response. . . . . . . . . . . . . . . . . . . . . . . . . . 149

Sample Business Error Response. . . . . . . . . . . . . . . . . . . . . . . . 149

Device Token Binding Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150

Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Request Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

Successful Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

Error Responses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

Sample Payloads. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

Sample Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

6 June 2023 Visa Confidential 9

Visa Token Service – Issuer API Specifications (JSON)

Sample Successful Response. . . . . . . . . . . . . . . . . . . . . . . . . . 159

Get Cardholder Verification Methods. . . . . . . . . . . . . . . . . . . . . . . . . . 159

Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160

Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

Request Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Successful Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Error Responses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Sample Payloads. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Sample Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Sample Successful Response. . . . . . . . . . . . . . . . . . . . . . . . . . 174

Sample Business Error Response. . . . . . . . . . . . . . . . . . . . . . . . 175

PAN Update Notification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175

Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

Query Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

Request Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

Successful Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

Error Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

Sample Payloads. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

Sample Successful Request. . . . . . . . . . . . . . . . . . . . . . . . . . 180

Sample Successful Response. . . . . . . . . . . . . . . . . . . . . . . . . . 180

Send Passcode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .181

Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

6 June 2023 Visa Confidential 10

Visa Token Service – Issuer API Specifications (JSON)

Request Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Successful Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Sample Business Error Response. . . . . . . . . . . . . . . . . . . . . . . . 189

Error Responses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

Sample Payloads. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

Sample Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

Token Create Notification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .191

Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

Query Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

Request Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

Successful Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

Error Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

Sample Payloads. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

Sample Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

Sample Successful Response. . . . . . . . . . . . . . . . . . . . . . . . . . 201

Token Notification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .201

Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

Query Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

Request Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

Successful Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

Error Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

Sample Payloads. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

6 June 2023 Visa Confidential 11

Visa Token Service – Issuer API Specifications (JSON)

Sample Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

Sample Successful Response. . . . . . . . . . . . . . . . . . . . . . . . . . 211

Chapter 7 • Visa Card Enrollment Hub (VCEH)

Push Card Enrollment to Wallet API. . . . . . . . . . . . . . . . . . . . . . . . . . 212

Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .212

Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Query Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Request Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Unencrypted Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

Successful Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

Error Responses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

Sample Payloads. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

Sample Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

Sample Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .223

VCEH Web Proxy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

VCEH Proxy Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

pushData Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

VCEH Returns to Issuer App. . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

results Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

Sample Payloads. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

Push Provisioning Status Notification. . . . . . . . . . . . . . . . . . . . . . . . . . 235

Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .235

Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

Query Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

Request Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

6 June 2023 Visa Confidential 12

Visa Token Service – Issuer API Specifications (JSON)

Successful Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

Error Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

Sample Payloads. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

Sample Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

Sample Successful Response. . . . . . . . . . . . . . . . . . . . . . . . . . 239

Chapter 8 • Update Card Metadata Batch Specifications

Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

Batch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

File Naming Convention. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

Batch Record Specification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

Batch Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

Batch Record Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

Sample Batch File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

Success Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

Failure Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

Chapter 9 • Performance Targets

Expected API Response Times. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

Appendix A • Reject Codes

Reject Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

6 June 2023 Visa Confidential 13

Preface

This document describes Application Programming Interfaces (APIs) that issuers use to perform
various token-related operations, such as provisioning and notifications.

Audience
Visa Token Service Issuer API Specifications is intended for issuers using Visa Token Service (VTS) REST
APIs.

Prerequisites
1. Issuer has been onboarded by Visa.
2. Issuer and Visa have exchanged X.509 certificates containing the required public keys.
3. Issuer has undergone client-specific configuration for various APIs.

Document Conventions

Conventions Purpose

bold Used for command buttons, menu names, and menu choices
referenced in procedures. Also used for extra emphasis (stronger than
italics).

italics Used for document titles, for explaining an unusual term the first time
it appears, and for emphasis.

Note: Gives more information about the preceding topic.

Important: Emphasizes significant information about the immediately preceding

topic.

Example: Presents an example of what the accompanying text describes.

n/a Stands for not applicable. Also used to indicate that there is not any
information.

Courier Used for items that appear in code.

Letter Gothic Used primarily to re-create screen captures and sample report layouts
and for prompts and messages displayed by the system.

text in quote marks Used to refer to section names in a chapter.

6 June 2023 Visa Confidential 14

Revision History

Version Date Comments

Web
3.7 (23.04) May 2023 l Added an encryptedData field to the Device Token Binding
Request API request, which contains the encrypted tokenInfo
structure. The tokenInfo structure outside of encryptedData
has been deprecated and Visa intends to sunset it with the April,
2024 release, at which time it will no longer be available. Visa
advises clients to stop processing the deprecated field and
consume the token information data from the encryptedData
field as soon as possible before the April, 2024 release to avoid
backwards compatibility issues when the deprecated field is
sunset.
l Added the PSEUDO_ACCOUNT enum to the
originalTokenType field in the tokenInfo structure.

3.7 (23.04) April 2023 l Added autoFillIndicator field to Token Inquiry by PAN API
response and the Token Create notification. The
autoFillIndicator field was previously added to the
tokenInfo structure, which is shared across several APIs.
l The issuerAccountID field in client information is required for
Secure Remote Commerce (SRC).
l For India PROD, the host/domain name is https://
api.visa.co.in:443

3.7 (23.01) January 2023 l Added Token Requestor Report API.

l The Update Card Metadata behavior changed:

– If you update by PAN, using the encrypted account number or

the PAN's reference ID, the update will apply to all tokens
associated with the PAN.
– If you update using a combination of token requestor ID and
token reference ID, the update will apply to only the specified
token requestor and token combination.

6 June 2023 Visa Confidential 15

Visa Token Service – Issuer API Specifications (JSON)

Version Date Comments

Web
3.7 (22.10) November 2022 The following changes were made to the interface:

l The autoFillIndicator field was added to the tokenInfo

structure to indicate whether the token is for an autofill use case.
It is required for the Approve Provisioning, Approve Provisioning
Stand-In Notification, and Token Create Notification APIs.
The following changes were made to documentation:

l Added information about the asynchronous nature of outbound

calls from Visa.
l Added documentation about the Device Information structure to
the Approve Provisioning API request.
l Added information about PAN replacement to the PAN Lifecycle
API overview.

3.7 (22.09) September 2022 The following changes were made to the interface:

l The maximum size of a messageServiceURL field has been

expanded to 128 characters.
l A tokenRequestorName field has been added to the
tokenInfo structure. It is provided by Visa if available.
l In the clientWalletAccountID field, either the client or, in
some cases, Visa provides the value.
The following changes were made to documentation:

l Added domain/host name and Visa production source IP

addresses for India
l Identified cardholderVerificationList field in Token
Inquiry response.
l Removed cardholderVerificationList status values
except for PENDING.
l Renamed the Encrypted Payload Data chapter to Encrypted
Payload Data Structures; the encryptedData field of an API
identifies the structures that apply.
l Changed the updateReferenceID field name to
panReferenceID in the PAN Update Notification API's request
and example.
l Clarified that both the cardholderInfo and
replaceCardholderInfo structures are described by the
"Cardholder Info" table; replaceCardholderInfo does not
include device information.
l Updated the kinds of notifications that may include the
encryptedData field; notifications that do not exchange PII
data will not include the encryptedData field.

6 June 2023 Visa Confidential 16

Visa Token Service – Issuer API Specifications (JSON)

Version Date Comments

Web

l Updated the sample request for Approve Provisioning;

numberOfActiveTokensForPAN,
numberOfInactiveTokensForPAN, and
numberOfSuspendedTokensForPAN are fields that contain an
integer.
l For VCEH, changed the JWS header's alg field to be PS256 and
the JWE header's alg field to be A256GCMKW; also, changed the
example for Issuer to VCEH to match.

3.7 (22.06) June 2022 This release only affects the Visa Card Enrollment Hub (VCEH). The
following changes were made to the interface:

l An enhanced Push Card Enrollment to Wallet API is provided and

replaces prior versions of the API, which are deprecated.
The following changes were made to VCEH documentation:

l The Push Card Enrollment to Wallet API and Push Provisioning

Status Notification have been moved to the Visa Card Enrollment
Hub chapter, which replaces the VCEH Web Proxy chapter.
l Corrected the URLs in the VCEH proxy request.
l Added the alg and kid fields to the JWS and JWE headers for
the pushData request.
l Changed the issuerTraceID field to be required in the
provider structure.

3.7 (22.04) May 2022 The following changes were made to the interface:

l A tokenInfo structure has been added to the following API

requests: Device Token Binding Request, Get Cardholder Verifi­
cation Methods, Send Passcode, and Token Notification.
l A tokenRequestorName field has been added to the
tokenInfo structure. It is provided by Visa if available.
The following changes were made to documentation:

l Removed references to a client using the Visa Digital Configu­

ration System (VDCS) tool; VDCS configuration actions are
handled by a Visa representative.

3.7 (22.01) January 2022 The following changes were made to documentation:

l Added a cardMetaDataInfo structure to the CheckEligibility

API response.
l Updated the samples for the Update Card Metadata API sample
request and CheckEligibility API sample request and response.

3.7 (21.12) December 2021 The following changes were made to the interface:

l The cvv2 field in the Unencrypted Payment Instrument object

for the Push Card Enrollment to Wallet API has been deprecated.

6 June 2023 Visa Confidential 17

Visa Token Service – Issuer API Specifications (JSON)

Version Date Comments

Web

The following changes were made to documentation:

l Removed Trusted Listing API Specifications chapter.

l Added 05 (decline) action code to Token Notification from Visa.
l Added sandbox URL and revised live/production URL for VCEH
Proxy Request (pushCardEnrollment).
l Middle name in provider's client information is optional and not
required for Secure Remote Commerce or for issuer push token
provisioning across user or across device; however, it should be
provided if available.
l The descriptions for clientWalletAccountID, firstName,
middleName, lastName, issuerAccountID, and
clientDeviceID in provider's client information was revised;
these fields are not required for Secure Remote Commerce.
l The userPersonalID field has been removed from the
provider's client information.
l The clientWalletAccountID and clientDeviceID fields
have been removed from the provider information.
l Changed client information for contactEmail in VCEH to 48
characters.
l Changed provider information for isTsAndCsAccepted; it is
not required for Secure Remote Commerce.
l The passCodeConversationID, field has been removed from
the provider's client information passcode structure.
l Provided additional information about VCEH enrollment results
status.
l Added additional JWS fields to the VCEH results response.
l Changed example for iat in JWE Header within JWE Using RSA.
l Added Terms and Conditions structure to Token Create Notifi­
cation request.
l Revised sample request for Approve Provisioning Stand-In Notifi­
cation.
l Added clarification to optionality of Get Cardholder Verification
Methods response fields.

3.7 (21.10) August 2021 The following changes were made to the interface:

l Added originalTokenType field to the Token Information

structure used in API requests to Visa.
l Added originalDeviceID and originalDeviceType fields
to the Device Information structure

6 June 2023 Visa Confidential 18

Visa Token Service – Issuer API Specifications (JSON)

Version Date Comments

Web

The following changes were made to documentation:

l Added the following enums to stipReasonCode field in the

Approve Provisioning Stand-In Notification request from Visa:

– 9011— The line to issuer is down.

– 9012— Forced STIP because of N0 (Force STIP) original
response from issuer.
– 9203— Decline due to Office of Foreign Assets Control
(OFAC) embargo.
– 9206— Mod-10 check failure.
– 9208— Declined because issuing identifier and/or routing
identifier is blocked.
– 9210— Declined because of issuer participation options.
– 9212— Declined due to fraud condition.
l Revised LifeCycleTraceID description to indicate that the
field may not be available for Token notifications, such as when
the message reason code is TOKEN_DEVICE_BINDING_RESULT.
l Revised descriptions to indicate that asterisks are allowed in the
line1, line2, and city address fields, e.g. for
billingAddress.
l Revised description for clientWalletAccoutId in the Client
Information of the encrypted payment instrument payload for
the Push Card Enrollment to Wallet API and the pushData (VCEH
Web Proxy) API requests to remove the following requirement:
"When the wallet provider enrolls the PAN, the
clientWalletAccoutId field should have the same value."
l Added a "Used by" column to CardholderInfo Field Contents for
Update Operation Type table in the Lifecycle API.
l Provided additional codes (S and U) for the cvv2ResultsCode
field.

6 June 2023 Visa Confidential 19

Visa Token Service – Issuer API Specifications (JSON)

Version Date Comments

Web

3.6 (21.08) August 2021 l Added the following enums to deviceType field:

– PC
– HOUSEHOLD_DEVICE
– WEARABLE_DEVICE
– AUTOMOBILE_DEVICE
l The tokenAssuranceLevel and
originalTokenAssuranceLevel fields have been
deprecated. Use the respective tokenAssuranceMethod and
originalTokenAssuranceMethod fields instead. Possible
values are as follows:

– 00 ID&V Not Performed

– 10 Card Issuer Account Verification
– 11 Card Issuer Interactive Cardholder Verification - 1 Factor
– 12 Card Issuer Interactive Cardholder Verification - 2 Factor
– 13 Card Issuer Risk Oriented Non-Interactive Cardholder
Authentication
– 14 Card Issuer Asserted Authentication
l The actionCode is always provided by Visa in the .Approve
Provisioning Stand-In Notification.

3.6 (21.04) May 2021 This version is primarily a maintenance release:

l In the VCEH Web Proxy, whitespace and hyphens (-) are not
supported in postal codes.
l Added “Base64URL Encoding” section

3.6 (21.02) February 2021 Added VCEH Web Proxy.

3.6 (21.01) January 2021 This version is primarily a maintenance release.

3.6 (20.10) November 2020 This version is primarily a maintenance release.

3.6 (20.09) September 2020 This version is primarily a maintenance release.

3.6 (20.08) August 2020 This version is primarily a maintenance release.

3.6 (20.07) July 2020 Added the following Trusted Listing APIs:

l Get Trusted Listings

l Get Trustable Listings
l Add Trusted Listing
l Remove Trusted Listing
Added Token requestor — token service provider (TR-TSP) ID
(tokenRequestorTspID) field to the following APIs:

l Approve Provisioning
l Approve Provisioning Notification

6 June 2023 Visa Confidential 20

Visa Token Service – Issuer API Specifications (JSON)

Version Date Comments

Web

l Token Create Notification

l Token Notification
Added the PUSH_PROV_MOBILE option to the intent field in the
Payment Instrument Provider (provider) structure.
Added panSource to the response from the Token Inquiry API.
Added the following enumerations to panSource in containing
APIs:

l CHIP_DIP
l CONTACTLESS_TAP
Added additional operation types in Token Lifecycle API:

l TOKEN_DEVICE_BINDING_APPROVE_CALL_CENTER
l TOKEN_DEVICE_BINDING_APPROVE_BANK_APP
l CARDHOLDER_STEPUP_CALL_CENTER
l CARDHOLDER_STEPUP_APP_TO_APP
Updated Issuer Service IP addresses.

3.6 (20.06) June 2020 This version is primarily a maintenance release.

3.6 (20.04) April 2020 Added the PUSH_PROV_ONFILE option to the intent field in the
Payment Instrument Provider (provider) structure and support in
the Push Card Enrollment to Wallet API.

3.6 (20.03) March 2020 Updated PAN Lifecycle API to support Account Level Management
(ALM) capability.

3.5 October 2019 The following updates support Visa Card Enrollment Hub (VCEH):

l Added Push Card Enrollment to Wallet API.

l Added Push Provisioning Status Notification API.
l Added exp, iss and aud as optional fields, to the JWE header
under the Data Encryption/Signature section.
Incorporated the following additional updates:

l Updated the lifeCycleTraceID field type to Integer.

l Removed erroneous footnote from the Get Cardholder Verifi­
cation Methods Request section.
l Corrected links in Get Cardholder Verification Methods and Send
Passcode API request to go to Cardholder Information common
structure, instead of Card Metadata Information.

6 June 2023 Visa Confidential 21

Visa Token Service – Issuer API Specifications (JSON)

Version Date Comments

Web

3.4 September 2019 Added the lifeCycleTraceID field to the following APIs:

l Approve Provisioning
l Approve Provisioning Stand-In Notification
l Token Create Notification
l Token Notification
l Check Eligibility
l Get Cardholder Verification Methods
l Send Passcode
l Token Inquiry
l Token Inquiry by PAN
The following updates support Token for Token:

l Added the following fields to the Token Information common

structure:

– originalToken
– originalTokenRequestorID
– originalTokenReferenceID
– originalTokenAssuranceLevel
l Added a new enum value to the panSource field for the
following APIs:
– Approve Provisioning
– Approve Provisioning Stand-In Notification
– Token Create Notification

6 June 2023 Visa Confidential 22

Visa Token Service – Issuer API Specifications (JSON)

Version Date Comments

Web

3.3 July 2019 The following updates support Cloud Token Framework:

l Added the deviceIndex field to the Device Information

common structure.
l Added new Token User Information and Merchant Information
common structures.
l Token Notification API: Added token user information, merchant
information, and device information as new optional fields.
l Get Cardholder Verification Methods API: Added token user
information and merchant information as new optional fields.
Added new enum values to the otpReason field. Added a new
responseCode field to indicate a step up response from the
issuer.
l Send Passcode API: Added new enum values to the otpReason
field.
l Token Inquiry API: Added an optional query parameter and a new
optional array field.
l Token Lifecycle API: Added new enum values to the
operationType field.
l Added deviceBindingInfoList a new Device Token Binding
Request API.

3.2 May 2019 Added Retrieve Network Hub Push Provisioning (NHPP) Profiles API.

3.1 January 2019 Added Update Cardmetadata batch specification.

Updated PAN Lifecycle API to remove billing address.

3.0 December 2018 Initial version

6 June 2023 Visa Confidential 23

Chapter 1
Getting Started with REST APIs

Introduction
Provides information about Visa Token Service (VTS) endpoints and the HTTPS headers of VTS APIs,
along with a backward-compatibility assurance from Visa.

Backward Compatibility
Visa ensures that changes to APIs are backward-compatible, wherever possible. The goal of backward
compatibility is to ensure that an API change is seamless and will not interrupt its usage in the client
environment. Visa considers the following changes backward-compatible:
l Adding a new API resource.
l Adding a new optional request parameter to an existing API resource.
Note:  

6 June 2023 Visa Confidential 24

Visa Token Service – Issuer API Specifications (JSON)
Getting Started with REST APIs

As a guideline, add the parameter as part of the request body, as a URL parameter, or as an
HTTPS header field.
l Adding a new enumeration value.
Note:  
As a guideline, add the value either in the request or in the response.
l Adding a new response parameter to the API response.
l Changing the order in which parameters are returned in existing API responses.
l Changing the format of string identifiers.
Note:  
As a guideline, change the content as long as it is within the stipulated length of the string.
In simple terms, all these guidelines mean:
l You can add new optional parameters to existing APIs at any time.
l You should ignore any unknown fields or enumeration values received in API responses.
l You should limit string identifiers to length validation unless specific validations are
mentioned.

Endpoints
There are two publicly available endpoints, one is for the Sandbox and one is for Production. All the
REST APIs defined in this document use the relative path. The complete Uniform Resource Identifier
(URI) is a concatenation of the endpoint (defined below), and of the REST API path defined in the
individual API.

Outbound From Visa

All URIs must conform to the following scheme:

https://<host>:<port>/<uri path>

Endpoint Description

host Issuer Sandbox or Production host.

port Default TLS/SSL port 443.

uri path Refer to the relevant outbound API for this value.

6 June 2023 Visa Confidential 25

Visa Token Service – Issuer API Specifications (JSON)
Getting Started with REST APIs

Inbound to Visa
Refer to the relevant API documents for the API URL.

HTTPS Headers
This section describes HTTPS headers that are to be transmitted as part of API calls and returned as
part of API responses.

HTTPS Request Headers

Field Description

X-REQUEST-ID (Required) Unique ID for the API request.

Format: String; alphabetic, numeric, and hyphens ( - ), e.g. spaces are
not allowed; max length 36 characters.

Accept (Required) Content-Types that are acceptable for the response.

Example: application/json; charset=UTF-8
Format: String.

Content-Type (Conditional) The type of the request body. Not required if the
message body is empty in the request, for example, “GET”.
Example: application/json; charset=UTF-8
Format: String.

Accept-Language (Optional) List of acceptable languages for the response. Defaults to

en-US if not present.
Example: en-US
Format: String.

6 June 2023 Visa Confidential 26

Visa Token Service – Issuer API Specifications (JSON)
Getting Started with REST APIs

Field Description

Content-Language (Optional) The language of the request body. Defaults to en-US if not
present.
Example: en-US
Format: String.

x-pay-token (Required) A token identifying the transaction and its contents. The
token expires in 480 seconds (8 minutes) for all clients.
Example:

x-pay-token: xv2:1440199445:4a3...

which is concatenated as follows:

x-pay-token: xv2: + UTC_Timestamp + : + HMAC-
SHA256_hash(shared_secret, (UTC_Timestamp + resource_path +
query_string + request_body))
where:
shared_secret is the private key value associated with your API key,
which is available in your Visa Developer Center account, resource_path
is the API name / URI, query_string contains query parameters, such as
apiKey=key, and request_body is a JSON structure representing the
request without extra whitespace.
Format: Alphanumeric; 256 characters in the form of x-pay-token:
xv2:UTC_Timestamp:HMAC-SHA256_hash, where:

l UTC_Timestamp is a UNIX Epoch timestamp, in seconds

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

1. Timestamp from the transaction; exactly the same

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

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.

6 June 2023 Visa Confidential 27

Visa Token Service – Issuer API Specifications (JSON)
Getting Started with REST APIs

HTTP Response Headers

Field Description

X-RESPONSE-ID Unique ID for the API response. This is the same ID (X-REQUEST-ID)
that is sent in the API request header, which can be optionally sent
back in the response.
Format: String, max length 36 characters.

Content-Type The MIME type of the response body. Defaults to application/

json; charset=UTF-8 if not present.
Example: application/json; charset=UTF-8
Format: String.

Content-Language The language of the response body. Defaults to en-US if not present.
Example: en-US.
Format: String.

URL Parameters
Query Parameters
The query parameters are used as part of API invocations and are described in the corresponding
API.

API Key

Parameter Description

apiKey (Required) Client-specific API Key issued during onboarding. This value
is passed as a query parameter.
Format: String; alphabetic, numeric; max length 64 characters.

Error Handling

Error Handling
The VTS system reports API errors by using an Error Response structure. Logically, all the errors are
categorized into Standard errors and Business errors. Any API can return a Standard error; it should

6 June 2023 Visa Confidential 28

Visa Token Service – Issuer API Specifications (JSON)
Getting Started with REST APIs

be handled as you would normally handle an error. (See “Standard Errors”.) Some APIs return
Business errors; these are described in the “Error Responses” section of the corresponding API.
Guidelines for handling errors are as follows:
l Use HTTP status codes as defined in “Standard Errors” to determine the API response.
n If an API is successful, the response is 2xx.
n If an API has errors, the response is either 4xx or 5xx.
l The Error Response structure is optional and is returned in the event of errors along with the
details. In case an error response is not returned, rely on HTTP status codes.

Error Response Structure

The Error Response is returned in the event of an error.
Note:  
In some cases, depending on the type of error, this error structure may not be returned and you
should rely on the HTTP status code semantics.

Field Description

errorResponse (Conditional) Error response from the API that contains the error
details.
Format: An Error Response structure.

The Error Response structure is as follows:

l errorResponse.reason: Use the field to drive your error handling logic.
l errorResponse.message: Gives an error description. Refer to this field only to understand
the problem.

Error Response
Field Description

status HTTP status code.

Format: String; alphanumeric.

message Free-form text message describing the error condition.

Format: String; alphanumeric.

6 June 2023 Visa Confidential 29

Visa Token Service – Issuer API Specifications (JSON)
Getting Started with REST APIs

Field Description

reason Drives the error handling business logic for the API.
Format: String; alphanumeric.

details Array of fields that failed validation.

Format: An Error Details structure array.

Error Details
Field Description

location The value of this field is using the XPATH expression to point to the
field that failed validation.
Format: String; alphanumeric.

message Field-specific error message.

Format: String; alphanumeric.

Sample Error Response

{
"errorResponse":{
"status":400,
"message":"Input parameters validation failed.",
"reason":"invalidParameter",
"details":[
{
"location":"encryptedData",
"message":"Unable to decrypt."
}
]
}
}

Standard Errors
Standard errors can be returned by any API and should be handled consistently, in the same manner.
Standard Errors are not documented as part of each individual API description.

6 June 2023 Visa Confidential 30

Visa Token Service – Issuer API Specifications (JSON)
Getting Started with REST APIs

HTTP Code Reason Code Description

400 invalidParameter The value provided for one or more request parameters is considered
invalid.
Examples:

l Missing required field.

l The value exceeds the length specified for this field.
l Field formatting does not match the expected format.
The details.location field of the error response may contain a list of
fields that failed the data validation constraints.

400 invalidRequest The API server could not understand the request.
Usually, this means that the data format does not match the specification.
Examples:

l Base64URL decoding failed.

l The field is not in a particular format.
The message field may provide additional clarification of what part/field
of the request is considered incorrect.
(Refer to the relevant API Specification for the structure, format, and
constraints on the API request.)

401 Unauthorized Authentication credentials were missing or incorrect.

Not entitled to perform the operation.

404 Not Found The server has not found anything matching the Request URI.

500 serviceError Caused by a server error. In case of this error, the client can retry the
request again.

Selected Mappings of TAR ISO

Message Fields
Selected JSON fields are mapped to TAR 0100/0110 ISO messages:

JSON Field Token Activation Response Message Field

tokenRequestorID TLV 123, Usage 2, Dataset ID 68, Tag 03

tokenReferenceID TLV 123, Usage 2, Dataset ID 68, Tag 05

tokenRequestorTspID TLV 123, Tag 86

tokenType TLV 123, Usage 2, Dataset ID 68, Tag 07

lifeCycleTraceID 62.2

6 June 2023 Visa Confidential 31

Visa Token Service – Issuer API Specifications (JSON)
Getting Started with REST APIs

Base64URL Encoding
Base64URL encoding is identical to RFC 4648 Base64 encoding, except that the padding character is
"." and the other alphanumeric characters are "-" and "_" instead of "+" and "/". Spaces are not
allowed.

Outbound Notifications from Visa

APIs invoked by Visa, e.g. outbound messages, are asynchronous, meaning that they may be
delivered to an issuer at any time. While an outbound API may be invoked as a result of an inbound
API called by an issuer, their arrival is not synchronized with any call and could occur much later,
depending on Visa's system-wide load.

6 June 2023 Visa Confidential 32

Chapter 2
Onboarding

Introduction
Presents guidelines for onboarding a client (issuer) using web services.

Key Management
l The client will provide Visa with an X.509 certificate, containing its public encryption key,
through a secure out-of-band channel.
l Visa will provide the client with an X.509 certificate, containing its public signature key for
validation, through a secure out-of-band channel.

Client Configuration
l Client needs to set up WSI configuration and mutual SSL with Visa for outbound APIs.
l Client needs to follow Visa WSI onboarding procedures.

6 June 2023 Visa Confidential 33

Visa Token Service – Issuer API Specifications (JSON)
Onboarding

l A Visa representative will configure the endpoint for outbound (Visa to Client) web services
and the protocol (Web Service or ISO) to use the appropriate services.
l Client generates public/private key pairs and certificates for:
n Outbound encryption from Visa (self-signed X.509 certificate).
n Inbound signature to Visa (self-signed X.509 certificate).
l A Visa representative will provide the RSA keys/certificates for both, inbound and outbound
configurations for payload encryption and signature.
l A Visa representative will download Visa public certificates for encryption and signature
verification.
l Client will use the Visa Developer Portal (VDP) portal to get access to API credentials (in the
form of an API Key and a Shared Secret Key) to integrate with Visa to generate x-pay-
token, which is used during message authentication and must be passed as part of all web
service requests.

Connecting to Visa-Exposed Web

Services

Prerequisites
To use Visa-exposed services, issuers must:
l Fulfill the security requirements as documented in this specification.
l Call the web service method as described in this specification.

Security Requirements for Visa-Exposed Web

Services
The client must adhere to the security requirements described in this section when using Visa web
services.
l All messages to Visa must be sent through the approved transport channel with the required
authentication and authorization scheme for the type and format of the information which is
passed.
l For exchanging messages with Visa, all Service Consumers must use a TLS/SSL X.509 Visa-
approved Client Certificate linked to the identity supplied in the Authorization header.

6 June 2023 Visa Confidential 34

Visa Token Service – Issuer API Specifications (JSON)
Onboarding

Security Setup
Secure services can only be accessed by trusted Visa partners according to their contractual
obligations using predetermined access parameters. Issuer staff, working with their corresponding
Visa representatives, will receive the following during the on-boarding process:
l X-pay-token scheme—This is used during message authentication and must be passed as
part of all web service requests.
l Visa Root CA Certificate—This is used to establish TLS/SSL connectivity with Visa Web
Service Gateway. To establish TLS/SSL connectivity for the REST-based web service requests,
the consumer of the service requires a Visa root certificate to be installed in the keystore of
the client invoking the service.
The issuer performs the following tasks:
1. The issuer receives the Visa Certificate Authority (VICA3) intermediate and root certificates.
2. The issuer obtains client certificate from VICA3 for the generated CSR.
Note:  
The VICA3 root certificate is installed in the Visa Internet Gateway.

TLS/SSL Connectivity Process

1. The issuer-system sends the client certificate to Visa Internet gateway.
2. Visa Internet gateway validates the certificate and returns the server certificate to the issuer-
system.
3. The issuer validates the server certificate and TLS v1.2 is established.

Requirements
l TLS X.509 certificate—This will be issued by Visa and is verified against the credentials while
connecting to the web service. This certificate must be installed in the keystore of the client
invoking the service.
l Data Encryption—Sensitive fields in the message (if present) must be encrypted.
Note:  
When functionality does not require exchanging sensitive fields in full, such fields may be
passed in a masked form, such as adding asterisks in the middle of consumer’s email address,
thus eliminating the need for encryption. Payment Card Industry Data Security Standard (PCI
DSS) and other security guidelines and standards must be applied when determining the
method for obscuring the data.
l Firewall/Proxy Server Setup—The issuer must ensure that the internal firewall/proxy servers
have been updated to allow connectivity to the Visa environments if required by the issuer’s
security guidelines.

6 June 2023 Visa Confidential 35

Visa Token Service – Issuer API Specifications (JSON)
Onboarding

Connecting to Issuer-Exposed Web

Services

Security Requirements for Issuer-Exposed Web

Services
Server-side implementation must meet the following security requirements:
l Transport Security—All services must use TLS/SSL for exchanging messages with Visa.
l TLS/SSL X.509 Client Certificate—All services must use mutual SSL authentication. The
issuer must provide Visa with the instructions for generating a TLS/SSL X.509 client certificate
request. The use of established and recognized public Certificate Authority can be
considered.
l Visa performs the following tasks:
1. Visa generates the CSR and obtains client certificate from VICA3.
2. Visa shares VICA3 intermediate and root certificates with the issuers.
3. Visa provides the issuers with VICA3-generated server certificate.
l Firewall Rules—If required by the issuer security guidelines, the issuer must add Visa client
source IP address to the issuer’s firewall rules to allow the Visa client to connect to the issuer
service.
l Data Encryption—If sensitive fields are present in the message, they must be encrypted.
Note:  
When functionality does not require exchanging sensitive fields in full, such fields may be
passed in a masked form, such as adding asterisks in the middle of consumer’s email address,
thus eliminating the need for encryption. PCI DSS and other security guidelines and standards
must be applied when determining the method for obscuring the data.

6 June 2023 Visa Confidential 36

Visa Token Service – Issuer API Specifications (JSON)
Onboarding

Source and Destination Connectivity

Information Exchange
In order to establish connectivity between source and destination, the following information needs to
be exchanged to enable timely firewall/proxy server rules updates.
l Provide Visa with the URL and IP addresses and the port numbers for the services exposed by
the issuer, such as for Check Eligibility API, for each environment, namely, Integration Testing
and Production.
l Provide Visa with the instructions describing how to obtain client-side certificates for mutual
SSL authentication for each environment.
l All messages to Visa must be sent through the approved transport channel with the required
authentication and authorization scheme for the type and format of the information which is
passed.
l All Service Consumers must use TLS/SSL for exchanging messages with Visa.

Information Exchange
For integrating with Visa APIs, the issuer should use the following source/destination information
from Visa:

Visa Connecting to the Issuer Service

CTE Visa Source IP Address:

198.241.168.141
198.241.162.104
198.241.168.142

Production Visa Source IP Address:

198.241.168.142
198.241.150.66
198.241.168.141
103.144.116.26 (India only)
198.217.248.24 (India only)

The issuer should use the following format for naming the URL:
https://{host/domain:port}/{APP}/{version}/{API Name}?params=<>
The following is an example of a URI for various operations exposed by issuers, for example the
Check Eligibility API:

6 June 2023 Visa Confidential 37

Visa Token Service – Issuer API Specifications (JSON)
Onboarding

https://{host/domain:port}/vtis/v1/checkEligibility

Issuer Connecting to Visa

Visa format for URIs for all operations exposed by Visa will be:
https://{host}/vtis/{version}/{API Name}?params=<>
The following are examples of URIs for various operations exposed by Visa in the Sandbox
Environment, for example the Lifecycle support API:
Issuer—Token Inquiry URI
Note:  
For PROD, the host/domain name is https://api.visa.com:443
For India PROD, the host/domain name is https://api.visa.co.in:443
For Cert, the host/domain name is https://cert.api.visa.com:443/vtis/v1/
inquiry?apiKey=<>

6 June 2023 Visa Confidential 38

Chapter 3
Data Encryption and Decryption

Introduction
This chapter details encryption and decryption strategies that protect sensitive information passed in
API payloads.

Data Encryption/Signature
The payload fields submitted by Visa Token Service (VTS) issuers in the APIs contain sensitive
informationthat must be encrypted and signed using JWE (JSON Web Encryption) and JWS (JSON
Web Signature). A compact serialization scheme is followed for both JWE and JWS with Base64URL-
encoded elements separated by a "." (period).

6 June 2023 Visa Confidential 39

Visa Token Service – Issuer API Specifications (JSON)
Data Encryption and Decryption

JWE Using RSA

The general approach for encrypting data using JWE and RSA is as follows:
l Visa uses the compact serialization style, wherein elements are separated by a “.”(period).
l All fields are Base64URL-encoded.
l Visa uses the hybrid encryption scheme. In this method, an RSA 2048 key is used to encrypt a
random symmetric key. The random symmetric key is then used to encrypt the text.
l Use the RSA-OAEP-256 algorithm, encrypting the random symmetric key.
l Use the A256GCM algorithm for the encryption of text with an Initialization Vector (IV). Size
of IV should be 96 bits.
l Authentication Tag will be generated as an additional output of the A256GCM encryption.
Size of this field is 128 bits.
l JWE header is used to pass AAD (Additional Authentication Data) for the A256GCM
operation.
l All string-to-byte and byte-to-string conversions are done with UTF-8 charset.
Note:  
Refer to https://tools.ietf.org/html/draft-ietf-jose-json-web-encryption-40 for more details and
complete specifications on JWE.

JWE Composition
The following format shows the encrypted payload fields from a plaintext representation:
Base64URL (UTF8 (JWE Header)) || ‘.’ || Base64URL (JWE Encrypted Key) || ‘.’ || Base64URL (JWE
Initialization Vector) || ‘.’ || Base64URL (JWE Ciphertext) || ‘.’ || Base64URL (JWE Authentication Tag)

JWE Header
The JWE header contains the following metadata for encryption and decryption:

Name Description

alg (Required) Description of the algorithm used to encrypt the randomly

generated symmetric Content Encryption Key (CEK).
.Format: Value is RSA-OAEP-256.

kid (Required) Key identifier that identifies the key used to encrypt the
CEK, which is the Issuer’s API key.
Format: String; max length 64 characters.

6 June 2023 Visa Confidential 40

Visa Token Service – Issuer API Specifications (JSON)
Data Encryption and Decryption

typ (Required) Media type of the JWE. Javascript Object Signing and
Encryption (JOSE) indicates that JWE is using JWE Compact Seriali­
zation scheme.

Format: Value is JOSE.

enc (Required) Type of encryption used by the CEK to encrypt sensitive

payload elements.
Format: Value is A256GCM.

iat (Required) Time when JWE was issued. Expressed in UNIX epoch time
(seconds since 1 January, 1970) and issued at timestamp in UTC when
the transaction was created and signed.
Format: 1429837145.

exp (Optional) Expiration time of the payload. This field is optional and
should be evaluated in conjunction with the ttl default defined with
use case.
exp can be used to reduce the default ONLY. If exp represents a time
greater than iat + ttl then iat + ttl will be used.
Format: yyyy-MM-ddTHH:mm:ss.SSSZ.

iss (Conditional) Message originator client ID, which is the vClientID of

the issuer. The field is required for pushing card enrollment to wallet
providers. The message originator is the issuer.
Format: String; alphanumeric; max length 64 characters.

aud (Conditional) List of desired recipients, which are the token requestors’
vClientID values. This field is required for pushing card enrollment
to wallet providers. The recipients are token requestors. The value
should be a comma-separated array of client IDs. Up to 10 client IDs
are allowed for each request.
Format: String; alphanumeric; max length 256 characters.

JWE Header Sample

{
"alg":"RSA-OAEP-256",
"kid":"7ZEIVC16DGRDQKWZEE3X11LeJMDhyqQu8Q1ctnp4bylyQJCsw",
"typ":"JOSE",
"enc":"A256GCM",
"iat":"1429837145"
}

JWE Body Sample

"encrypted_key": "UghIOgu ... MR4gp_A=",

//base64 encoded form.
//CEK encrypted using A256GCM algorithm
"iv": "AxY8DctDa….GlsbGljb3RoZQ=",

6 June 2023 Visa Confidential 41

Visa Token Service – Issuer API Specifications (JSON)
Data Encryption and Decryption

//base64 encoded form.

//IV for the text encryption. Size of IV is to be 96 bit
"ciphertext": "KDlTthhZTGufMY….xPSUrfmqCHXaI9wOGY=",
//Base64 encoded form.
//Encrypted blob generated using the AES-GCM encryption(enc)
//of the text to encrypt.
"tag": "Mz-VPPyU4…RlcuYv1IwIvzw="
//base64 encoded form.
//HMAC generated using the AES-GCM encryption of the text to encrypt.

The size of the tag is to be 256 bits.

JWE Encrypted Key

The JWE Encrypted Key is a randomly generated Content Encryption Key (CEK) that is encrypted with
the receiver's public encryption key, by using the RSA-OAEP-256 algorithm.

JWE Initialization Vector

The JWE Initialization Vector (IV) is a randomly generated initialization vector (also known as salt) of
96 bits length.

JWE Ciphertext
JWE Ciphertext is an encrypted BLOB that is generated from the plaintext (sensitive data that needs
to be encrypted), by using the A256GCM encryption scheme specified in the enc header field.

JWE Authentication Tag

An HMAC (hash-based message authentication code) encryption of 128 bits is generated from the
plaintext authentication tag using the A256GCM algorithm (A256GCM).

General Steps for Data Encryption

Apply JWE on plaintext data and encrypt data by following these steps:
1. Get the RSA 2048 public key.
2. Generate a Random Symmetric Key (RSK) of 256 bits length.
3. Encrypt the RSK that is using the RSA 2048 key, by using the algorithm specified in alg (RSA-
OAEP-256).
4. Generate a random IV of 96 bits length and perform Base64URL encoding to produce E-IV.
5. Encrypt plaintext data, by using the RSK, Payload-IV, and the algorithm A256GCM specified in
the enc header field to form the ciphertext and the payload tag data.
6. Base64URL-encode the encrypted bytes to produce E-Ciphertext.

6 June 2023 Visa Confidential 42

Visa Token Service – Issuer API Specifications (JSON)
Data Encryption and Decryption

7. Base64URL-encode the Tag data to produce E-TAG.

8. Base64URL-encode the RSK to produce E-Encrypted Key.
9. Base64URL-encode the entire JWE header JSON containing the encryption parameters used
in clear text as shown below, to produce the JWE:

Encoded-HEADER|| ‘.’ || Base64URL (JWE Encrypted Key) || ‘.’ ||

Base64URL (JWE IV) || ‘.’ || Base64URL (JWE Ciphertext) || ‘.’ ||
Base64URL (JWE Authentication Tag).

JWS Using RSA

The general approach for generating a JWS payload that signs a JWE payload is as follows:
l Visa uses the compact serialization style, wherein elements are separated by a period (“.”).
l All fields are Base64URL-encoded.
l Use RSA-OAEP-256 algorithm (PS256 in terms of JWS algorithm notation) for signature.
All string-to-byte and byte-to-string conversions are done with the UTF-8 charset.

JWS Composition
The following format shows the encrypted payload fields from a plaintext representation:
Base64URL (UTF-8 (JWS Header)) || ‘.’ || Base64URL (JWS Payload) || ‘.’ || Base64URL (JWS Signature)

JWS Header
The JWE header contains the metadata for encryption and decryption.

Name Description

alg (Required) A description of the algorithm that is used to sign the JWS
payload.
Format: Value is PS256.

kid (Required) The key identifier that identifies the key used to sign the
JWS payload.
Format: String; max length 64 characters.

typ (Required) The media type of the JWS. JOSE indicates that the JWS is
using the JWS Compact Serialization scheme.
Format: Value is JOSE.

cty (Optional) The content type of the JWS payload.

Format: Value is JWE.

6 June 2023 Visa Confidential 43

Visa Token Service – Issuer API Specifications (JSON)
Data Encryption and Decryption

JWS Header Sample

{
"alg":"PS256",
"kid":"7ZEIVC16DGRDQKWZEE3X11LeJMDhyqQu8Q1ctnp4bylyQJCsw",
"typ":"JOSE",
"cty":"JWE"
}

JWS Signature Sample

“signature”: “rDxMelJ4y_EKQzxMus6oCS3WkyKb-2HqqZYgSyEP9VhDkUGNKEgeU7b3v
TeamL9voLttF__be44skxVbLOe3IorO3AmnO93O4evSMyXakABR6HorSXqZ8Izx1N8AzgwZ
Ot9HkVesH7tIR_IR69bFdDPCpG5qIe1EBEpodilSfs-LphbEPw”

JWS Payload
The JWS payload is the payload being signed.

JWS Signature
The JWS signature is generated to protect the integrity of both the JWS header and JWS payload.

Creating a Signature
To create a signature by applying JWS on JWE:

1. Get the RSA 2048 private key.

2. Sign the JWE (JWS payload) that is using the RSA 2048 private key by using the algorithm
specified in the alg header field (PS256).
3. JWS Signing Input: ASCII (Base64URL (UTF8 (JWS Header)) || ‘.’ ||
Base64URL (JWS Payload))
4. Package the header by using alg,kid,cty and typ params (as shown in the above
example for JWS).
5. Base64URL-encode the JWS signature to produce an E-Signature.
6. Base64URL-encode the JWE to produce E-JWS payload.
7. Base64URL-encode the entire JWS header JSON containing the encryption parameters.
8. Concatenate the above elements to produce the JWS:

Base64URL (UTF8 (JWS Header)) || ‘.’ || Base64URL (JWE) || ‘.’ ||

Base64URL (JWS Signature)

6 June 2023 Visa Confidential 44

Visa Token Service – Issuer API Specifications (JSON)
Data Encryption and Decryption

Signature Validation/Data Decryption

Sensitive payload fields submitted by VTS issuers through the APIs are encrypted and signed using
JWE (JSON Web Encryption) and JWS (JSON Web Signature).

Signature Validation
To validate a -Signature:
1. Get the RSA 2048 public key.
2. Base64URL decode the E-Header field.
3. Get the kid and the alg elements to use for signature validation.
4. Base64URL decode the E-Signature field to get the JWS signature.
5. Base64URL decode the E-JWS payload to get the JWS payload.
6. Validate the JWS signature against the JWS payload by using the RSA 2048 public key with
the encryption algorithm, as specified in alg element (PS256).

Data Decryption
To decrypt encrypted data:
1. Get the RSA 2048 private key.
2. Base64URL decode the E-Header field.
3. Get the kid and the algorithms to use for decryption.
4. Base64URL decode the E-Key field to get the encrypted E-key (Random Symmetric Key).
5. Decrypt the JWE Encrypted Key field by using the RSA 2048 private key with the encryption
algorithm, as specified in the alg element (RSA-OAEP-256).
6. Get the RSK in clear.
7. Base64URL decode the E-IV for use in ciphertext decryption.
8. Base64URL decode the E-Authentication Tag for use in ciphertext decryption.
9. Base64URL decode the ciphertext field.
10. Decrypt the ciphertext, by using RSK and IV and authentication tag and encryption
algorithm, as specified in the enc header field (A256GCM).

6 June 2023 Visa Confidential 45

Chapter 4
Encrypted Payload Data Structures

Cardholder Information
Field Description

primaryAccountNumber (Required) Primary account number (PAN) of the card that is being
tokenized.
Format: String; max length 19 characters.

cvv2 (Optional) Value associated with the PAN on the card.

Format: String; max length 4 characters.

name (Optional) Full name on the Visa card associated with the enrolled
payment instrument.
Format: String; max length 256 characters.

6 June 2023 Visa Confidential 46

Visa Token Service – Issuer API Specifications (JSON)
Encrypted Payload Data Structures

Field Description

expirationDate (Conditional) The expiration date of the payment instrument.

This is a required field for Secure Remote Commerce and in the
following APIs:

l Approve Provisioning
l Token Create Notification
Format: An Expiration Date structure.

billingAddress (Conditional) Billing address associated with the payment instrument. It

is required for Secure Remote Commerce.
Format: An Address structure.

highValueCustomer (Optional) If available, it will be provided in Check Eligibility.

Format: It is one of the following values:

l true— Indicates that the customer is high value.

l false— Indicates that the customer is not high value.

riskAssessmentScore (Optional) Advanced Authorization (AA) Risk Score is generated by

VisaNet on the last payment transaction for the PAN. Values are 0
through 99, with a higher value indicating higher risk. This value is
calculated by the AA Risk engine, based on the PAN’s transaction
pattern (long-term and short-term). If available, it will be provided in
Check Eligibility.
Format: String; max length 2 characters.

Address
This structure is used by several APIs.

Field Description

line1 (Optional) First line associated with the address.

Format: String; alphanumeric; UTF-8, white space, comma (,),
underscore (_), hashtag (#), colon (:), forward slash (/), period (.), single
quote (‘), asterisk (*), and hyphens (-) are allowed; max length 64
characters.

line2 (Optional) Second line associated with the address.

Format: String; alphanumeric; UTF-8, white space, comma (,),
underscore (_), hashtag (#), colon (:), forward slash (/), period (.), single
quote (‘), asterisk (*), and hyphens (-) are allowed; max length 64
characters.

6 June 2023 Visa Confidential 47

Visa Token Service – Issuer API Specifications (JSON)
Encrypted Payload Data Structures

Field Description

city (Optional) City associated with the address.

Format: String; alphanumeric; UTF-8, white space, carat (^), period (.),
single quote (‘), asterisk (*), and hyphens (-) are allowed; max length 32
characters.

state (Optional) State or province code associated with the address.

Example: NY
Format: String; ISO 3166-2; max length 2 characters.

postalCode (Optional) The postal code associated with the address.

Format: String; alphanumeric, valid for the country; whitespace and
hyphens (-) are allowed; max length 10 characters.

country (Optional) Code for a country; default is US.

Example: US
Format: String; ISO 3166-1 alpha-2; max length 2 characters.

Expiration Date
This structure is used by several APIs.

Field Description

month (Required) The month upon which the payment instrument is set to
expire.
Example: "month": "9"
Format: String; numeric; max length 2 digits.

year (Required) The year upon which the payment instrument is set to
expire.
Example: "year": "2024"
Format: String; numeric; length 4 digits.

6 June 2023 Visa Confidential 48

Visa Token Service – Issuer API Specifications (JSON)
Encrypted Payload Data Structures

Token Information
Field Description

token (Conditional) The account number associated with a token. This is a

required field in the following APIs:

l Token Create Notification

l Token Notification
Format: String; max length 19 characters.

tokenType (Conditional) This is a required field in the following APIs:

l Approve Provisioning
l Approve Provisioning Stand-In Notification
l Token Create Notification
Format: It is one of the following values:

l SECURE_ELEMENT
l HCE
l CARD_ON_FILE
l ECOMMERCE
l QRC

tokenStatus (Conditional) This is a required field in the following APIs:

l Token Create Notification

l Token Notification
Format: It is one of the following values:

l ACTIVE
l INACTIVE
l SUSPENDED
l DEACTIVATED

tokenExpirationDate (Conditional) The date upon which the token is set to expire. This field
is required in the Token Create Notification API.
Format: An Expiration Date structure.

6 June 2023 Visa Confidential 49

Visa Token Service – Issuer API Specifications (JSON)
Encrypted Payload Data Structures

Field Description

tokenAssuranceMethod (Optional) Method of Issuer ID&V that has taken place at time of
provisioning, device binding, or cardholder initiated verification. It is
one of the following values:

l 00 ID&V Not Performed

l 10 Card Issuer Account Verification
l 11 Card Issuer Interactive Cardholder Verification - 1 Factor
l 12 Card Issuer Interactive Cardholder Verification - 2 Factor
l 13 Card Issuer Risk Oriented Non-Interactive Cardholder Authenti­
cation
l 14 Card Issuer Asserted Authentication
Format: String; max length 2 characters.

numberOfActiveTokensForPAN (Optional) Number of device tokens that are currently active for this
PAN.
Format: Integer; max length 4 digits.

numberOfInactiveTokensForPAN (Optional) Number of device tokens that are currently inactive (device
tokens have not been activated) for this PAN.
Format: Integer; max length 4 digits.

numberOfSuspendedTokensForPAN (Optional) Number of device tokens that were activated, but are
suspended for payments for this PAN.
Format: Integer; max length 4 digits.

tokenActivationDate (Optional) System date/timestamp, in GMT, of token activation into an

active state. For an inactive state, this field is left empty and populated
only when a token transitions to an active state. If a token is
suspended, this field is populated with the new date/timestamp of
when an active state resumes.
Format: String; yyyy-MM-ddTHH:mm:ss.SSSZ.

tokenDeactivationDate (Optional) Date of token deactivation.

Format: String; YYYY-MM-DD.

lastTokenStatusUpdatedTime (Optional) Date/timestamp, in GMT, of the last token status update.

Format: String; yyyy-MM-ddTHH:mm:ss.SSSZ.

originalToken (Conditional) Token account number. This field is populated when

performing token-for-token provisioning only.
Format: String; max length 19 characters.

originalTokenRequestorID (Required) Unique ID assigned to the initiator of the token request. This
field is populated when performing token-for-token provisioning only.
Format: Numeric; max length 11 digits.

6 June 2023 Visa Confidential 50

Visa Token Service – Issuer API Specifications (JSON)
Encrypted Payload Data Structures

Field Description

originalTokenReferenceID (Conditional) Unique ID for the token associated with the PAN. This ID
can be used in lieu of the token for subsequent calls, such as life cycle
events. This field is populated when performing token-for-token
provisioning only.
Format: String; max length 32 characters.

originalTokenType (Conditional) Token type of the original token. This field is populated
only when performing token for token provisioning and can be used
only in the following APIs:

l Approve Provisioning
l Approve Provisioning Stand-In Notification
l Token Create Notification
Format: It is one of the following values:

l SECURE_ELEMENT
l HCE
l CARD_ON_FILE
l ECOMMERCE
l QRC
l PSEUDO_ACCOUNT

originaltokenAssuranceMethod (Conditional) Original token assurance method. This field is populated

when performing token-for-token provisioning only. It is one of the
following values:

l 00 ID&V Not Performed

l 10 Card Issuer Account Verification
l 11 Card Issuer Interactive Cardholder Verification - 1 Factor
l 12 Card Issuer Interactive Cardholder Verification - 2 Factor
l 13 Card Issuer Risk Oriented Non-Interactive Cardholder Authenti­
cation
l 14 Card Issuer Asserted Authentication
Format: String; max length 2 characters.

6 June 2023 Visa Confidential 51

Visa Token Service – Issuer API Specifications (JSON)
Encrypted Payload Data Structures

Field Description

tokenRequestorName (Conditional) Token requester name. Populated when available in the

following APIs:

l Device Token Binding Request

l Get Cardholder Verification Methods
l Send Passcode
l Token Notification
Format: String; max length 100 characters.

autoFillIndicator (Conditional) Indicates whether the token is for an autofill use case.
This is a required field in the following APIs:

l Approve Provisioning
l Approve Provisioning Stand-In Notification
l Token Create Notification
Format: It is one of the following values:

l true — Indicates that the token (e-Commerce Enabler, or Card-on-

File) is for an autofill use case.
l false — Indicates that the token is not for an autofill use case.

Risk Information
Field Description

walletProviderRiskAssessment Wallet provider risk assessment. If the DWP sends the value, Visa will
send it to the issuer.
Format: It is one of the following values:

l 0— Unconditionally approved.
l 1— Conditionally approved with further consumer verification.
l 2— Not approved

walletProviderRiskAssessment If the DWP sends this information, Visa will send it to the issuer. May
Version contain separators to indicate major and minor components, for
example, periods, hyphens, slashs, and other similar characters.
Format: String; max length 10 characters.

walletProviderAccountScore The wallet provider account score. Score value is between1 and 5,
indicating the confidence level of the account, where 5 indicates the
most confidence on the account.
Example: 5
Format: String; max length 2 characters.

6 June 2023 Visa Confidential 52

Visa Token Service – Issuer API Specifications (JSON)
Encrypted Payload Data Structures

Field Description

walletProviderDeviceScore The wallet provider device score. Score value is between1 and 5,
indicating the confidence level of the device, where5 indicates the
most confidence.
Example: 5
Format: String; max length 2 characters.

walletProviderReasonCodes Wallet provider reason codes, in a comma-separated format.

Format: String; max length 100 characters.

deviceBluetoothMac MAC address for Bluetooth.

Format: String; max length 24 characters.

deviceIMEI Hardware ID of the device.

Format: String; max length 24 characters.

deviceSerialNumber Serial number of the mobile device.

Format: String; max length 24 characters.

deviceTimeZone Time-zone abbreviation.

Example: PDT
Format: String; max length 5 characters.

deviceTimeZoneSetting Device time-zone setting.

Format: It is one of the following values:

l NETWORK_SET
l CONSUMER_SET

osID OS ID to allow building velocity and risk rules.

Format: String; max length 24 characters.

simSerialNumber SIM serial number of the mobile device.

Format: String; max length 24 characters.

deviceLostMode Number of days. Values are up to 9999 number of days.

Example: 9999
Format: String; max length 4 characters.

daysSinceConsumerDataLast Number of days since account settings were changed (in case of a
AccountChange password update). If the number of days exceeds 9999, it will stay at
9999.
Example: "9999"
Format: String; max length 4 characters.

accountHolderName Account-holder’s name.

Format: String; max length 64 characters.

6 June 2023 Visa Confidential 53

Visa Token Service – Issuer API Specifications (JSON)
Encrypted Payload Data Structures

Field Description

walletProviderPANAge Length of time (in days) that a PAN has been on file for a user.
Example: "9999"

Format: String; max length 4 characters.

walletAccountHolderCardNameMatch Name of the account-holder and name of cardholder matched.

Format: It is one of the following values:

l Y— Indicates the two names match.

l N— Indicates the two names do not match.

accountToDeviceBindingAge Number of days this device has been used by this account. If the
number of days exceeds 9999, it will stay at 9999.
Example: 9999
Format: String; max length 4 characters.

userAccountAge Number of days since an account for this user has existed (how long
have you known this user?).
Values are 0 through 9999.
Example: "9999"
Format: String; max length 4 characters.

walletAccountAge Number of days since the user created a wallet account or started
using a wallet. If the number of days exceeds 256, it will stay at 256.
Example: "256"
Format: String; max length 4 characters.

provisioningAttemptsOnDevice Number of provisioning attempts on this device in the past 24 hours. If

In24Hours the number of attempts exceeds 99, it will stay at 99.
Example: "99"
Format: String; max length 2 characters.

distinctCardholderNames Number of distinct cardholder names used in provisioning from this

device.
Example: "99"
Format: String; max length 2 characters.

deviceCountry Country of device at time of provisioning.

Example: US
Format: String; ISO 3166-1, alpha-2; max length 2 characters.

walletAccountCountry Country of account-holder.

Example: US
Format: String; ISO 3166-1, alpha-2; max length 2 characters.

6 June 2023 Visa Confidential 54

Visa Token Service – Issuer API Specifications (JSON)
Encrypted Payload Data Structures

Field Description

suspendedCardsInAccount Number of cards suspended in the account. If the number of days

exceeds 99, it will stay at 99.
Example: "99"
Format: String; max length 2 characters.

daysSinceLastAccountActivity Number of days since the last activity on account. If the number of
days exceeds 9999, it will stay at 9999.
Example: "9999"
Format: String; max length 4 characters.

numberOfTransactionsInLast Number of transactions on this account in the last 12 months. If the

12months number of transaction exceeds 9999, it will stay at 9999.
Example: "9999"
Format: String; max length 4 characters.

numberOfActiveTokens Number of active tokens on this account. If the number of tokens

exceeds 99, it will stay at 99
Example: "99"
Format: String; max length 2 characters.

deviceWithActiveTokens Number of devices for this user with the same token. If the number of
tokens exceeds 99, it will stay at 99
Example: "99"
Format: String; max length 2 characters.

activeTokensOnAllDeviceFor Number of active tokens for this user, across all devices. If the number
Account of tokens exceeds 9999, it will stay at 9999.
Example: "9999"
Format: String; max length 4 characters.

visaTokenScore Value indicating the degree of risk associated with the token. Numeric
value is 01 through 99.
Format: String; max length 2 characters.

visaTokenDecisioning Results from the token provisioning service.

Format: It is one of the following values:

l 00 – Provision and activate

l 05 – Do not provision
l 85 – Provision in inactive state (requires further consumer
authentication prior to activation)

6 June 2023 Visa Confidential 55

Visa Token Service – Issuer API Specifications (JSON)
Encrypted Payload Data Structures

Field Description

riskAssessmentScore Values are 0 through 99. A higher value indicates a higher risk. This is
calculated by the AA Risk Engine, based on the PAN’s transaction
pattern (long term and short term).
Format: String; max length 2 characters.

issuerSpecialConditionCodes Supported for issuers participating in 0100 TAR. The issuer can send
values for this element in the 0100 TAR response.

l If the issuer sends a value in the 0100 TAR, it will be sent in this
element of the Get CVM.
l If no value is sent in 0100 TAR or if the issuer does not participate in
TAR, this element will not be present.
Format: String; max length 100 characters.

Device Information
Field Description

deviceID For Secure Element (SE) wallet providers, this value will be the SE ID in
hex binary characters transformed to a 48-character string.
For Host Card Emulation (HCE) wallet providers, this field will be the
Device ID as determined by the digital wallet provider (DWP). All
alphanumeric and special characters are allowed for HCE DWPs.
Secure Element (SE) ID represents the device ID.

l For SE DWPs, this value will be the SE ID in hex binary characters

transformed to a 48-character string.
l For CBP DWPs, this field will be the device ID as determined by the
DWP. All alphanumeric and special characters are allowed for CBP
DWPs.
For Card-on-File (COF) wallets, this value will not be present.
For the initial Check Eligibility request on PAN enrollment, this value
may not be available, however Visa will send this value if it is available.
Format: String; max length 48 characters.

deviceLanguageCode This value is any ISO 639 Version 3 Language Code, for example, eng
(English). This language code will be used by the issuer and Visa to
retrieve the Terms and Conditions (T&C). If T&Cs are not found for the
Language Code in the request, the T&Cs will return the
default :anguage Code of eng (English).
Format: String; ISO-639 Version 3 Language Code, max length 3
characters.

6 June 2023 Visa Confidential 56

Visa Token Service – Issuer API Specifications (JSON)
Encrypted Payload Data Structures

Field Description

deviceType Device type.

Format: It is one of the following values:

l UNKNOWN
l MOBILE_PHONE
l TABLET
l WATCH
l MOBILEPHONE_OR_TABLET
l PC
l HOUSEHOLD_DEVICE
l WEARABLE_DEVICE
l AUTOMOBILE_DEVICE

deviceName A readable name for the device. Ideally, the customer enters this name.
It can be used to identify the device in customer support calls.
Example: My Work Phone
Format: String; Base64URL-encoded; UTF-8; max length 128
characters.

deviceNumber Device number.

Format: String; max length 13 characters.

osType Type of operating system.

Format: It is one of the following values:

l ANDROID
l IOS
l WINDOWS
l BLACKBERRY
l TIZEN
l OTHER

osVersion Version of the operating system running on the device.

Example: 4.4.4
Format: String; max length 32 characters.

osBuildID Operating system build identifier.

Example: KTU84M
Format: String; max length 32 characters.

6 June 2023 Visa Confidential 57

Visa Token Service – Issuer API Specifications (JSON)
Encrypted Payload Data Structures

Field Description

deviceIDType Attribute indicating the source of the Device ID value.

Example: The source for Device ID (deviceID) could be
SecureElement, TEE, or Derived
Format: String; max length 32 characters.

deviceManufacturer Manufacturer of the device.

Example: Samsung
Format: String; max length 32 characters.

deviceBrand Brand name of the device.

Example: Galaxy
Format: String; max length 32 characters.

deviceModel model of the device.

Example: SGH-T999
Format: String; max length 32 characters.

deviceLocation Obfuscated geographic location of the device. Initially, when

provisioned, this contains the general location of the device.
Information will be supplied with latitude/longitude rounded to the
nearest whole digit.
Example: +37/-121
Format: String; max length 25 characters.

deviceIndex The index number from Visa where the deviceID is stored. This is
required for token device binding.
Format: Integer; max length 2 digits.

deviceIPAddressV4 (Optional) The IP address of the device at the time of the provisioning
request, with the value represented in 255.255.255.255 format. An
octet (255) may be 1–3 digits in length but cannot contain any leading
zeros.
Format: String; max length 15 characters.

locationSource Source used to identify consumer location.

Format: It is one of the following values:

l WIFI
l CELLULAR
l GPS
l OTHER

6 June 2023 Visa Confidential 58

Visa Token Service – Issuer API Specifications (JSON)
Encrypted Payload Data Structures

Field Description

tokenProtectionMethod Method of token protection.

Format: It is one of the following values:

l SOFTWARE
l TRUSTED_EXECUTION_ENVIRONMENT
l SECURE_ELEMENT
l CLOUD

originalDeviceID Device ID from the original provision. This field is populated only when
performing token-for-token provisioning and can be used only in the
following APIs:

l Approve Provisioning
l Approve Provisioning Stand-In Notification
l Token Create Notification
Format: String; max length 48 characters.

originalDeviceType Device type from the original provision. This field is populated only
when performing token-for-token provisioning and can be used only
in the following APIs:

l Approve Provisioning
l Approve Provisioning Stand-In Notification
l Token Create Notification
Format: It is one of the following values:

l UNKNOWN
l MOBILE_PHONE
l TABLET
l WATCH
l MOBILEPHONE_OR_TABLET
l PC
l HOUSEHOLD_DEVICE
l WEARABLE_DEVICE
l AUTOMOBILE_DEVICE

6 June 2023 Visa Confidential 59

Chapter 5
Inbound API Specifications (To
Visa)

PAN Lifecycle
This service enables the issuer to update PAN and PAN expiration date. It also helps perform VAU
updates, enroll a PAN in Registered Program Identification Number (RPIN) and link relationships.

Lifecycle Operations
The following table shows the various lifecycle operations and the corresponding fields that need to
be passed in order to achieve a particular operation.

6 June 2023 Visa Confidential 60

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

CardholderInfo Field Contents for Update Operation Type

Lifecycle Operation Old PAN Old PAN New New Used by

Value Expiry PAN PAN
Op Reason Code Field
(pan) Date (pan2) Expiry
(expdt) Date
(expdt2)

PAN Update With Expiry Date PAN 1 PAN 1 PAN 2 PAN 2 Token/VAU
Expiry Expiry
ACCOUNT_UPDATE

PAN Update (Reversal) PAN 1 N/A N/A N/A Token/VAU

ACCOUNT_UPDATE

PAN Expiry Date Update PAN 1 PAN 1 Old PAN 1 PAN 1 Token/VAU
Expiry New
EXP_DATE_UPDATE
Expiry

Close Account PAN 1 N/A N/A N/A Token/VAU

ACCOUNT_CLOSED

Contact Cardholder PAN 1 N/A N/A N/A VAU

CONTACT_CARDHOLDER

Portfolio Conversion PAN 1 N/A PAN 2 PAN 2 VAU

Expiry
PORTFOLIO_CONVERSION

PAN RPIN Enrollment N/A N/A PAN 1 N/A ALM

UPDATE_ACCOUNT_LEVEL_RECORD

PAN Link Enrollment N/A N/A PAN 1 N/A ALM

UPDATE_ACCOUNT_LEVEL_RECORD

PAN Replace Enrollment N/A N/A PAN 2 N/A ALM

UPDATE_ACCOUNT_LEVEL_RECORD

Note:  
l In the table above, the Operation Type field is always UPDATE.
l For a PAN Update (Reversal), the Operation Reason Code field contains ACCOUNT
UPDATE and the Operation Type field is DELETE; other field values ae not applicable.
l If an issuer is not enabled for VAU, ACCOUNT UPDATE, and EXP_DATE UPDATE, they
will function as a BAU token PAN update and no VAU system will be updated.
l Operation type field is required for the above functions but if not provided, the default
behavior is Update all systems based on issuer participation.

6 June 2023 Visa Confidential 61

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

PAN Replacement
If you are replacing an existing PAN with another one and there are tokens associated with the
existing PAN, the new PAN must have the same BIN as the replacement PAN. If the BINs are different
between the existing PAN and the replacement PAN, you must delete the tokens on the existing PAN
before calling the PAN Lifecycle API to replace the PAN.
Note:  You must allow between 1 and 5 minutes from the time you delete the tokens for the
existing PAN before you call the PAN Lifecycle API to replace the PAN.
The issuer can then use push provisioning APIs to add new tokens to the replacement PAN on the
cardholder's device. To provision tokens on the replacement PAN, the issuer must have enabled App-
to-App push provisioning and the cardholder must have the issuer's mobile banking app installed on
their device.
The issuer can allow merchant-initiated transactions prior to the cardholder acknowledging receipt of
a physical card. The cardholder can use the digital card from their mobile app before receiving a
physical card.

Card/Credential-on-File or eCommerce Considerations

You must handle replacements of Card/Credential-on-File or eCommerce tokens in one of the
following ways:
l Use Visa Card Enrollment Hub (VCEH) to handle push provisioning
l Delete these tokens and instruct the cardholder to enroll the replacement PAN with
merchants themselves.
For further information, contact your Visa representative.

Request

Endpoints

Path:

{Visa host}/vtis/v1/pan/lifecycle?apiKey=key

Method
POST

6 June 2023 Visa Confidential 62

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Query Parameters

API Key

Parameter Description

apiKey (Required) Client-specific API Key issued during onboarding. This value
is passed as a query parameter.
Format: String; alphabetic, numeric; max length 64 characters.

Request Body

Field Description

operatorID (Optional) Operator ID of either person or system performing the

operation.
Format: String; max length 16 characters.

operationType (Required) Type of operation.

Format: It is one of the following values:

l UPDATE
l DELETE

operationReason (Required) Reason for the operation. The reason should be descriptive,
such that if the issuer performs an action and the consumer calls
Customer Support, the support team should be able to read the
reason, advise the consumer, and act accordingly. For example, if the
PAN is replaced, the request reason might say “Replacement due to
lost card”.
Format: String; max length 254 characters.

6 June 2023 Visa Confidential 63

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Field Description

operationReasonCode (Required) A reason code for the operation. If the reason code is
ACCOUNT_UPDATE or PORTFOLIO_CONVERSION (updating PAN only
or PAN & Expiry date), the old PAN and replacement PAN cannot be
the same. If the reason code is EXP_DATE_UPDATE (expiry date
update only), the old PAN and replacement PAN values must be the
same. If the reason code is UPDATE_ACCOUNT_LEVEL_RECORD, the
account level information in the encrypted data needs to be provided.
Format: It is one of the following values:

l ACCOUNT_UPDATE— Account number change or Account number

and Expiry date change.
l ACCOUNT_CLOSED— Closed account advice.
l EXP_DATE_UPDATE— Expiration date change.
l CONTACT_CARDHOLDER— Contact cardholder advice. Query
account.
l PORTFOLIO_CONVERSION
l UPDATE_ACCOUNT_LEVEL_RECORD

updateReferenceID (Conditional) Reference ID that is needed to track all account level

updates. This field is required if the operation reason code is
UPDATE_ACCOUNT_LEVEL_RECORD.
Format: String; max length 32 characters.

encryptedData (Required) Blob field that contains the encrypted payload; see the
“Unencrypted Payload” section for more information.

Note:  For PAN update/replacement, the new and the PAN to

be changed must share the same 9-digit account range; the new
PAN should not have any tokens already associated with it. See
Cardholder Information.

l cardholderInfo

– Current PAN
– Expiration Date
l replaceCardholderInfo

– New PAN
– New Expiration Date
l accountLevelInfo

– Account-level enrollment information

Format: String; max length 7000 characters.

6 June 2023 Visa Confidential 64

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Unencrypted Payload

Field Description

cardholderInfo Cardholder information, which includes the following fields:

l primaryAccountNumber–Current PAN
l expirationDate–Current expiration date
Format: A cardholder info structure.

replaceCardholderInfo Replacement cardholder information, which includes the following

fields:

l primaryAccountNumber–New PAN
l expirationDate–New expiration date
Format: A cardholder info structure.

accountLevelInfo Account level information.

Format: An account level info structure.

Cardholder Info
The following table describes both the cardholderInfo and replaceCardholderInfo
structures:

Field Description

primaryAccountNumber (Required) Primary account number (PAN).

Format: String; max length 19 characters.

expirationDate (Required) The expiration date of the payment instrument.

Format: An Expiration Date structure.

Expiration Date
This structure is used by several APIs.

Field Description

month (Required) The month upon which the payment instrument is set to
expire.
Example: "month": "9"
Format: String; numeric; max length 2 digits.

year (Required) The year upon which the payment instrument is set to
expire.
Example: "year": "2024"
Format: String; numeric; length 4 digits.

6 June 2023 Visa Confidential 65

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Account-Level Enrollment Information

Field Description

productID (Conditional) This is the product ID for the card number in the Account
Number field. It is required, when the rpinEnrollment structure is
provided in the request, or when the linkEnrollment structure is
present for either the USHNW or VIRTUAL groupType. For example if
the product type of the card is ‘Visa Traditional Credit’, the value of
productID is A.
Format: String; max 2 characters.

rpinEnrollment (Optional) Contains information to enroll the account number in a

given Registered Program Identification Number (RPIN). This field is
not required when sending request only for linking or replacement. If
the account number has customerContactInfo accompanying it,
then it must be sent with rpinEnrollment to avoid deletion.
Format: A RPIN Enrollment Information Structure.

customerContactInfo (Optional) Contains account-number-specific information such as

name and address. If not provided, this will result in deletion of any
existing customerContactInfo for the account number in the
system. It is only accepted for certain Visa Product IDs but ignored for
all other product IDs. When specified, it must have the accompanying
rpinEnrollment structure in its entirety.
Format: A Customer Contact Information structure.

replaceEnrollment (Optional) Contains information about card replacement for the

account number. This information can be sent independently of other
structures such as rpinEnrollment or linkEnrollment.
Format: A Replace Enrollment Information structure.

linkEnrollment (Conditional) Contains linking information for the account number. Link
enrollment information is not required when sending request only for
RPIN enrollment or replace Enrollment.
Format: A Link Enrollment Information structure.

6 June 2023 Visa Confidential 66

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

RPIN Enrollment Information

Field Description

action (Required) Action for RPIN Enrollment.

Format: It is one of the following values:

l Add— Use Add when submitting new card numbers; record is for a
new account number. All required fields must be provided.
l Change— Use if changing any attribute in rpinEnrollment data.
A change record will fully replace all data in the original record.
Every required field must be submitted in a change record. If issuers
wish to preserve previously submitted optional data, this data must
be resubmitted.
l Delete— Use if removing an account number. For delete records,
all other fields are optional.

accountOpenDate (Required) The date the account number was first opened with the
issuer.
Format: String in the form of YYYYMMDD.

rpin (Required) The six-digit Visa-provided Registered Program Identifi­

cation Number (RPIN) in which this account is enrolled. The RPIN’s
product ID in the Visa system must match the product ID provided in
the web service call.
Format: String; numeric; max length 6 characters.

rpinEffectiveDate (Optional) The RPIN effective date, which can be a past or future date,
but it must be a date that is after the RPIN create-date and before the
RPIN end-date. If the date does not follow these rules, the request is
rejected with an Invalid Date reject reason. It will default to the current
date if the correct date is not provided.
Format: String; YYYYMMDD.

Customer Contact Information

Field Description

action (Required) If an action other than Add is selected, the webservice call
will be rejected.
Format: It is one of the following values:

l Add— Use this to add new customer information. All required fields
must be provided.

address (Optional) Address details for the account holder.

Format: An Address structure.

namePrefix (Optional) Account holder’s name prefix.

Format: String; max length 5 characters.

6 June 2023 Visa Confidential 67

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Field Description

firstName (Required) Account holder’s first name.

Format: String; max length 15 characters.

middleInitial (Optional) Account holder’s middle initial.

Format: String; max length 1 characters.

lastName (Required) Account holder’s last name.

Format: String; max length 25 characters.

nameSuffix (Optional) Account holder’s name suffix.

Format: String; max length 5 characters.

prefMethodOfContact (Optional) Account holder’s preferred method of contact; if a space or

an empty string is specified, the preferred method of contact is ‘no
preference’.
Format: It is one of the following values:

l M— Physical mail.
l E— E mail.
l C— Mobile telephone.

email (Conditional) Account holder’s email address. Required when

prefMethodOfContact is E.
Format: String; max length 100 characters.

mobileNumber (Conditional) Account holder’s telephone number. Required when

prefMethodOfContact is C.
Format: String; max length 10 characters.

Address

Field Description

line1 (Required) First line associated with the account holder’s address.
Format: String; alphanumeric; UTF-8, white space, comma (,),
underscore (_), hashtag (#), colon (:), forward slash (/), period (.), single
quote (‘), asterisk (*), and hyphen (-) are allowed; max length 40
characters.

line2 (Optional) Second line associated with the account holder’s address.
Format: String; alphanumeric; UTF-8, white space, comma (,),
underscore (_), hashtag (#), colon (:), forward slash (/), period (.), single
quote (‘), asterisk (*), and hyphen (-) are allowed; max length 40
characters.

6 June 2023 Visa Confidential 68

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Field Description

companyName (Conditional) Account holder’s company name.

Format: String; alphanumeric; UTF-8, white space, comma (,),
underscore (_), hashtag (#), colon (:), forward slash (/), period (.), single
quote (‘), and hyphens (-) are allowed; max length 40 characters.

city (Required) City associated with the account holder’s address.

Format: String; alphanumeric; UTF-8, white space, carat (^), period (.),
single quote (‘), asterisk (*), and hyphen (-) are allowed; max length 30
characters.

state (Conditional) State or province code associated with the account

holder’s address. Required for the US, but can be left blank for a non-
US address.
Example: NY
Format: String; ISO 3166-2; max length 2 characters.

zip (Conditional) Account holder’s zipcode. Required for the US, but can
be left blank for a non-US address.
Format: String; numeric; max 5 characters.

Replace Enrollment Information

Field Description

oldAccountNumber (Required) A valid account number specifying the card is being

replaced by the card number in the Account Number field.
Format: String; max length 19 characters.

linkReasonCode (Conditional) The reason for replacement.

Format: It is one of the following values:

l L— Lost: Consumer reports the card has been lost.

l S— Stolen: Consumer reports the card has been stolen.
l U— Upgrade/Downgrade: Consumer has been issued a new
product.
l O— Other: Used when no other value applies.
l C— Converted
l R— Reissued
l N— Not known

unlinkIndicator (Conditional) Unlink indicator. This must be set to Y when deleting a

replacement relationship.
Format: It is one of the following values:

l Y— User is trying to unlink the account number

6 June 2023 Visa Confidential 69

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Link Enrollment Information

Field Description

group Group.
Format: An array of groupType structures.

Group

Field Description

action (Required) Action taken on the record for an enrollment link.

Format: It is one of the following values:

l Add— Record is for a new link.

l Delete— Record is for removing a link.
l Change— Can only be used to change the Primary Account flag.

groupType (Required) Group type.

Format: It is one of the following values:

l LOC— Groups a primary card account with authorized accounts

from other cardholders.
l CUSTOMER— Groups a set of card accounts for the same
cardholder.
l VIP1— A value representing the priority of treatment applied to
the given primary account number.
l VIRTUAL— Groups a primary card account with a set of virtual
cards.

Note:  A value for productID must be specified. Contact

your Visa representative before submitting a request using
the VIRTUAL Group Type.
l ISEGMENT— Issuer’s specific Customer Segment applied to the
given primary account number. Issuers supporting multiple group
types must submit an array of Group information..
l USHNW

Note:  A value for productID must be specified.

A variety of customized Group Types may be available, depending on
region, issuer, or other criteria. Additional Group Types and values for
those Group Types may be required, depending on region, issuer, or
other criteria. For information on these Group Types, see their
respective Product Implementation Guides. Issuers should consult the
respective Product Implementation Guides for details on how to
submit primary/supplementary flags to generate accurate billing
information for those related products with associated card fees. For
more information, contact your Visa representative.

6 June 2023 Visa Confidential 70

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Field Description

groupID (Required) Contains the issuer-supplied identifier for the group type
specified in the Group Type field. Must not be PAI/PII data.
Format: String; alphabetic, numeric, hyphens ( - ), and underscores
( _) [a-zA-Z0-9-_ ]; max 32 characters.

isPrimaryAccount (Conditional) Whether the account the account number is to be the

primary account number in the group.. Used for group types that have
a primary or owner account. It is required when groupType is LOC, or
VIRTUAL. It should be set to Y for Primary (physical plastic card).
Issuers should refer to the Product Implementation Guide for
requirements related to custom group types.
Format: It is one of the following values:

l Y— The account number is to be the primary account number in

the group.
l N—The account number is not the primary account number.

Response

Successful Response
No response body, if available, will contain the error response of the API as described in this
specification.

Error Response
If a business error is present, it is assumed that no “Standard Errors” were detected in the API
request.
VTS domain-specific business error reason codes are as follows:

HTTP Status Error Code Error Code Description

400 VSE40001 VSE_ERROR_REQUIRED_DATA_MISSING

400 VSE40000 VSE_ERROR_INVALID_DATA

400 VSE40006 VSE_ERROR_INVALID_REPLACEMENT_PAN

400 VSE40010 VSE_ERROR_CRYPTOGRAPHY_ERROR

500 VSE40009 VSE_INTERNAL_SYSTEM_ERROR

6 June 2023 Visa Confidential 71

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Sample Payloads

Sample Request

{
“operatorID”: “Operator1”,
“operationReason”: “Replacement due to lost card”,
“operationReasonCode”: “ACCOUNT_UPDATE”,
“operationType”: “UPDATE”,
“encryptedData”: “<JWS>”
}

All JWS and JWE elements are Base64URL-encoded. JWS:

<JWS Header>.<JWS Payload>.<JWS Signature>
JWS Payload:
<JWE>
JWE:

<Header>.<Encrypted Key>.<InitializationVector>.<Ciphertext>.
<Authentication Tag>

Unencrypted data contained in JWE ciphertext element:

{
“cardholderInfo”:{
“primaryAccountNumber”: “...”,
“expirationDate”: {
“month”: “...”,
“year”: “...”
}
},
“replaceCardholderInfo”: {
“primaryAccountNumber”: “...”,
“expirationDate”: {
“month”: “...”,
“year”: “...”
}
}
}
},
“accountLevelInfo”: {
“productID”: “...”,
“rpinEnrollment”: {
“action”: “...”,
“accountOpenDate”: “...”,
“rpin”: “...”,
“rpinEffectiveDate”: “...”

6 June 2023 Visa Confidential 72

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

},
“customerContactInfo”: {
“accountLevelActionType”: “...”,
“address”: {
“line1”: “...”,
“line2”: “...”,
“companyName”: “...”,
“city”: “...”,
“zip”: “...”
},
“namePrefix”: “...”,
“firstName”: “...”,
“middleInitial”: “...”,
“lastName”: “...”,
“nameSuffix”: “”,
“prefMethodOfContact”: “...”,
“email”: “...”,
“mobileNumber”: “...”
},
“replaceEnrollment”: {
“oldAccountNumber”: “...”,
“linkReasonCode”: “...”,
“unlinkIndicator”: “...”
},
“linkEnrollment”: {
“Group”: [
{
“action”: “...”,
“groupType”: “...”,
“groupID”: “...”,
“isPrimaryAccount”: “...”
},
{
“action”: “...”,
“groupType”: “...”,
“groupID”: “”,
“isPrimaryAccount”: “...”
}
]
}
}
}

Token Inquiry
This service enables the issuer to retrieve token details for a particular token, including device and
risk information.

Request

6 June 2023 Visa Confidential 73

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Endpoints

Path:

{Visa host}/vtis/v1/tokenRequestors/{tokenRequestorID}/tokens/
{tokenReferenceID}/details?apiKey=key
[&cardHolderVerificationRetrieve=true|false]
[&deviceBindingInfo=true|false]

URL Parameters:

Parameter Description

{tokenRequestorID} (Required) Unique ID assigned to the initiator of the token request.

Format: Numeric; max length 11 digits.

{tokenReferenceID} (Required) Unique ID for the token associated with the PAN. This ID can
be used in lieu of the token for subsequent calls, such as lifecycle
events.
Format: String; max length 32 characters.

Method
GET

6 June 2023 Visa Confidential 74

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Query Parameters

Parameter Description

apiKey (Required) Client-specific API Key issued during onboarding.

Format: String; alphabetic, numeric; max length 64 characters.

cardHolderVerificationRetrieve (Optional) Whether cardholderVerificationList needs to be

provided in the response, which enables issuers to query the status of
token requestor-initiated cardholder verification requests for this
token.

Note:  A cardholderVerificationList will only be

returned if the list’s status is PENDING.
Format: It is one of the following values:

l true
l false (default)

deviceBindingInfo (Optional) Whether deviceBindingInfoList needs to be provided

in the response.
Format: It is one of the following values:

l true
l false (default)

Token Inquiry Response

Field Description

encryptedData Blob field that contains the encrypted payload; see the “Decrypted
Payload” section for more information.
Format: String; max length 7000 characters.

panReferenceID Unique ID for the PAN.

Can be used in lieu of PAN for subsequent calls, such as lifecycle
events.
Format: String; max length 32 characters.

operatorID Operator ID of either the person or the system that performed the last
status update.
Format: String; max length 16 characters.

6 June 2023 Visa Confidential 75

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Field Description

entityOfLastAction Entity of the last action.

Format: It is one of the following values:

l TOKEN_REQUESTOR
l ISSUER
For example, only the actor which suspended the token can change
the status back to Activate.

walletAccountEmailAddressHash Hash of email address linked to their wallet account login.

Format: String; max length 64 characters.

clientWalletAccountID Consumer ID identifying the wallet account-holder entity. Provided by

the client.
Format: String; max length 32 characters.

panSource Source of PAN.

Format: It is one of the following values:

l KEY_ENTERED
l ON_FILE
l MOBILE_BANKING_APP
l TOKEN
l CHIP_DIP
l CONTACTLESS_TAP

consumerEntryMode The method of consumer entry.

Format: It is one of the following values:

l KEY_ENTERED
l CAMERA_CAPTURED
l UNKNOWN

cardMetadataProfileID Profile ID associated with the card.

Format: String; max length 32 characters

lastFourOfPAN Last four digits of the current PAN for the token.
Format: Numeric; max length 4 digits.

lastFourOfPreviousPAN Last four digits of the previous PAN for the token. If a card has been
replaced while the token was in an active state, this represents the
previous PAN with which the token was associated.
Format: Numeric; max length 4 digits.

otpInfo OPT information.

Format: An OTP info structure.

6 June 2023 Visa Confidential 76

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Field Description

issuerDiscretionaryData Issuer discretionary data.

Format: An issuer discretionary data structure.

cardholderVerificationList Cardholder verification list. Provided only if the

cardHolderVerificationRetrieve query parameter is set to
true and the list's status field is PENDING.
Format: A cardholderVerificationList structure.

deviceBindingInfoList Returns a list of device bindings. Only device index and device ID are
populated in device information.
Format: An array of device binding information.

OTP Information

Field Description

otpCodeIndicator OTP state indicator.

Format: It is one of the following values:

l PRESENT
l NOT_PRESENT
l EXPIRED

otpCodeExpiration OTP expiration date and time in GMT.

Format: String; yyyy-MM-ddTHH:mm:ss.SSSZ

otpVerificationAttempts OTP verification attempts.

Format: Numeric; max 3 digits

otpVerificationRetryCounts OTP verification retry count.

Format: Numeric; max 3 digits

6 June 2023 Visa Confidential 77

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Discretionary Data Information

Field Description

fileControlInformation File control information, which is the FCI IDD tag BF0C in hexadecimal
128 bytes length transformed to a 256-character string that can be
displayed. For example, a 1-hex byte is represented as 2-character
values where each 4-bit nibble represents a character.

Note:  An issuer-provided FCI IDD overrides tag BF0C data

(and subfields) in the Visa perso scripts.
Format: hexBinary, hex characters must be uppercase; max length of
128 bytes.

issuerApplication Discretionary data, which is the IAD IDD tag 9F10 in hexadecimal 15
DiscretionaryData bytes fixed length (transformed to a 30–character string that can be
displayed). The
9F10 – IAD IDD Format (1 byte) and IDD Data (14 bytes):

l IDD format—Support only x’00’.

l IDD data—Fixed length of 14 bytes padded.
For example, a 1-hex byte is represented as 2-character values where
each 4-bit nibble represents a character.

Note:  An issuer-provided IAD IDD would override tag 9F10

data in the Visa perso scripts.
Format: hexBinary, hex characters must be uppercase; max length of
15 bytes.

Note:  
The hexBinary format represents each single 8-bit byte of binary data as two 8-bit characters
in string format.
Example:
A decimal value of 267 = binary b’0000000100001011’ = hex value of x’010B’ (2 bytes)
= hexBinary value of ’010B’ (4 byte string). Only hexadecimal numeric digits, 0–9 and
uppercase letters, A–F are allowed in this canonical representation of hexBinary format. Since
each binary byte is expressed as a character tuple, consisting of 2 hexadecimal digits, a
hexBinary format encoded field must always be expressed in an even number of hexadecimal
digits.

6 June 2023 Visa Confidential 78

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Cardholder Verification List

Parameter Description

lifeCycleTraceID A message identifier that can be used to link some messages

associated with a provisioning request. This should be used by the
issuer in event/message logging.
Format: Integer; max length 15 digits.

status
Format: It is one of the following values:

l PENDING

timestamp Timestamp.
Format: UNIX Epoch timestamp, in seconds

Device Binding Info

Field Description

deviceIndex The index number from Visa where the deviceID is stored. This is
required for token device binding.
Format: Integer between 1 and 99, inclusive.

deviceID For Secure Element (SE) wallet providers, this value is the SE ID in hex
binary characters transformed to a 48-character string.
For Host Card Emulation (HCE) wallet providers, this field is the Device
ID as determined by the digital wallet provider (DWP). All
alphanumeric and special characters are allowed for HCE DWPs.
Secure Element (SE) ID represents the device ID.

l For SE DWPs, this value is the SE ID in hex binary characters

transformed to a 48-character string.
l For CBP DWPs, this field is the device ID as determined by the DWP.
All alphanumeric and special characters are allowed for CBP DWPs.
For Card-on-File (COF) wallets, this value is not present.
For the initial Check Eligibility request on PAN enrollment, this value
may not be available.
Format: String; max length 48 characters.

6 June 2023 Visa Confidential 79

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Field Description

deviceName Name of device.

Format: String; max length 16 characters.

deviceBindingStatus Device binding info status.

Format: It is one of the following values:

l DECLINED
l APPROVED
l CHALLENGED

Decrypted Payload
Field Description

tokenInfo Token information, which includes all fields that are available.
Format: A token info structure; see "Token Information" in the
"Encrypted Payload Data Structures" chapter for more information.

deviceInfo Device information, which includes the following fields:

l deviceID
l deviceType
l deviceNumber
l deviceName
Format: A device info structure; see "Device Information" in the
"Encrypted Payload Data Structures" chapter for more information.

riskInfo Risk information, which includes the following fields:

l walletProviderDeviceScore
l walletProviderAccountScore
l riskAssessmentScore
l visaTokenScore
l visaTokenDecisioning
l walletProviderReasonCodes
l issuerSpecialConditionCodes
Format: A risk info structure; see "Risk Information" in the "Encrypted
Payload Data Structures" chapter for more information.

6 June 2023 Visa Confidential 80

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Token Inquiry Errors

Successful API responses will return HTTP status code in the 2xx range. The response body, if
available, will contain the response of the API as described in this specification. If a business error is
present, it is assumed that no Standard Errors were detected in the API request.
VTS domain-specific business error reason codes are as follows:

HTTP Status Error Code Error Code Description

400 VSE40001 VSE_ERROR_REQUIRED_DATA_MISSING

400 VSE40000 VSE_ERROR_INVALID_DATA

400 VSE40003 VSE_ERROR_TOKEN_NOT_FOUND

400 VSE40010 VSE_ERROR_CRYPTOGRAPHY_ERROR

500 VSE40009 VSE_INTERNAL_SYSTEM_ERROR

Sample Payloads
Sample Request

GET https://{Visa host}/vtis/v1/tokenRequestors/

{tokenRequestorID}/tokens/{tokenReferenceID}/
details?apiKey=key
&cardHolderVerificationRetrieve=true
&deviceBindingInfo=true

Sample Successful Response

Headers

Response-Code: 200
X-RESPONSE-ID: 477...45
Content-Type: application/json;charset=UTF-8
Content-Language: en-US
Date:...

Response Body

{
"encryptedData": "eyJ...uw",
"panReferenceID": "V-3...83",
"entityOfLastAction": "TOKEN_REQUESTOR",
"walletAccountEmailAddressHash": "129...CB",
"clientWalletAccountID": "rq...E",
"panSource": "KEY_ENTERED",
"lastFourOfPAN": "...",

6 June 2023 Visa Confidential 81

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

"cardholderVerificationList": [
{
"lifeCycleTraceID": 239...47,
"status": "PENDING",
"timestamp": 1592869947
}
],
"deviceBindingInfoList": [
{
"deviceIndex": 1,
"deviceID": "...",
"deviceName": "...",
"deviceBindingStatus": "APPROVED"
}
]
}

All JWS and JWE elements are Base64URL-encoded. JWS:

<JWS Header>.<JWS Payload>.<JWS Signature>
JWS Payload:
<JWE>
JWE:

<Header>.<Encrypted Key>.<InitializationVector>.<Ciphertext>.
<Authentication Tag>

Decrypted Data
Decrypted data contained in JWE ciphertext element:

{
"tokenInfo": {
"token": "451...75",
"tokenType": "ECOMMERCE",
"tokenStatus": "ACTIVE",
"tokenExpirationDate": {
"month": "9",
"year": "2024"
},
"tokenAssuranceMethod": "00",
"lastTokenStatusUpdatedTime": "2020-05-06T14:15:10.000Z"
}
}

Decrypted Secure Element Data

{
"tokenInfo": {
"token": "...",
"tokenType": "SECURE_ELEMENT",
"tokenStatus": "ACTIVE",
"tokenExpirationDate": {

6 June 2023 Visa Confidential 82

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

"month": "...",
"year": "..."
},
"tokenAssuranceMethod": "00",
"tokenActivationDate": "2020-01-30T10:18:17.000Z",
"lastTokenStatusUpdatedTime": "2020-02-22T07:22:29.000Z"
},
"deviceInfo": {
"deviceID": "...",
"deviceType": "MOBILE_PHONE",
"deviceName": "...",
"deviceNumber": "5815"
},
"riskInfo": {
"walletProviderAccountScore": "3",
"walletProviderDeviceScore": "3",
"walletProviderReasonCodes": "01,02,03,04,0D,0G",
"visaTokenScore": "81",
"visaTokenDecisioning": "85",
"riskAssessmentScore": "5"
}
}

Decrypted HCE Data

{
"tokenInfo": {
"token": "...",
"tokenType": "HCE",
"tokenStatus": "ACTIVE",
"tokenExpirationDate": {
"month": "...",
"year": "..."
},
"tokenAssuranceMethod": "00",
"tokenActivationDate": "2020-06-08T16:19:59.000Z",
"lastTokenStatusUpdatedTime": "2020-06-08T16:20:18.000Z"
},
"deviceInfo": {
"deviceID": "...",
"deviceType": "MOBILE_PHONE",
"deviceName": "..."
},
"riskInfo": {
"visaTokenScore": "35",
"visaTokenDecisioning": "00",
"riskAssessmentScore": "23"
}
}

6 June 2023 Visa Confidential 83

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Token Inquiry by PAN

This service enables the issuer to retrieve a list of all tokens for a PAN.

Request

Endpoints

Path:

{Visa host}/vtis/v1/pan/retrieveTokenInfo?apiKey=key

Method
POST

Query Parameters

API Key

Parameter Description

apiKey (Required) Client-specific API Key issued during onboarding. This value
is passed as a query parameter.
Format: String; alphabetic, numeric; max length 64 characters.

Request Body

Field Description

panReferenceID (Conditional) Unique ID for the PAN. This ID can be used in lieu of PAN
for the subsequent calls, such as life cycle events.
Format: String; max length 32 characters.

encryptedData (Conditional) Blob field that represents the encrypted payload; see
"Cardholder Information" in the "Encrypted Payload Data Structures"
chapter for more information. Only primaryAccountNumber needs
to be provided.
Format: String; max length 7000 characters.

6 June 2023 Visa Confidential 84

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Note:  
Either panReferenceID OR encryptedData (PAN) is required. Any requests having more
than one combination is not supported.

Response
Successful API responses will return HTTP status code in the 2xx range. The response body, if
available, will contain the response of the API as described in this specification.

Field Description

tokenDetails Token details that include PAN, token, and token requestor IDs, client
wallet account ID, PAN source, etc. If PAN or PAN Reference ID is
provided in the request, all tokens (max. up to 100) associated with the
PAN/PAN Reference ID and its attributes will be provided in the
response.
Format: An array of tokenDetails structures.

Token Details

Field Description

tokenRequestorID Unique ID assigned to the initiator of the token request.

Format: Numeric; max length 11 digits.

tokenReferenceID Unique ID for the token associated with the PAN. Can be used in lieu of
the token for subsequent calls, such as lifecycle events.
Format: String; max length 32 characters.

panReferenceID Unique ID for the PAN. Can be used in lieu of PAN for subsequent calls,
such as lifecycle events.
Format: Integer; max length 32 characters.

entityOfLastAction The entity of the last action.

Format: It is one of the following values:

l TOKEN_REQUESTOR
l ISSUER
Only the actor that suspended the token can change the status back to
Activate.

walletAccountEmailAddressHash Hash of email address linked to their wallet account login.

Format: String; max length 64 characters.

6 June 2023 Visa Confidential 85

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Field Description

clientWalletAccountID Consumer ID identifying the wallet account-holder entity. Provided by

the client.
Format: String; max length 32 characters.

panSource Source of the PAN.

Format: It is one of the following values:

l KEY_ENTERED
l ON_FILE
l MOBILE_BANKING_APP
l TOKEN
l CHIP_DIP
l CONTACTLESS_TAP

tokenType Type of the token.

Format: It is one of the following values:

l SECURE_ELEMENT
l HCE
l CARD_ON_FILE
l ECOMMERCE
l QRC

tokenStatus Status of the token.

Format: It is one of the following values:

l ACTIVE
l INACTIVE
l SUSPENDED
l DEACTIVATED

autoFillIndicator Whether this is token was used to initiate token autofill.

Format: It is one of the following values:

l true
l false

lastFourOfPAN Last four digits of the current PAN for the token.
Format: String; max length 4 characters.

Error Response
If a business error is present, it is assumed that no Standard Errors were detected in the API request.

6 June 2023 Visa Confidential 86

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

VTS domain-specific business error reason codes are as follows:

HTTP Status Error Code Error Code Description

400 VSE40001 VSE_ERROR_REQUIRED_DATA_MISSING

400 VSE40000 VSE_ERROR_INVALID_DATA

400 VSE40003 VSE_ERROR_TOKEN_NOT_FOUND

400 VSE40010 VSE_ERROR_CRYPTOGRAPHY_ERROR

500 VSE40009 VSE_INTERNAL_SYSTEM_ERROR

Sample Payloads

Sample Request
{
“encryptedData”: “<JWS>”
}

All JWS and JWE elements are Base64URL-encoded.

JWS:
<JWS Header>.<JWS Payload>.<JWS Signature>
JWS Payload:
<JWE>
JWE:

<Header>.<Encrypted Key>.<InitializationVector>.<Ciphertext>.
<Authentication Tag>

Decrypted data contained in JWE ciphertext element:

{
“cardholderInfo”: {
“primaryAccountNumber”: “”
}
}

OR

{
“panReferenceID”: “V-420...90”,
}

6 June 2023 Visa Confidential 87

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Sample Successful Response

{
"tokenDetails": [
{
"tokenRequestorID": 400...73,
"tokenReferenceID": "DNI...70",
"panReferenceID": "V-3...25",
"entityOfLastAction": "TOKEN_REQUESTOR",
"walletAccountEmailAddressHash": "5DA...27",
"clientWalletAccountID": "5DA...D8",
"panSource": "KEY_ENTERED",
"tokenType": "SECURE_ELEMENT",
"tokenStatus": "DEACTIVATED",
"lastFourOfPAN": "..."
},
{
"tokenRequestorID": 400...73,
"tokenReferenceID": "DNI...04",
"panReferenceID": "V-3...25",
"entityOfLastAction": "TOKEN_REQUESTOR",
"walletAccountEmailAddressHash": "5DA...27",
"clientWalletAccountID": "5DA...D8",
"panSource": "KEY_ENTERED",
"tokenType": "SECURE_ELEMENT",
"tokenStatus": "DEACTIVATED",
"lastFourOfPAN": "..."
},
{
...
},
{
"tokenRequestorID": 400...73,
"tokenReferenceID": "DNI...71",
"panReferenceID": "V-3...25",
"entityOfLastAction": "TOKEN_REQUESTOR",
"walletAccountEmailAddressHash": "656...00",
"clientWalletAccountID": "Ad_...40",
"tokenType": "CARD_ON_FILE",
"tokenStatus": "ACTIVE",
"lastFourOfPAN": "..."
},
{
...
}
]
}

Token Lifecycle
This service enables the issuer to activate, resume, suspend, or delete the token.

6 June 2023 Visa Confidential 88

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Lifecycle Actions at Token States

Various lifecycle actions that are permitted at various token states are given below:

Valid Actions

Status Activate Suspend Resume Deactivate Update PAN Replace PAN

(3713) (3702) (3703) (3701) Expiry Date for Token
(3720) (3721)

Inactive (I) Y N N Y Y Y

Active (A) N Y N Y Y Y

Suspended (S) N N Y Y Y Y

Deactivated (D) N N N N Y N

Request

Endpoints

Path:

{Visa host}/vtis/v1/tokenRequestors/
{tokenRequestorID}/tokens/{tokenReferenceID}/lifecycle?apiKey=key

URL Parameters

Parameter Description

{tokenRequestorID} (Required) Unique ID assigned to the initiator of the token request.

Format: Numeric; max length 11 digits.

{tokenReferenceID} (Required) Unique ID for the token associated with the PAN. This ID can
be used in lieu of the token for subsequent calls, such as lifecycle
events.
Format: String; max length 32 characters.

Method
POST

6 June 2023 Visa Confidential 89

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Query Parameters

Parameter Description

apiKey (Required) Client-specific API Key issued during onboarding.

Format: String; alphabetic, numeric; max length 64 characters.

Request Body

Field Description

operatorID (Optional) Operator ID of either the person or system that is

performing the operation.
Format: String, max length 16 characters.

operationType (Required) Type of operation.

Format: It is one of the following values:

l DELETE
l SUSPEND
l RESUME
l CALL_CENTER_ACTIVATION
l TOKEN_DEVICE_BINDING_APPROVE
l TOKEN_DEVICE_BINDING_REMOVE
l TOKEN_TRUSTED_LISTING_ADD
l TOKEN_TRUSTED_LISTING_REMOVE
l TOKEN_DEVICE_BINDING_APPROVE_CALL_CENTER
l TOKEN_DEVICE_BINDING_APPROVE_BANK_APP
l CARDHOLDER_STEPUP_CALL_CENTER
l CARDHOLDER_STEPUP_APP_TO_APP

operationReason (Required) Reason for operation. Free form. The reason should be
descriptive, such that if the issuer performs an action and the
consumer calls DWP Customer Support, they should be able to read
the reason, advise the consumer, and act accordingly. For example, if
the token is suspended, the Request Reason could say “Suspended due
to lost device”
Format: String; max length 254 characters.

6 June 2023 Visa Confidential 90

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Field Description

deviceInfo (Conditional) Only valid for Device Binding operations, in which case
deviceID and deviceIndex must be populated.
Format: A Device Information structure.

activationCode (Conditional) Equivalent of Auth Code. Required if operationType is

CALL_CENTER_ACTIVATION.This parameter is merely used for audit
purposes. There is no validation on Visa’s side and the value is not
passed to DWP but saved into the audit log as proof that the activation
request was approved by the issuer.
Format: String; max length 8 characters.

Device Information
This structure is used by several APIs.

Field Description

deviceID (Conditional) For Secure Element (SE) wallet providers, this value will be
the SE ID in hex binary characters transformed to a 48-character string.
For Host Card Emulation (HCE) wallet providers, this field will be the
Device ID as determined by the digital wallet provider (DWP). All
alphanumeric and special characters are allowed for HCE DWPs.
Secure Element (SE) ID represents the device ID.

l For SE DWPs, this value will be the SE ID in hex binary characters

transformed to a 48-character string.
l For CBP DWPs, this field will be the device ID as determined by the
DWP. All alphanumeric and special characters are allowed for CBP
DWPs.
For Card-on-File (COF) wallets, this value will not be present.
For the initial Check Eligibility request on PAN enrollment, this value
may not be available, however Visa will send this value if it is available.
Format: String; max length 48 characters.

deviceLanguageCode (Optional) This value is any ISO 639 Version 3 Language Code, for
example, eng (English). This language code will be used by the issuer
and Visa to retrieve the Terms and Conditions (T&C). If T&Cs are not
found for the Language Code in the request, the T&Cs will return the
default :anguage Code of eng (English).
Format: String; ISO-639 Version 3 Language Code, max length 3
characters.

6 June 2023 Visa Confidential 91

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Field Description

deviceType (Optional) Device type.

Format: It is one of the following values:

l UNKNOWN
l MOBILE_PHONE
l TABLET
l WATCH
l MOBILEPHONE_OR_TABLET
l PC
l HOUSEHOLD_DEVICE
l WEARABLE_DEVICE
l AUTOMOBILE_DEVICE

deviceName (Optional) A readable name for the device. Ideally, the customer enters
this name. It can be used to identify the device in customer support
calls.
Example: My Work Phone
Format: String; Base64URL-encoded; UTF-8; max length 128
characters.

deviceNumber (Optional) Device number.

Format: String; max length 13 characters.

osType (Optional) Type of operating system.

Format: It is one of the following values:

l ANDROID
l IOS
l WINDOWS
l BLACKBERRY
l TIZEN
l OTHER

osVersion (Optional) Version of the operating system running on the device.

Example: 4.4.4
Format: String; max length 32 characters.

osBuildID (Optional) Operating system build identifier.

Example: KTU84M
Format: String; max length 32 characters.

6 June 2023 Visa Confidential 92

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Field Description

deviceIDType (Optional) Attribute indicating the source of the Device ID value.

Example: The source for Device ID (deviceID) could be
SecureElement, TEE, or Derived
Format: String; max length 32 characters.

deviceManufacturer (Optional) Manufacturer of the device.

Example: Samsung
Format: String; max length 32 characters.

deviceBrand (Optional) Brand name of the device.

Example: Galaxy
Format: String; max length 32 characters.

deviceModel (Optional) model of the device.

Example: SGH-T999
Format: String; max length 32 characters.

deviceLocation (Optional) Obfuscated geographic location of the device. Initially, when

provisioned, this contains the general location of the device.
Information will be supplied with latitude/longitude rounded to the
nearest whole digit.
Example: +37/-121
Format: String; max length 25 characters.

deviceIndex (Conditional) The index number from Visa where the deviceID is
stored. This is required for token device binding.
Format: Integer; max length 2 digits.

deviceIPAddressV4 (Optional) The IP address of the device at the time of the provisioning
request, with the value represented in 255.255.255.255 format. An
octet (255) may be 1–3 digits in length but cannot contain any leading
zeros.
Format: String; max length 15 characters.

6 June 2023 Visa Confidential 93

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Field Description

locationSource (Optional) Source used to identify consumer location.

Format: It is one of the following values:

l WIFI
l CELLULAR
l GPS
l OTHER

tokenProtectionMethod (Optional) Method of token protection.

Format: It is one of the following values:

l SOFTWARE
l TRUSTED_EXECUTION_ENVIRONMENT
l SECURE_ELEMENT
l CLOUD

Response

Successful Response
Successful API responses will return HTTP status code in the 2xx range. No response body, if
available, will contain the error response of the API as described in this specification.

Error Response
If a business error is present, it is assumed that no Standard Errors were detected in the API request.
VTS domain-specific business error reason codes are as follows:

HTTP Status Error Code Error Code Description

400 VSE40000 VSE_ERROR_INVALID_DATA

400 VSE40001 VSE_ERROR_REQUIRED_DATA_MISSING

400 VSE40002 VSE_ERROR_TOKEN_STATE_EXIST

400 VSE40003 VSE_ERROR_TOKEN_NOT_FOUND

400 VSE40010 VSE_ERROR_CRYPTOGRAPHY_ERROR

400 VSE40011 VSE_TOKEN_NOT_ACTIVE

500 VSE40009 VSE_INTERNAL_SYSTEM_ERROR

6 June 2023 Visa Confidential 94

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Sample Payloads

Sample Request
POST https://[Visa host]/vtis/v1/tokenRequestors/400...49/tokens/
DNI...VX/
lifecycle?apikey=XDI...C4

Request Body

{
"operatorID": "...",
"operationReason": "a reason",
"operationType": "TOKEN_DEVICE_BINDING_APPROVE",
"deviceInfo": {
"deviceID": "...",
"deviceIndex": 1
}
}

Sample Successful Response

HTTP 200 Success status with no payload.

Retrieve Network Hub Push

Provisioning (NHPP) Profiles
This service enables the issuer to retrieve a list of all the Network Hub Push Provisioning (NHPP)
profiles.

Request

Endpoints

Path:

{Visa host}/vtis/v1/retrieveNHPPParticipants?apiKey=key

6 June 2023 Visa Confidential 95

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Method
POST

Query Parameters

API Key

Parameter Description

apiKey (Required) Client-specific API Key issued during onboarding. This value
is passed as a query parameter.
Format: String; alphabetic, numeric; max length 64 characters.

Request Body

Field Description

encryptedData (Required) Blob field that contains the encrypted payload; see
"Cardholder Information" in the "Encrypted Payload Data Structures"
chapter for more information. Only primaryAccountNumber needs
to be provided.
Format: String; max length 7000 characters.

Response

Successful Response
Successful API responses will return HTTP status code in the 2xx range. The response body, if
available, will contain the response of the API as described in this specification.

Field Description

nhppProfiles NHPP profiles.

Format: An NHPP Profiles structure array.

6 June 2023 Visa Confidential 96

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

NHPP Profiles

Field Description

displayName Application name/brand name displayed in the issuer application.

Format: String; max length 100 characters.

clientID Unique ID that identifies the client entity.

Format: String; max length 36 characters.

tokenRequestorID Unique ID that identifies the entity for which the token request is being
conducted on behalf of (OBO).
Format: String; max length 11 digits.

tokenTypes Types of tokens to select from.

Format: An array of the following values:

l SECURE_ELEMENT
l HCE
l CARD_ON_FILE
l ECOMMERCE
l QRC

logoURL Content URI.

Format: String; Base64URL-encoding, hyphens (-), and underscores (_)
are allowed to replace plus signs (+), and forward slashes (/); max
length 1024 characters.

sourceAddress The URL that is used by issuers to push the encrypted payload for
cross-device push provisioning.
Format: String; Base64URL-encoded; max length 1024 characters.

supportedPlatforms A list of the end point URIs that can be invoked to push a token to the
token requestor.
Format: An array of Wallet Provider Supported Platforms Information
structures

supportedCardTypes An array of supported card types.

Format: It is one of the following values:

l VISA
l MASTERCARD

Note:  
Either sourceAddress OR supportedPlatforms is required.

6 June 2023 Visa Confidential 97

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Wallet Provider Supported Platforms Information

Field Description

uri The URI or universal link that is used to invoke the token requestor’s
device or web app.
Format: String, max length 1024 characters.

platformType The platform type this URL was configured for.

Format: It is one of the following values:

l IOS
l ANDROID
l WEB
l WINDOWS
l VISA_AS_HOP

accountBindingMode Indicates if this URI can be invoked for up-front or post-provisioning

account binding.
Format: It is one of the following values:

l POST_BINDING

Error Response
If a business error is present, it is assumed that no “Standard Errors” were detected in the API
request.
VTS domain-specific business error reason codes are as follows:

HTTP Status Error Code Error Code Description

400 VSE40001 VSE_ERROR_REQUIRED_DATA_MISSING

400 VSE40000 VSE_ERROR_INVALID_DATA

400 VSE40010 VSE_ERROR_CRYPTOGRAPHY_ERROR

500 VSE40009 VSE_INTERNAL_SYSTEM_ERROR

Sample Payloads

6 June 2023 Visa Confidential 98

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Sample Successful Request

{
“encryptedData”: “<JWS>”
}

All JWS and JWE elements are Base64URL-encoded.

JWS:
<JWS Header>.<JWS Payload>.<JWS Signature>
JWS payload:
<JWE>
JWE:

<Header>.<Encrypted Key>.<Initialization Vector>.<Ciphertext>.

<Authentication Tag>

Decrypted data contained in JWE Ciphertext element:

{
“cardholderInfo”:{
“primaryAccountNumber”: “”
}
}

Sample Successful Response

{
"nhppProfiles": [
{
"displayName": "Test",
"clientID": "180...01",
"tokenRequestorID": "400...45",
"tokenTypes": [
"HCE",
"ECOMMERCE"
],
"logoURL": "aHR.....",
"supportedPlatforms": [
{
"platformType": "VISA_AS_HOP",
"accountBindingMode": [
"POST_BINDING"
]
}
],
"supportedCardTypes": [
"VISA"
]
},

6 June 2023 Visa Confidential 99

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

{
"displayName": "SRC",
"clientID": "33ba...01",
"tokenRequestorID": "400...38",
"tokenTypes": [
"HCE",
"ECOMMERCE"
],
"logoURL": "aHR...0.",
"supportedPlatforms": [
{
"platformType": "VISA_AS_HOP",
"accountBindingMode": [
"POST_BINDING"
]
}
],
"supportedCardTypes": [
"VISA"
]
},
{
"displayName": "vhop",
"clientID": "2170...bb",
"tokenRequestorID": "400...95",
"tokenTypes": [
"HCE",
"ECOMMERCE"
],
"logoURL": "aHR......",
"supportedPlatforms": [
{
"platformType": "VISA_AS_HOP",
"accountBindingMode": [
"POST_BINDING"
]
}
],
"supportedCardTypes": [
"VISA"
]
},
{
"displayName": "SDKNHPPTest",
"clientID": "4e7...01",
"tokenRequestorID": "400...39",
"tokenTypes": [
"HCE",
"ECOMMERCE"
],
"logoURL": "aHR...0.",
"supportedPlatforms": [
{
"platformType": "VISA_AS_HOP",
"accountBindingMode": [
"POST_BINDING"
]
}

6 June 2023 Visa Confidential 100

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

],
"supportedCardTypes": [
"VISA"
]
}
]
}

Update Card Metadata

This service lets the issuer update Card Metadata attributes associated with the card after the card
has provisioned in the digital wallet. For example, if the product changes after the initial successful
provisioning (for example, cardholder account is upgraded to Visa Signature), the issuer can take
advantage of this API to change Cart Art images without requiring re-provisioning.
You can specify updates by either PAN or token:
l If you update by PAN, using the encrypted account number or the PAN's reference ID, the
update will apply to all tokens associated with the PAN.
l If you update using a combination of token requestor ID and token reference ID, the update
will apply to only the specified token requestor and token combination.
Note:  
When sending updates for a card, the complete set of metadata attributes should be sent and
not only the ones that were changed.

Request

Endpoints

Path:
{Visa host}/vtis/v1/updateCardMetadata?apiKey=key

Method
POST

6 June 2023 Visa Confidential 101

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Query Parameters

API Key

Parameter Description

apiKey (Required) Client-specific API Key issued during onboarding. This value
is passed as a query parameter.
Format: String; alphabetic, numeric; max length 64 characters.

Request Body

Field Description

tokenRequestorID (Conditional) Unique ID assigned to the initiator of the token request.

Required when tokenReferenceID is specified.
Format: Numeric; max length 11 digits.

tokenReferenceID (Conditional) Unique ID for the token associated with the PAN.
Required when tokenRequestorID is specified. Can be used in lieu
of the token for subsequent calls, such as lifecycle events. Specifying a
value causes metadata to be updated for only the associated token.
Format: String; max length 32 characters.

panReferenceID (Conditional) Unique ID for the PAN. See the note below regarding
when it is required. Can be used in lieu of PAN for subsequent calls,
such as lifecycle events. Specifying a value causes metadata to be
updated for all tokens associated with the PAN.
Format: String; max length 32 characters.

operatorID (Optional) Operator ID of either person or system performing the

operation.
Format: String; max length 16 characters.

operationReason (Required) Populate the reason for card metadata change.

Format: String; max length 128 characters.

cardMetadataInfo (Required) Card metadata information.

Format: A Card Metadata Information structure.

encryptedData (Conditional) Blob field that contains the encrypted payload; see
"Cardholder Information" in the "Encrypted Payload Data Structures"
chapter for more information. Only primaryAccountNumber needs
to be provided. See the note below regarding when it is required.
Specifying a value causes metadata to be updated for all tokens
associated with the PAN.
Format: String; max length 7000 characters.

6 June 2023 Visa Confidential 102

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Note:  
One of the following is required:
l tokenRequestorID and tokenReferenceID, OR
l panReferenceID, OR
l encryptedData (primaryAccountNumber)
Any requests having more than one combination is not supported.

Card Metadata Information

Field Description

cardIssuer (Optional) Card issuer name.

Format: String; max length 128 characters.

foregroundColor (Optional) Foreground color of the Digital Wallet entry for the card.
Specified as a CSS style RGB triple. This value is optional in this API
because the issuer may pre-configure this value via Visa Card Art
Management (VCMM).
Example: rgb(255,122,235)
Format: String; max length 32 characters.

backgroundColor (Optional) Background color of the Digital Wallet UI entry (“space”) for
the card. Specified as a CSS style RGB triple. It is optional in this API
because the issuer may pre-configure this value via VCMM
Example: rgb(255,122,235)
Format: String; max length 32 characters.

labelColor (Optional) Label color of the Digital Wallet entry for the card. Specified
as a CSS style RGB triple. It is optional in this API because the issuer
may pre-configure this value via VCMM.
Example: rgb(255,122,235)
Format: String; max length 32 characters.

shortDescription (Optional) A short description of the card. May be used with lock-
screen notifications.
Example: The Bank Card
Format: String; max length 32 characters.

longDescription (Optional) Longer description of the card. May be used inside the
Digital Wallet.
Example: The Bank Signature Rewards Card
Format: String; max length 64 characters.

6 June 2023 Visa Confidential 103

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Field Description

profileID (Conditional) Profile ID associated with the card. Only applicable for
issuers who opt for the Check Eligibility API service. During the pre-
loading of Card Metadata into the Visa system, either via Visa Card Art
Management UI (VCMM) or the Batch file Interface, issuers have an
option to assign their own unique profile ID (GUID) to a set of card
metadata.
Example: 12c7bc...
In this example:

1. The profile ID is assigned.

2. Issuers populate the profile ID in the Check Eligibility Response or
the Update Card Metadata Request.
3. Visa retrieves all the card metadata associated with the Profile ID
received in the Check Eligibility Response, or the Update Card
Metadata Request, and sends it to the DWP.
When a profile ID is used, no other card metadata elements are
required to be sent to Visa in the messages.
Format: String; lowercase, hexadecimal, hyphens (-) are not allowed;
max length 32 characters.

cardArtData (Optional) Card art data.

Format: An array of card art reference IDs in a cardArtRefID
structure; see Card Art Details.

termsAndConditionsID (Optional) GUID-based file name for Terms and Conditions text. File
used by the issuer while loading the image in VCMM. This is a DWP
required field. However, it is optional in this API because the issuer can
pre-configure this value via VCMM. This value is not applicable for
Check Eligibility; only available for Update Card Metadata.
Format: String; max length 64 characters.

privacyPolicyURL (Optional) URL pointing to an issuing bank’s privacy policy. This value is
nott applicable for Check Eligibility; only available for Update Card
Metadata.
Format: String; max length 128 characters.

termsAndConditionsURL (Optional) URL pointing to the issuing bank’s terms and conditions for
a card. This value is not applicable for Check Eligibility; only available
for Update Card Metadata.
Format: String; max length 128 characters.

contactInfo (Optional) Contact information.

Format: A Contact Information structure.

applicationInfo (Optional) Applicaton information.

Format: A Card Metadata Application Information structure.

6 June 2023 Visa Confidential 104

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Card Art Data Details

Field Description

cardArtRefID (Conditional) GUID-based file names for Cart Art Image file used by
the issuer while loading the image in VCMM. Required by DWP-
required field; it is optional in this API because the issuer can pre-
configure this value via VCMM.
Format: An array of GUID-based file names; max length 32 characters.

Card Metadata Application Information

Field Description

supportsTokenNotifications (Optional) Indicates whether the card supports token notifications for
transactions originating on the device.
Format: It is one of the following values:

l true
l false

supportsFPANNotifications (Optional) Indicates whether the card supports FPAN notifications for
all transactions that point back to the FPAN. Not applicable for Check
Eligibility; only available for Update Card Metadata.
Format: It is one of the following values:

l true
l false

transactionServiceURL (Optional) Transaction history URL (Transaction Details) of the issuer’s

web service. Not applicable for Check Eligibility; only available for
Update Card Metadata.
Format: String; max length 128 characters.

messageServiceURL (Optional) URL of the message/offer web service that conforms to the
API as described to PNOs and issuers in the Card Notification Services
API Specification. Not applicable for Check Eligibility; only available for
Update Card Metadata.
Format: String; max length 128 characters.

transactionPushTopic (Conditional) A push topic the issuer uses to notify the device that new
transactions are available. Not applicable for Check Eligibility; only
available for Update Card Metadata.
Format: String; max length 128 characters.

messagePushTopic (Conditional) A push topic the notification provider uses to notify the
device that new messages are available. Not applicable for Check
Eligibility; only available for Update Card Metadata.
Format: String; max length 128 characters.

6 June 2023 Visa Confidential 105

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Field Description

appLaunchURL (Optional) URL passed to the associated issuer mobile app when
launching it. If this key is present, the
associatedStoreIdentifiers key must also be present. This
field is not applicable for Check Eligibility; only for Update Card
Metadata.

Format: String; max length 128 characters.

appLaunchURLScheme (Optional) URL scheme that the application is registered for, in order to
deep link from transaction notifications and show all transaction notifi­
cations. The Application ID must be included in the
associatedApplicationsIdentifiers array and the application
itself must register for the URL scheme specified in this key. This field is
not applicable for Check Eligibility; only for Update Card Metadata.

Format: String; max length 32 characters.

associatedStoreIdentifiers (Optional) A list of mobile application store item identifiers for

associated issuer mobile banking application. Format is specific to a
mobile store/phone platform. Only one item in the list is used: the first
item identifier for an application compatible with the current device.
This field is not applicable for Check Eligibility; only for Update Card
Metadata.

l If the application is not installed, the link opens the mobile

application store and shows the application.
l If the application is already installed, the link launches it (this only
applies to SE DWPs).
Format: String; max length 20 characters.

associatedApplicationIdentifiers (Optional) An array of associated app identifiers. Similar to

associatedStoreIdentifiers, but explicit App IDs (only
applicable to SE DWPs). This field is not applicable for Check Eligibility;
only for Update Card Metadata.
Format: String; max length 128 characters.

Contact Information

Field Description

contactWebsite (Optional) Customer Service website of the issuing bank.

Format: String; max length 128 characters.

contactEmail (Optional) Customer Service email address of the issuing bank.

Format: String; max length 32 characters.

6 June 2023 Visa Confidential 106

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Field Description

contactNumber (Optional) Customer Service phone number of the issuing bank.

Format: String; max length 32 characters.

contactName Name of the issuing bank. It may be used in combination with other
text strings.
Example: If contactName is “XYZ Bank”, it may be used to construct
a string such as “Contact XYZ Bank”, or “XYZ Bank Contact
Information”.
Format: String; max length 32 characters.

Response
Note:  
Visa will return the response after validating the request received from the issuer. A successful
response is not an indication that card metadata updates have been successfully done on the
device(s); it is merely an indication that updates have been successfully queued up by Visa for
delivery to device(s). If a device is not accessible, the actual update may happen much later.

Successful Response
Successful API responses will return HTTP status code in the 2xx range. The response body, if
available, will contain the response of the API as described in this specification.

Field Description

responseDetails Contains response details such as task, token reference. and token
requestor IDs and status code. Also includes all inactive tokens.
Deactivated tokens will be returned with the Action Code of
NOT_ALLOWED
Format: A Response Details structure array.

Response Details

Field Description

taskID GUID, with hyphens allowed. The issuer needs to store this for future
references. This value is present when Action Code is PENDING
Format: String, [A-Z][a-z][0-9], with hyphens (-) allowed; max length
36 characters.

tokenRequestorID Unique ID assigned to the initiator of the token request.

Format: Numeric; max length 11 digits.

6 June 2023 Visa Confidential 107

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Field Description

tokenReferenceID Unique ID for the token associated with the PAN. This can be used in
lieu of the token for subsequent calls, such as lifecycle events.
Format: String; max length 32 characters.

panReferenceID Unique ID for the PAN. This can be used in lieu of the PAN for
subsequent calls, such as life cycle events.
Format: String; max length 32 characters.

statusCode Action status codes.

Format: It is one of the following values:

l PENDING
l FAILURE
l NOT_ALLOWED

errorCode This is present for business error codes VSEXXXXX and status code
FAILURE.
Format: String; max length 8 characters.

Error Responses
If a business error is present, it is assumed that no “Standard Errors” were detected in the API
request.
VTS domain-specific business error reason codes are as follows:

HTTP Status Error Code Error Code Description

400 VSE40001 VSE_ERROR_REQUIRED_DATA_MISSING

200 with Successful VSE40000 VSE_ERROR_INVALID_DATA

Response
400 with Error Response

200 VSE40003 VSE_ERROR_TOKEN_NOT_FOUND

400 VSE40004 VSE_ERROR_INVALID_PROFILE_ID

200 VSE40007 VSE_ERROR_INVALID_TOKEN_STATE

400 VSE40010 VSE_ERROR_CRYPTOGRAPHY_ERROR

500 VSE40009 VSE_INTERNAL_SYSTEM_ERROR

Sample Payloads

6 June 2023 Visa Confidential 108

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Sample Request
{
"encryptedData": "<JWS>",
"operatorID": "Operator1",
"operationReason": "OperationReason",
"cardMetadataInfo": {
"foregroundColor": "rgb(255,255,255)",
"backgroundColor": "rgb(255,255,255)",
"labelColor": "rgb(255,255,255)",
"shortDescription": "Fifth Group",
"longDescription": "Fifth Group",
"cardIssuer": "ieadmin",
"cardArtData": {
"cardArtRefID": [
"...",
"...",
"...",
"..."
]
},
"privacyPolicyURL": "https://www.issuer.com/data/dataprivacy",
"termsAndConditionsURL": "https://issuer.com/data/tnc",
"contactInfo": {
"contactWebsite": "https://issuer.com",
"contactNumber": "800-000-0000",
"contactName": "issuer"
},
"applicationInfo": {
"supportsTokenNotifications": true,
"supportsFPANNotifications": false,
"transactionServiceURL":
"https://vntsnotificationservice.visa.com/TxnHist/1",
"messageServiceURL": null
}
}
}

Sending Profile ID

{
"operationReason": "Card Art Update",
"tokenReferenceID": "DNI...77",
"tokenRequestorID": "400...24",
"cardMetadataInfo": {
"cardArtData": {},
"contactInfo": {},
"applicationInfo": {},
"profileID": "bxx...2d"
}
}

All JWS and JWE elements are Base64URL-encoded.

JWS:

6 June 2023 Visa Confidential 109

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

<JWS Header>.<JWS Payload>.<JWS Signature>

JWS payload:
<JWE>
JWE:

<Header>.<Encrypted Key>.<InitializationVector>.<Ciphertext>.
<Authentication Tag>

Decrypted data contained in JWE Ciphertext element:

{
“cardholderInfo”: {
“primaryAccountNumber”: “”
}
}

Sample Successful Response

{
“responseDetails”: [{
“taskID”: “ed3 91”,
“tokenReferenceID”: “D95 32”,
“tokenRequestorID”: 400...11,
“statusCode”: “PENDING”
},
{
“taskID”: “42b 35”,
“tokenReferenceID”: “F55 32”,
“tokenRequestorID”: 400...11,
“statusCode”: “PENDING”
}]
}

Sample Business Error Response

{
“errorCode”: “VSE40008”
}

Token Requestor Report

This service enables the issuer to retrieve a report on the token requestors onboarded to Visa.
Each request retrieves the specified page of results; the first page is 0. Each page contains a
maximum of limit results. Thus, if the page is 0 and limit is 100, a maximum of 100 results are
returned in the response and the totalResults response field contains the total number of results

6 June 2023 Visa Confidential 110

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

that match the criteria. You can iterate over subsequent results, incrementing the page number and
calling the API for the next page until you have received all the results.
Note:  
You can obtain all the results when the page value multiplied by the limit value is equal to
or exceeds the totalResults; or if page equals 0, when the limit is equal to or exceeds
the totalResults.

Request

Endpoints

Path:
{Visa host}/vtis/v1/reports/tokenRequestor

Method
GET

Query Parameters

API Key

Parameter Description

apiKey (Required) Client-specific API Key issued during onboarding. This value
is passed as a query parameter.
Format: String; alphabetic, numeric; max length 64 characters.

page (Required) The zero-based page number of results to retrieve; a value

of 0 specifies the first page. The expected usage for iterative calls to
this API is to increment the page value for each subsequent call.
Format: Integer; minimum value 0

limit (Required) Maximum number of results to be retrieved in this request.

The typical usage for iterative calls to this API is to set the value once
and use the same value in each call to this API; however, you can set
limit to 0 to determine the total matching results without retrieving
results.
Format: Integer; a value between 0 and 1000, inclusive

6 June 2023 Visa Confidential 111

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Parameter Description
fromIDAssignedDateTime (Required) The date/time that the token requestor ID was first
assigned, in GMT. The fromIDAssignedDateTime date must be
prior to the current date but no earlier than 60 days before the current
date.

Note:   The date range between fromIDAssignedDateTime

and toIDAssignedDateTime cannot exceed 14 days.
Format: String; yyyy-MM-ddTHH:mm:ss.SSSZ (DateTime)

toIDAssignedDateTime (Required) The date/time that the token requestor ID was last assigned
in GMT.

Note:   The date range between fromIDAssignedDateTime

and toIDAssignedDateTime cannot exceed 14 days.
Format: String; yyyy-MM-ddTHH:mm:ss.SSSZ (DateTime)

Request Body
None

Response

Successful Response
Successful API responses will return HTTP status code in the 2xx range. The response body, if
available, will contain the response of the API as described in this specification.

Field Description

count Number of elements in the tokenRequestors array.

Format: integer

totalResults Total number of matches for the provided filter criteria.

Format: integer

maxTokenRequestorIDAssigned Maximum token requestor IDs assigned date/time, in GMT

DateTime
Format: String; yyyy-MM-ddTHH:mm:ss.SSSZ (DateTime)

tokenRequestors Token requestors that match the criteria.

Format: An array of tokenRequestor structures; maximum 1000
items

6 June 2023 Visa Confidential 112

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Token Requestors

Field Description

tokenRequestorID Unique ID assigned to the initiator of the token request.

Format: Numeric; max length 11 digits

tokenRequestorName Name of the token requestor.

Format: String, max 100 characters

tokenRequestorWebsiteURL Token requestor website universal resource locator (URL) address.

Format: String, max 128 characters

tokenTypes Token types.

Format: It is one of the following values:

l SECURE_ELEMENT
l HCE
l CARD_ON_FILE
l ECOMMERCE
l QRC

tokenRequestorType Kind of token requestor.

Format: It is one of the following values:

l DWP_THIRDPARTY - 01-Digital Wallet Provider - Third Party (ID&V

Required)
l MERCHANT_OF_RECORD - 03-Payment Service Provider (COF
Controls)
l PAYMENT_SERVICE_PROVIDER - 03-Payment Service Provider
(COF Controls)
l ACQUIRER - 04-Financial Institution - Acquirer (ID&V Required)
l ISSUER - 05-Financial Institution - Issuer (No ID&V Required)
l ISSUER_ACQUIRER - 06-Financial Institution - Acquirer and Issuer
(No ID&V Required)
l DWP_ISSUER - 07-Digital Wallet Provider - Issuer (No ID&V
Required)
l UNKNOWN - Token requestor type could not be determined

tokenRequestorTSPs Token requestor TSPs.

Format: An array of tokenRequestorTSPs structures; maximum 50
items

tokenRequestorIDAssignedDateTime Token requestor ID assigned date/time

Format: String; yyyy-MM-ddTHH:mm:ss.SSSZ (DateTime)

6 June 2023 Visa Confidential 113

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

Token Requestor TSPs

Field Description

tokenRequestorTSPID Unique ID assigned to the token requestor token service provider.

Format: Numeric; max length 11 digits

tokenRequestorTSPName Name of the token requestor token service provider.

Format: String, max 100 characters

Error Responses
Only standard errors are returned; for more information, see "Error Handling" in "Getting Started with
REST APIs."

Sample Payloads
Sample Request

GET https://cert.api.visa.com/vtis/v1/reports/tokenRequestor?
apiKey=...&
fromIDAssignedDateTime=2022-11-03T08%3A57%3A20.567&
limit=1&
page=0&
toIDAssignedDateTime=2022-11-05T08%3A57%3A20.567
x-pay-token: xv2:167...78:c6e...c2
x-request-id: sample123

Sample Successful Response

Selected Headers

Response-Code: 200
X-RESPONSE-ID: 166...WS
Content-Type: application/json;charset=UTF-8
Content-Language: en-US
Date:...

Response Body

{
"count": 1,
"totalResults": 1,
"maxTokenRequestorIDAssignedDateTime": "2022-11-04T00:35:08.419",
"tokenRequestors": [
{
"tokenRequestorID": 34324421,

6 June 2023 Visa Confidential 114

Visa Token Service – Issuer API Specifications (JSON)
Inbound API Specifications (To Visa)

"tokenRequestorName": "RISE Test TR",

"tokenTypes": [
"ECOMMERCE"
],
"tokenRequestorType": "MERCHANT_OF_RECORD",
"tokenRequestorTSPs": [],
"tokenRequestorIDAssignedDateTime": "2022-11-04T00:35:08.419"
}
]
}

6 June 2023 Visa Confidential 115

Chapter 6
Outbound API Specifications (From
Visa)

Approve Provisioning
This API is invoked during the token provisioning flow on a device. Visa invokes this API call to the
issuer with Identity Verification and Validation (ID&V) attributes and other relevant attributes so that
the issuer can take appropriate action, such as approve, decline, or step-up, based on those
attributes to provision the token.

Request

6 June 2023 Visa Confidential 116

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Endpoints

Path:

{Issuer Endpoint}/vtis/v2/tokenRequestors/
{tokenRequestorID}/tokens/{tokenReferenceID}/approveProvisioning

URL Parameters

Parameter Description

{tokenRequestorID} (Required) Unique ID to the initiator of the token request.

Format: Numeric; max length 11 digits.

{tokenReferenceID} (Required) Unique ID for the token associated with the PAN. This ID can
be used in lieu of the token for subsequent calls, such as life cycle
events.
Format: String; max length 32 characters.

Method
POST

Request Body

Field Description

tokenInfo (Required) Data associated with the token.

Format: A tokenInfo structure.

panReferenceID (Required) Unique ID for the PAN. This ID can be used in lieu of PAN for
subsequent calls, such as lifecycle events.
Format: String, max length 32 characters.

lifeCycleTraceID (Required) A message identifier that can be used to link some

messages associated with a provisioning request. This should be used
by the issuer in event/message logging.
Format: Integer; max length 15 digits.

walletAccountEmailAddressHash (Required) Hash of email address that is linked to the wallet account
login ID.
Format: String; max length 64 characters.

clientWalletAccountID (Required) Consumer ID that identifies the Wallet Account Holder

entity. This value was provided by the client or, in some cases, by Visa.
Format: String; max length 32 characters.

6 June 2023 Visa Confidential 117

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

panSource (Required) Source of PAN.

Format: It is one of the following values:

l KEY_ENTERED
l ON_FILE
l MOBILE_BANKING_APP
l TOKEN
l CHIP_DIP
l CONTACTLESS_TAP

addressVerificationResultCode (Optional) A Visa-defined code that describes the result of an address

verification.
Format: String; max length 1 character.

cvv2ResultsCode (Optional) A card verification value 2 (CVV2) verification result.

Format: It is one of the following values:

l M — CVV2 Match, indicates that Visa was able to verify the CVV2
value provided by the wallet provider.
l N — CVV2 No Match, indicates that Visa was not able to verify the
CVV2 value provided by the wallet provider.
l P — Not processed, indicates that Visa was unable to verify the
CVV2 value provided by the wallet provider. This applies for Issuers
opting for CVV2 Bypass only.
l S — CVV2 should be on the card: Indicates that V.I.P. or the issuer
was unable to perform CVV2 verification and notifies the merchant
that the card should contain a CVV2 value.
l U — Issuer is not available, does not participate in the CVV2 Service,
or participates but has not provided Visa with encryption keys:
Indicates that the issuer is notparticipating in the CVV2 Service or
has not provided Visa with encryption keys needed to perform
verification, or that STIP has responded to an issuer-unavailable
response.

consumerEntryMode (Optional) Method of consumer entry.

Format: It is one of the following values:

l KEY_ENTERED
l CAMERA_CAPTURED
l UNKNOWN

locale (Optional) Language in which the app communicates with the

customer. The language and country should be separated using a “_“.
Example: en_US
Format: String; ISO format for language (ISO 639-1) and alpha-2
country code (ISO 3166-1 alpha-2); max length 5 characters.

6 June 2023 Visa Confidential 118

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

deviceInfo (Optional) Data associated with the device.

Format: A Device Information structure.

encryptedData (Required) Blob field that contains the encrypted payload; see
"Cardholder Information" and "Risk Information" in the "Encrypted
Payload Data Structures" chapter for more information.
Format: String; max length 7000 characters.

tokenRequestorTspID (Conditional) Token requestor — token service provider (TR-TSP) ID;

provided by token service providers.
Format: String, numeric; 11 digits.

Device Information

Field Description

deviceID For Secure Element (SE) wallet providers, this value will be the SE ID in
hex binary characters transformed to a 48-character string.
For Host Card Emulation (HCE) wallet providers, this field will be the
Device ID as determined by the digital wallet provider (DWP). All
alphanumeric and special characters are allowed for HCE DWPs.
Secure Element (SE) ID represents the device ID.

l For SE DWPs, this value will be the SE ID in hex binary characters

transformed to a 48-character string.
l For CBP DWPs, this field will be the device ID as determined by the
DWP. All alphanumeric and special characters are allowed for CBP
DWPs.
For Card-on-File (COF) wallets, this value will not be present.
For the initial Check Eligibility request on PAN enrollment, this value
may not be available, however Visa will send this value if it is available.
Format: String; max length 48 characters.

deviceLanguageCode This value is any ISO 639 Version 3 Language Code, for example, eng
(English). This language code will be used by the issuer and Visa to
retrieve the Terms and Conditions (T&C). If T&Cs are not found for the
Language Code in the request, the T&Cs will return the
default :anguage Code of eng (English).
Format: String; ISO-639 Version 3 Language Code, max length 3
characters.

6 June 2023 Visa Confidential 119

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

deviceType Device type.

Format: It is one of the following values:

l UNKNOWN
l MOBILE_PHONE
l TABLET
l WATCH
l MOBILEPHONE_OR_TABLET
l PC
l HOUSEHOLD_DEVICE
l WEARABLE_DEVICE
l AUTOMOBILE_DEVICE

deviceName A readable name for the device. Ideally, the customer enters this name.
It can be used to identify the device in customer support calls.
Example: My Work Phone
Format: String; Base64URL-encoded; UTF-8; max length 128
characters.

deviceNumber Device number.

Format: String; max length 13 characters.

osType Type of operating system.

Format: It is one of the following values:

l ANDROID
l IOS
l WINDOWS
l BLACKBERRY
l TIZEN
l OTHER

osVersion Version of the operating system running on the device.

Example: 4.4.4
Format: String; max length 32 characters.

osBuildID Operating system build identifier.

Example: KTU84M
Format: String; max length 32 characters.

6 June 2023 Visa Confidential 120

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

deviceIDType Attribute indicating the source of the Device ID value.

Example: The source for Device ID (deviceID) could be
SecureElement, TEE, or Derived
Format: String; max length 32 characters.

deviceManufacturer Manufacturer of the device.

Example: Samsung
Format: String; max length 32 characters.

deviceBrand Brand name of the device.

Example: Galaxy
Format: String; max length 32 characters.

deviceModel model of the device.

Example: SGH-T999
Format: String; max length 32 characters.

deviceLocation Obfuscated geographic location of the device. Initially, when

provisioned, this contains the general location of the device.
Information will be supplied with latitude/longitude rounded to the
nearest whole digit.
Example: +37/-121
Format: String; max length 25 characters.

deviceIndex The index number from Visa where the deviceID is stored. This is
required for token device binding.
Format: Integer; max length 2 digits.

deviceIPAddressV4 (Optional) The IP address of the device at the time of the provisioning
request, with the value represented in 255.255.255.255 format. An
octet (255) may be 1–3 digits in length but cannot contain any leading
zeros.
Format: String; max length 15 characters.

locationSource Source used to identify consumer location.

Format: It is one of the following values:

l WIFI
l CELLULAR
l GPS
l OTHER

6 June 2023 Visa Confidential 121

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

tokenProtectionMethod Method of token protection.

Format: It is one of the following values:

l SOFTWARE
l TRUSTED_EXECUTION_ENVIRONMENT
l SECURE_ELEMENT
l CLOUD

originalDeviceID Device ID from the original provision. This field is populated only when
performing token-for-token provisioning and can be used only in the
following APIs:

l Approve Provisioning
l Approve Provisioning Stand-In Notification
l Token Create Notification
Format: String; max length 48 characters.

originalDeviceType Device type from the original provision. This field is populated only
when performing token-for-token provisioning and can be used only
in the following APIs:

l Approve Provisioning
l Approve Provisioning Stand-In Notification
l Token Create Notification
Format: It is one of the following values:

l UNKNOWN
l MOBILE_PHONE
l TABLET
l WATCH
l MOBILEPHONE_OR_TABLET
l PC
l HOUSEHOLD_DEVICE
l WEARABLE_DEVICE
l AUTOMOBILE_DEVICE

6 June 2023 Visa Confidential 122

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Token Information

Field Description

token (Conditional) The account number associated with a token. This is a

required field in the following APIs:

l Token Create Notification

l Token Notification
Format: String; max length 19 characters.

tokenType (Conditional) This is a required field in the following APIs:

l Approve Provisioning
l Approve Provisioning Stand-In Notification
l Token Create Notification
Format: It is one of the following values:

l SECURE_ELEMENT
l HCE
l CARD_ON_FILE
l ECOMMERCE
l QRC

tokenStatus (Conditional) This is a required field in the following APIs:

l Token Create Notification

l Token Notification
Format: It is one of the following values:

l ACTIVE
l INACTIVE
l SUSPENDED
l DEACTIVATED

tokenExpirationDate (Conditional) The date upon which the token is set to expire. This field
is required in the Token Create Notification API.
Format: An Expiration Date structure.

6 June 2023 Visa Confidential 123

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

tokenAssuranceMethod (Optional) Method of Issuer ID&V that has taken place at time of
provisioning, device binding, or cardholder initiated verification. It is
one of the following values:

l 00 ID&V Not Performed

l 10 Card Issuer Account Verification
l 11 Card Issuer Interactive Cardholder Verification - 1 Factor
l 12 Card Issuer Interactive Cardholder Verification - 2 Factor
l 13 Card Issuer Risk Oriented Non-Interactive Cardholder Authenti­
cation
l 14 Card Issuer Asserted Authentication
Format: String; max length 2 characters.

numberOfActiveTokensForPAN (Optional) Number of device tokens that are currently active for this
PAN.
Format: Integer; max length 4 digits.

numberOfInactiveTokensForPAN (Optional) Number of device tokens that are currently inactive (device
tokens have not been activated) for this PAN.
Format: Integer; max length 4 digits.

numberOfSuspendedTokensForPAN (Optional) Number of device tokens that were activated, but are
suspended for payments for this PAN.
Format: Integer; max length 4 digits.

tokenActivationDate (Optional) System date/timestamp, in GMT, of token activation into an

active state. For an inactive state, this field is left empty and populated
only when a token transitions to an active state. If a token is
suspended, this field is populated with the new date/timestamp of
when an active state resumes.
Format: String; yyyy-MM-ddTHH:mm:ss.SSSZ.

tokenDeactivationDate (Optional) Date of token deactivation.

Format: String; YYYY-MM-DD.

lastTokenStatusUpdatedTime (Optional) Date/timestamp, in GMT, of the last token status update.

Format: String; yyyy-MM-ddTHH:mm:ss.SSSZ.

originalToken (Conditional) Token account number. This field is populated when

performing token-for-token provisioning only.
Format: String; max length 19 characters.

originalTokenRequestorID (Required) Unique ID assigned to the initiator of the token request. This
field is populated when performing token-for-token provisioning only.
Format: Numeric; max length 11 digits.

6 June 2023 Visa Confidential 124

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

originalTokenReferenceID (Conditional) Unique ID for the token associated with the PAN. This ID
can be used in lieu of the token for subsequent calls, such as life cycle
events. This field is populated when performing token-for-token
provisioning only.
Format: String; max length 32 characters.

originalTokenType (Conditional) Token type of the original token. This field is populated
only when performing token for token provisioning and can be used
only in the following APIs:

l Approve Provisioning
l Approve Provisioning Stand-In Notification
l Token Create Notification
Format: It is one of the following values:

l SECURE_ELEMENT
l HCE
l CARD_ON_FILE
l ECOMMERCE
l QRC
l PSEUDO_ACCOUNT

originaltokenAssuranceMethod (Conditional) Original token assurance method. This field is populated

when performing token-for-token provisioning only. It is one of the
following values:

l 00 ID&V Not Performed

l 10 Card Issuer Account Verification
l 11 Card Issuer Interactive Cardholder Verification - 1 Factor
l 12 Card Issuer Interactive Cardholder Verification - 2 Factor
l 13 Card Issuer Risk Oriented Non-Interactive Cardholder Authenti­
cation
l 14 Card Issuer Asserted Authentication
Format: String; max length 2 characters.

6 June 2023 Visa Confidential 125

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

tokenRequestorName (Conditional) Token requester name. Populated when available in the

following APIs:

l Device Token Binding Request

l Get Cardholder Verification Methods
l Send Passcode
l Token Notification
Format: String; max length 100 characters.

autoFillIndicator (Conditional) Indicates whether the token is for an autofill use case.
This is a required field in the following APIs:

l Approve Provisioning
l Approve Provisioning Stand-In Notification
l Token Create Notification
Format: It is one of the following values:

l true — Indicates that the token (e-Commerce Enabler, or Card-on-

File) is for an autofill use case.
l false — Indicates that the token is not for an autofill use case.

Response

Successful Response
Successful API responses will return HTTP status code in the 2xx range.

6 June 2023 Visa Confidential 126

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

actionCode Action status codes.

Format: It is one of the following values:

l 00— Unconditional approval (provision and activate immediately

for payments)
l 85— Conditional approval (provision, but do not activate until
additional consumer verification is performed)
Any decline reason code present other than 00 and 85 will prevent
device provisioning.
Decline approval due to one of the following reasons:

l N7— CVV2 Failure

l 14— Invalid PAN
l 54— Invalid Expiration Date
l 05— Generic Decline
l 96— Issuer Internal System Error

errorCode This value will be present in the case of business error codes
ISEXXXXX.
Format: String; max length 8 characters.

addressVerificationResultCode A Visa-defined code that describes the result of an address verification.

Format: String; max length 1 character.

cvv2ResultsCode A card verification value 2 (CVV2) verification result.

Format: It is one of the following values:

l M— CVV2 Match, indicates that Visa was able to verify the CVV2
value provided by the wallet provider.
l N— CVV2 No Match, indicates that Visa was not able to verify the
CVV2 value provided by the wallet provider.
l P— Not processed, indicates that Visa was unable to verify the
CVV2 value provided by the wallet provider. This applies for Issuers
opting for CVV2 Bypass only.
l S — CVV2 should be on the card: Indicates that V.I.P. or the issuer
was unable to perform CVV2 verification and notifies the merchant
that the card should contain a CVV2 value.
l U — Issuer is not available, does not participate in the CVV2 Service,
or participates but has not provided Visa with encryption keys:
Indicates that the issuer is notparticipating in the CVV2 Service or
has not provided Visa with encryption keys needed to perform
verification, or that STIP has responded to an issuer-unavailable
response.

6 June 2023 Visa Confidential 127

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

issuerSpecialConditionCodes Values populated by the issuer and then passed during the step-up API
calls to the issuer.
Format: String; max length 100 characters.

issuerDiscretionaryData If available, includes issuer application and files control data.

Format: A Discretionary Data Information structure.

Error Responses
If a business error is present, it is assumed that no Standard Errors were detected in the API request.
VTS domain-specific business error reason codes are as follows:

HTTP Status Action Code Error Code Error Code Description

200 05 ISE40000 ISS_ERROR_REQUIRED_DATA_MISSING

200 05 ISE40005 ISS_ERROR_INVALID_FIELD_LENGTH

200 05 ISE40006 ISS_ERROR_INVALID_FIELD_TYPE

200 05 ISE40010 ISS_ERROR_CRYPTOGRAPHY_ERROR

200 05 ISE40011 ISS_ERROR_INVALID_FIELD_VALUE

200 96 ISE40504 ISS_ERROR_INTERNAL_SYSTEM_ERROR

200 N7 ISE40106 ISS_ERROR_CVV2_FAILED

200 54 ISE40013 ISS_ERROR_INVALID_EXP_DATE

200 14 ISE40001 ISS_ERROR_PAN_INELIGIBLE

Sample Payloads

Sample Request
{
"panReferenceID": "V-58...65",
"walletAccountEmailAddressHash": "55C...08",
"clientWalletAccountID": "400...30",
"visaTokenScore": null,
"visaTokenDecisioning": null,
"panSource": "KEY_ENTERED",
"addressVerificationResultCode": null,
"cvv2ResultsCode": null,
"consumerEntryMode": null,

6 June 2023 Visa Confidential 128

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

"locale": null,
"encryptedData": "<JWS>",
"deviceInfo": {
"deviceID": null,
"deviceLanguageCode": "eng",
"deviceType": null,
"deviceName": null,
"deviceNumber": null,
"osType": null,
"osVersion": null,
"osBuildID": null,
"deviceIDType": null,
"deviceManufacturer": null,
"deviceBrand": null,
"deviceModel": null,
"deviceLocation": null,
"deviceIPAddressV4": "...",
"locationSource": null,
"tokenProtectionMethod": "CLOUD",
"deviceIndex": null
},
"lifeCycleTraceID": 381...69,
"tokenRequestorTspID": "400...41",
"tokenInfo": {
"token": "...",
"tokenType": "CARD_ON_FILE",
"tokenStatus": null,
"tokenExpirationDate": "...",
"tokenAssuranceMethod": "",
"numberOfActiveTokensForPAN": ...,
"numberOfInactiveTokensForPAN": ...,
"numberOfSuspendedTokensForPAN": ...,
"originalToken": "...",
"originaltokenAssuranceMethod": null,
"originalTokenRequestorID": null,
"originalTokenReferenceID": null
}
}

All JWS and JWE elements are Base64URL-encoded.

JWS:
<JWS Header>.<JWS Payload>.<JWS Signature>
JWS payload:
<JWE>
JWE:

<Header>.<Encrypted Key>.<Initialization Vector>.<Ciphertext>.

<Authentication Tag>

6 June 2023 Visa Confidential 129

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Decrypted data contained in JWE Ciphertext element:

{
“cardholderInfo”:{
“primaryAccountNumber”: “”,
“cvv2”: “”,
“name”: “”,
“expirationDate”: {
“month”: “”,
“year”: “”
},
“billingAddress”:{
“line1”: “”,
“line2”: “”,
“city”: “”,
“state”: “”,
“country”: “”,
“postalCode”: “”
},
“highValueCustomer”: “”,
“riskAssessmentScore”: “”
},
“riskInformation”: {
“walletProviderRiskAssessment”: “”,
“walletProviderRiskAssessmentVersion”: “”,
“walletProviderAccountScore”: “”,
“walletProviderDeviceScore”: “”,
“walletProviderReasonCodes”: “”,
“deviceBluetoothMac”: “”,
“deviceIMEI”: “”,
“deviceSerialNumber”: “”,
“deviceTimeZone”: “”,
“deviceTimeZoneSetting”: “”,
“osID”: “”,
“simSerialNumber”: “”,
“deviceLostMode”: “”,
“daysSinceConsumerDataLastAccountChange”: “”,
“accountHolderName”: “”,
“walletProviderPANAge”: “”,
“walletAccountHolderCardNameMatch”: “”,
“accountToDeviceBindingAge”: “”,
“userAccountFirstCreated”: “”,
“provisioningAttemptsOnDeviceIn24Hours”: “”,
“distinctCardholderNames”: “”,
“deviceCountry”: “”,
“walletAccountCountry”: “”,
“suspendedCardsInAccount”: “”,
“daysSinceLastAccountActivity”: “”,
“numberOfTransactionsInLast12months”: “”,
“numberOfActiveTokens”: “”,
“deviceWithActiveTokens”: “”,
“activeTokensOnAllDeviceForAccount”:“”,
“visaTokenScore”: “”,
“visaTokenDecisioning”: “”
}
}

6 June 2023 Visa Confidential 130

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Sample Successful Response

{
“actionCode”: “00”,
“addressVerificationResultCode”: “”,
“cvv2ResultsCode”: “”
}

Approve Provisioning Stand-In

Notification
This API is invoked during the token provisioning flow on a device. Visa invokes this API call to the
issuer with ID&V attributes and other relevant stand-in (STIP) attributes when the Approve
Provisioning API fails on the issuer.

Request

Endpoints

Path:

{Issuer Endpoint}/vtis/v2/tokenRequestors/
{tokenRequestorID}/tokens/{tokenReferenceID}/tokenChanged?
eventType=eventType

URL Parameters

Parameter Description

{tokenRequestorID} (Required) Unique ID assigned to the initiator of the token request.

Format: Numeric, max length 11 digits.

{tokenReferenceID} (Required) Unique ID for the token associated with the PAN. This ID can
be used in lieu of the token for subsequent calls, such as lifecycle
events.
Format: String; max length 32 characters.

Method
POST

6 June 2023 Visa Confidential 131

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Query Parameters

Event Type — Token Activation in STIP

Parameter Description

eventType (Required) Event type.

Format: It is one of the following values:

l TOKEN_ACTIVATION_STIP
–token activation occurred in STIP mode

Request Body

Field Description

panReferenceID (Required) Unique ID for the PAN. This ID can be used in lieu of PAN for
subsequent calls, such as lifecycle events.
Format: String, max length 32 characters.

lifeCycleTraceID (Required) A message identifier that can be used to link some

messages associated with a provisioning request. This should be used
by the issuer in event/message logging.
Format: Integer; max length 15 digits.

walletAccountEmailAddressHash (Required) Hash of email address that is linked to the wallet account
login ID.
Format: String; max length 64 characters.

clientWalletAccountID (Required) Consumer ID that identifies the Wallet Account Holder

entity. This is provided by the client or, in some cases, by Visa.
Format: String; max length 32 characters.

panSource (Required) Source of PAN.

Format: It is one of the following values:

l KEY_ENTERED
l ON_FILE
l MOBILE_BANKING_APP
l TOKEN
l CHIP_DIP
l CONTACTLESS_TAP

addressVerificationResultCode (Optional) A Visa-defined code that describes the result of an address

verification.
Format: String; max length 1 character.

6 June 2023 Visa Confidential 132

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

cvv2ResultsCode (Optional) A card verification value 2 (CVV2) verification result.

Format: It is one of the following values:

l M— CVV2 Match, indicates that Visa was able to verify the CVV2
value provided by the wallet provider.
l N— CVV2 No Match, indicates that Visa was not able to verify the
CVV2 value provided by the wallet provider.
l P— Not processed, indicates that Visa was unable to verify the
CVV2 value provided by the wallet provider. This applies for Issuers
opting for CVV2 Bypass only.
l S — CVV2 should be on the card: Indicates that V.I.P. or the issuer
was unable to perform CVV2 verification and notifies the merchant
that the card should contain a CVV2 value.
l U — Issuer is not available, does not participate in the CVV2 Service,
or participates but has not provided Visa with encryption keys:
Indicates that the issuer is notparticipating in the CVV2 Service or
has not provided Visa with encryption keys needed to perform
verification, or that STIP has responded to an issuer-unavailable
response.

consumerEntryMode (Optional) Method of consumer entry.

Format: It is one of the following values:

l KEY_ENTERED
l CAMERA_CAPTURED
l UNKNOWN

locale (Optional) Language in which the app communicates with the

customer. The language and country should be separated using a “_“.
Example: en_US
Format: String; ISO format for language (ISO 639-1) and alpha-2
country code (ISO 3166-1 alpha-2); max length 5 characters.

deviceInfo (Optional) Data associated with the device.

Format: A Device Information structure.

encryptedData (Required) Blob field that contains the encrypted payload; see
"Cardholder Information," "Token Information," and "Risk Information"
in the "Encrypted Payload Data Structures" chapter for more
information.
Format: String; max length 7000 characters.

6 June 2023 Visa Confidential 133

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

actionCode (Required) Action code.

Format: It is one of the following values:

l 00— Unconditional approval (provision and activate immediately

for payments)
l 85— Conditional approval (provision, but do not activate until
additional consumer verification is performed)
Any decline reason code present other than 00 and 85 will prevent
device provisioning.
Decline approval due to one of the following reasons:

l N7— CVV2 Failure

l 14— Invalid PAN
l 54— Invalid Expiration Date
l 05— Generic Decline
l 96— Issuer Internal System Error

stipReasonCode (Required) This field contains a code that identifies why STIP responded
for the issuer.
Format: It is one of the following values:

l 9011— The line to issuer is down.

l 9012— Forced STIP because of N0 (Force STIP) original response
from issuer.
l 9020— Issuer Time Out.
l 9027— ECIP RTD Decline. Sent by CVV2 or RTD upon decline.
l 9203— Decline due to Office of Foreign Assets Control (OFAC)
embargo.
l 9206— Mod-10 check failure.
l 9208— Declined because issuing identifier and/or routing identifier
is blocked.
l 9210— Declined because of issuer participation options.
l 9212— Declined due to fraud condition.
l 9216— Ineligible data for Token Type. Token is not a device-based
one.
l 9217— Loyalty personalized data input is incorrect.
l 9061— Switch Detected Error. Sent by Visa by default.

6 June 2023 Visa Confidential 134

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

dateTimeOfEvent (Required) Event date/timestamp in GMT.

Format: String; yyyy-MM-ddTHH:mm:ss.SSSZ.

tokenRequestorTspID (Conditional) Token requestor — token service provider (TR-TSP) ID;

provided by token service providers.
Format: String, numeric; 11 digits.

Response

Successful Response
Successful API responses returns an HTTP 200 status code with no response payload.

Error Responses
The notification API is an asynchronous API and does not need the issuer to return anything to Visa.
The issuer returns the following error statuses as appropriate with no response payload in addition to
the “Standard Errors”.

HTTP Status HTTP Reason Code Description

400 Bad Request The request could not be understood by the server due to
malformed syntax. The client should not repeat the request
without modifications.

401 Unauthorized Authentication credentials were missing or incorrect.

404 Not Found The server has not found anything matching the Request URI.

500 Internal Server Error An unspecified server error has occurred. Visa should attempt to
retry or contact issuer support.

Sample Payloads

Sample Request
{
"panReferenceID": "V-5...45",
"walletAccountEmailAddressHash": "729...76",
"clientWalletAccountID": "Yqc...MK",

6 June 2023 Visa Confidential 135

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

"visaTokenScore": "19",
"visaTokenDecisioning": "00",
"panSource": "ON_FILE",
"encryptedData": "eyJ...iQ",
"deviceInfo": {
"deviceLanguageCode": "spa",
"tokenProtectionMethod": "CLOUD"
},
"lifeCycleTraceID": 380...56,
"stipReasonCode": "9020",
"actionCode": "00",
"dateTimeOfEvent": "2020-07-17T22:08:16.000Z"
}

All JWS and JWE elements are Base64URL-encoded.

JWS:
<JWS Header>.<JWS Payload>.<JWS Signature>
JWS payload:
<JWE>
JWE:

<Header>.<Encrypted Key>.<Initialization Vector>.<Ciphertext>.

<Authentication Tag>

Decrypted data contained in JWE ciphertext element:

{
“tokenInfo”: {
“tokenType”: “”,
“tokenAssuranceMethod”: “”,
“numberOfActiveTokensForPAN”: “”,
“numberOfInactiveTokensForPAN”: “”,
“numberOfSuspendedTokensForPAN”: “”
},
“cardholderInfo”:{
“primaryAccountNumber”:“”,
“cvv2”: “”,
“name”: “”,
“expirationDate”: {
“month”: “”,
“year”: “”
“billingAddress”:{
“line1”: “”,
“line2”: “”,
“city”: “”,
“state”: “”,
“country”: “”,
“postalCode”: “”
},
“highValueCustomer”: “”,
“riskAssessmentScore”: “”

6 June 2023 Visa Confidential 136

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

},
“riskInformation”: {
“walletProviderRiskAssessment”: “”,
“walletProviderRiskAssessmentVersion”: “”,
“walletProviderAccountScore”: “”,
“walletProviderDeviceScore”: “”,
“walletProviderReasonCodes”: “”,
“deviceBluetoothMac”: “”,
“deviceIMEI”: “”,
“deviceSerialNumber”: “”,
“deviceTimeZone”: “”,
“deviceTimeZoneSetting”: “”,
“osID”: “”,
“simSerialNumber”: “”,
“deviceLostMode”: “”,
“daysSinceConsumerDataLastAccountChange”: “”,
“accountHolderName”: “”,
“walletProviderPANAge”: “”,
“walletAccountHolderCardNameMatch”: “”,
“accountToDeviceBindingAge”: “”,
“userAccountFirstCreated”: “”,
“provisioningAttemptsOnDeviceIn24Hours”: “”,
“distinctCardholderNames”: “”,
“deviceCountry”: “”,
“walletAccountCountry”: “”,
“suspendedCardsInAccount”: “”,
“daysSinceLastAccountActivity”: “”,
“numberOfTransactionsInLast12months”: “”,
“numberOfActiveTokens”: “”,
“deviceWithActiveTokens”: “”,
“activeTokensOnAllDeviceForAccount": “”
“visaTokenScore”: “”,
“visaTokenDecisioning”: “”
}
}

Successful Response
Successful API responses returns an HTTP 200 status code with no response payload.

Card Metadata Update Notification

Visa will invoke this API on the issuer side upon receiving a notification from the wallet provider of
the status of the card metadata update on the device. This is only supported for the SE wallet
provider.

Request

6 June 2023 Visa Confidential 137

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Endpoints

Path:

{Issuer Endpoint}/vtis/v1/tokenRequestors/
{tokenRequestorID}/tokens/{tokenReferenceID}/notification?
eventType=eventType

URL Parameters

Parameter Description

{tokenRequestorID} (Required) Unique ID assigned to the initiator of the token request.

Format: Numeric; max length 11 digits.

{tokenReferenceID} (Required) Unique ID for the token associated with the PAN. This ID can
be used in lieu of the token for subsequent calls, such as life cycle
events.
Format: String; max length 32 characters.

Method
POST

Query Parameters

Event Type — Card Metadata Updated

Parameter Description

eventType (Required) Event type.

Format: It is one of the following values:

l CARD_METADATA_UPDATED
– PAN updated

6 June 2023 Visa Confidential 138

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Request Body

Field Description

taskID (Required) GUID with hyphens. The issuer needs to store this for future
references.
Format: String; max length 36 characters.

statusCode (Conditional) Action status code.

Format: It is one of the following values:

l SUCCESS
l FAILURE

errorCode (Required) This is present for business error codes VSEXXXXX.

Format: String; max length 8 characters.

Visa Token Service (VTS) domain-specific business error reason codes are as follows:

HTTP Status Error Code Error Code Description

400 VSE40001 VSE_ERROR_REQUIRED_DATA_MISSING

400 VSE40000 VSE_ERROR_INVALID_DATA

400 VSE40005 VSE_ERROR_INVALID_TASKID

400 VSE40009 VSE_INTERNAL_SYSTEM_ERROR

Response

Successful Response
Successful API responses will return HTTP 200 status code with no response payload.

Error Response
The notification API is an asynchronous API and does not need the issuer to return anything to Visa.
The issuer returns the following error statuses as appropriate with no response payload in addition to
the Standard Errors.

6 June 2023 Visa Confidential 139

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

HTTP Code HTTP Reason Code Description

400 Bad Request The request could not be understood by the server because of
malformed syntax. The client should not repeat the request until
modifications have been made.

401 Unauthorized Authentication credentials were missing or incorrect.

404 Not Found The server has not found anything matching the Request URI.

500 Internal Server Error An unspecified server error has occurred. Visa should attempt to
retry or contact issuer support.

Sample Payloads

Sample Successful Request

{
“taskID”: “ed3 91”,
“statusCode”: “SUCCESS”
}

Sample Successful Request With Business Error

{
“taskID”: “ed3...91”,
“statusCode”: “FAILURE”,
“errorCode”: “VSE40008”
}

Check Eligibility
This API is invoked during the token provisioning flow on a device. Visa invokes this API call to the
issuer with ID&V attributes and other relevant attributes so that the issuer can take appropriate
action, such as approve or decline, based on those attributes to provision the token.
This service allows issuers to:
l Pre-screen the cardholder who is about to start provisioning of tokens to a digital wallet.
l Provide reference to Card Art and Terms & Conditions (T&Cs) for a specific cardholder PAN.
l Deliver Token Reference ID that can be used by the issuers in subsequent calls to Visa, for
example, in Token Lifecycle control APIs, instead of using the token value.

6 June 2023 Visa Confidential 140

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

The three functions of API described above are optional; the issuer may opt to participate in this API
integration for a subset of the described functions. Because participation in this API is optional, the
issuer may decide to provide all required information to Visa so that Visa can perform On-Behalf
processing.
Alternate Flow: STIP Processing
If the issuer system does not respond with a response message within the required timeframe or
issuer returns ISE40504 error code, Visa systems will determine if the card is eligible for tokenization
and if so, will return the issuer-defined card art and Terms and Conditions (T&C) to the wallet
provider on behalf of the issuer.
Note:  
If there are no pre-configured card metadata for the corresponding card being enrolled, the
enrollment will be declined to the wallet provider.

Request

Endpoints

Path:
{Issuer Endpoint}/vtis/v1/checkEligibility

Method
POST

Request Body
In the case of a provisioning flow, tokenRequestorID, tokenReferenceID, and
panReferenceID must always be present.

Field Description

tokenRequestorID (Conditional) Unique ID assigned to the initiator of the token request.

Format: Numeric; max length 11 digits.

tokenReferenceID (Conditional) Unique ID for the token associated with the PAN. This ID
can be used in lieu of the token for subsequent calls, such as lifecycle
events.
Format: String; max length 32 characters.

6 June 2023 Visa Confidential 141

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

panReferenceID (Conditional) Unique ID for the PAN. This ID can be used in lieu of PAN
for subsequent calls, such as lifecycle events.
Format: String; max length 32 characters.

lifeCycleTraceID (Required) A message identifier that can be used to link some

messages associated with a provisioning request. This should be used
by the issuer in event/message logging.
Format: Integer; max length 15 digits.

panSource (Required) Source of the PAN.

Format: It is one of the following values:

l KEY_ENTERED
l ON_FILE
l MOBILE_BANKING_APP
l TOKEN
l CHIP_DIP
l CONTACTLESS_TAP

deviceInfo (Optional) Data associated with the device.

Format: It is one of the following values, if populated:

l deviceID
l deviceLanguageCode
Format: A Device Information structure.

encryptedData (Required) Blob field that contains the encrypted payload; see
"Cardholder Information" in the "Encrypted Payload Data Structures"
chapter for more information. Only primaryAccountNumber needs
to be provided in cardholderInfo.
Format: String; max length 7000 characters.

Response

Successful Response
Successful API responses will return HTTP status code in the 2xx range. The response body, if
available, will contain the response of the API as described in this specification.

6 June 2023 Visa Confidential 142

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

errorCode This is present in the case of business error ISEXXXXX codes. Required
for Decline.
Format: String; max length 8 characters.

cardMetadataInfo A Card Metadata Information structure.

Card Metadata Information

Field Description

cardIssuer (Optional) Card issuer name.

Format: String; max length 128 characters.

foregroundColor (Optional) Foreground color of the Digital Wallet entry for the card.
Specified as a CSS style RGB triple. This value is optional in this API
because the issuer may pre-configure this value via Visa Card Art
Management (VCMM).
Example: rgb(255,122,235)
Format: String; max length 32 characters.

backgroundColor (Optional) Background color of the Digital Wallet UI entry (“space”) for
the card. Specified as a CSS style RGB triple. It is optional in this API
because the issuer may pre-configure this value via VCMM
Example: rgb(255,122,235)
Format: String; max length 32 characters.

labelColor (Optional) Label color of the Digital Wallet entry for the card. Specified
as a CSS style RGB triple. It is optional in this API because the issuer
may pre-configure this value via VCMM.
Example: rgb(255,122,235)
Format: String; max length 32 characters.

shortDescription (Optional) A short description of the card. May be used with lock-
screen notifications.
Example: The Bank Card
Format: String; max length 32 characters.

longDescription (Optional) Longer description of the card. May be used inside the
Digital Wallet.
Example: The Bank Signature Rewards Card
Format: String; max length 64 characters.

6 June 2023 Visa Confidential 143

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

profileID (Conditional) Profile ID associated with the card. Only applicable for
issuers who opt for the Check Eligibility API service. During the pre-
loading of Card Metadata into the Visa system, either via Visa Card Art
Management UI (VCMM) or the Batch file Interface, issuers have an
option to assign their own unique profile ID (GUID) to a set of card
metadata.
Example: 12c7bc...
In this example:

1. The profile ID is assigned.

2. Issuers populate the profile ID in the Check Eligibility Response or
the Update Card Metadata Request.
3. Visa retrieves all the card metadata associated with the Profile ID
received in the Check Eligibility Response, or the Update Card
Metadata Request, and sends it to the DWP.
When a profile ID is used, no other card metadata elements are
required to be sent to Visa in the messages.
Format: String; lowercase, hexadecimal, hyphens (-) are not allowed;
max length 32 characters.

cardArtData (Optional) Card art data.

Format: An array of card art reference IDs in a cardArtRefID
structure; see Card Art Details.

termsAndConditionsID (Optional) GUID-based file name for Terms and Conditions text. File
used by the issuer while loading the image in VCMM. This is a DWP
required field. However, it is optional in this API because the issuer can
pre-configure this value via VCMM. This value is not applicable for
Check Eligibility; only available for Update Card Metadata.
Format: String; max length 64 characters.

privacyPolicyURL (Optional) URL pointing to an issuing bank’s privacy policy. This value is
nott applicable for Check Eligibility; only available for Update Card
Metadata.
Format: String; max length 128 characters.

termsAndConditionsURL (Optional) URL pointing to the issuing bank’s terms and conditions for
a card. This value is not applicable for Check Eligibility; only available
for Update Card Metadata.
Format: String; max length 128 characters.

contactInfo (Optional) Contact information.

Format: A Contact Information structure.

applicationInfo (Optional) Applicaton information.

Format: A Card Metadata Application Information structure.

6 June 2023 Visa Confidential 144

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Card Art Data Details

Field Description

cardArtRefID (Conditional) GUID-based file names for Cart Art Image file used by
the issuer while loading the image in VCMM. Required by DWP-
required field; it is optional in this API because the issuer can pre-
configure this value via VCMM.
Format: An array of GUID-based file names; max length 32 characters.

Card Metadata Application Information

Field Description

supportsTokenNotifications (Optional) Indicates whether the card supports token notifications for
transactions originating on the device.
Format: It is one of the following values:

l true
l false

supportsFPANNotifications (Optional) Indicates whether the card supports FPAN notifications for
all transactions that point back to the FPAN. Not applicable for Check
Eligibility; only available for Update Card Metadata.
Format: It is one of the following values:

l true
l false

transactionServiceURL (Optional) Transaction history URL (Transaction Details) of the issuer’s

web service. Not applicable for Check Eligibility; only available for
Update Card Metadata.
Format: String; max length 128 characters.

messageServiceURL (Optional) URL of the message/offer web service that conforms to the
API as described to PNOs and issuers in the Card Notification Services
API Specification. Not applicable for Check Eligibility; only available for
Update Card Metadata.
Format: String; max length 128 characters.

transactionPushTopic (Conditional) A push topic the issuer uses to notify the device that new
transactions are available. Not applicable for Check Eligibility; only
available for Update Card Metadata.
Format: String; max length 128 characters.

messagePushTopic (Conditional) A push topic the notification provider uses to notify the
device that new messages are available. Not applicable for Check
Eligibility; only available for Update Card Metadata.
Format: String; max length 128 characters.

6 June 2023 Visa Confidential 145

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

appLaunchURL (Optional) URL passed to the associated issuer mobile app when
launching it. If this key is present, the
associatedStoreIdentifiers key must also be present. This
field is not applicable for Check Eligibility; only for Update Card
Metadata.

Format: String; max length 128 characters.

appLaunchURLScheme (Optional) URL scheme that the application is registered for, in order to
deep link from transaction notifications and show all transaction notifi­
cations. The Application ID must be included in the
associatedApplicationsIdentifiers array and the application
itself must register for the URL scheme specified in this key. This field is
not applicable for Check Eligibility; only for Update Card Metadata.

Format: String; max length 32 characters.

associatedStoreIdentifiers (Optional) A list of mobile application store item identifiers for

associated issuer mobile banking application. Format is specific to a
mobile store/phone platform. Only one item in the list is used: the first
item identifier for an application compatible with the current device.
This field is not applicable for Check Eligibility; only for Update Card
Metadata.

l If the application is not installed, the link opens the mobile

application store and shows the application.
l If the application is already installed, the link launches it (this only
applies to SE DWPs).
Format: String; max length 20 characters.

associatedApplicationIdentifiers (Optional) An array of associated app identifiers. Similar to

associatedStoreIdentifiers, but explicit App IDs (only
applicable to SE DWPs). This field is not applicable for Check Eligibility;
only for Update Card Metadata.
Format: String; max length 128 characters.

Contact Information

Field Description

contactWebsite (Optional) Customer Service website of the issuing bank.

Format: String; max length 128 characters.

contactEmail (Optional) Customer Service email address of the issuing bank.

Format: String; max length 32 characters.

6 June 2023 Visa Confidential 146

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

contactNumber (Optional) Customer Service phone number of the issuing bank.

Format: String; max length 32 characters.

contactName Name of the issuing bank. It may be used in combination with other
text strings.
Example: If contactName is “XYZ Bank”, it may be used to construct
a string such as “Contact XYZ Bank”, or “XYZ Bank Contact
Information”.
Format: String; max length 32 characters.

Error Responses
If a business error is present, it is assumed that no Standard Errors were detected in the API request.
VTS domain-specific business error reason codes are as follows:

HTTP Status Error Code Error Code Description

200 ISE40000 ISS_ERROR_REQUIRED_DATA_MISSING

200 ISE40001 ISS_ERROR_INVALID_PAN

200 ISE40003 ISS_ERROR_INVALID_CARD_TYPE

200 ISE40005 ISS_ERROR_INVALID_FIELD_LENGTH

200 ISE40006 ISS_ERROR_INVALID_FIELD_TYPE

200 ISE40010 ISS_ERROR_CRYPTOGRAPHY_ERROR

200 ISE40011 ISS_ERROR_INVALID_FIELD_VALUE

200 ISE40101 ISS_ERROR_PAN_INELIGIBLE

200 ISE40504 ISS_ERROR_INTERNAL_SYSTEM_ERROR

200 ISE40505 ISS_ERROR_SUSPECTED_FRAUD

200 ISE40506 ISS_ERROR_CARD_EXPIRED

200 ISE40507 ISS_ERROR_REPLACEMENT_CARD_ISSUED

200 ISE40300 ISS_ERROR_AUTH_FAILED

Sample Payloads

6 June 2023 Visa Confidential 147

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Sample Request
{
"tokenRequestorID": 400...20,
"tokenReferenceID": "DNI...46",
"panReferenceID": "V-5...71",
"panSource": "KEY_ENTERED",
"deviceInfo": {
"deviceLanguageCode": "eng"
},
"encryptedData": "eyJ...UQ"
}

All JWS and JWE elements are Base64URL-encoded.

JWS:
<JWS Header>.<JWS Payload>.<JWS Signature>
JWS payload:
<JWE>
JWE:

<Header>.<Encrypted Key>.<Initialization Vector>.<Ciphertext>.

<Authentication Tag>

The following structure shows the encryptedData field before encryption:

{
"primaryAccountNumber": "...",
"name": "...",
"expirationDate": {
"month": "...",
"year": "..."
},
"highValueCustomer": false,
"riskAssessmentScore": "3"
}

Additional Sample Request

{
"tokenRequestorID": 400...24,
"tokenReferenceID": "DNI...58",
"panReferenceID": "V-3...64",
"panSource": "ON_FILE",
"lifeCycleTraceID": 382...01,
"deviceInfo": {
"deviceLanguageCode": "fin"
},
"encryptedData": "..."
}

6 June 2023 Visa Confidential 148

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Sample Successful Response

{
"cardMetadataInfo": {
"foregroundColor": "rgb(255,255,255)",
"backgroundColor": "rgb(255,255,255)",
"labelColor": "rgb(255,255,255)",
"shortDescription": "Fifth Group",
"longDescription": "Fifth Group",
"cardIssuer": "ieadmin",
"cardArtData": {
"cardArtRefID": [
"ak0...jk",
"bk0...jk",
"ck0...jk",
"k04...jk"
]
},
"termsAndConditionsID": "32e...75",
"contactInfo": {
"contactWebsite": "https://issuer.com",
"contactNumber": "800-000-0000",
"contactName": "issuer",
"contactEmail": "[email protected]"
},
"applicationInfo": {
"supportsTokenNotifications": true
}
}
}

Response with Profile ID

{
"cardMetadataInfo": {
"profileID": "226...21"
}
}

Sample Business Error Response

{
“errorCode”: “ISE40000”
}

Device Token Binding Request

This API is invoked to bind an ECOM/COF token to a device.

6 June 2023 Visa Confidential 149

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Request

Endpoints

Path:

{Issuer Endpoint}/vtis/v1/tokenRequestors/
{tokenRequestorID}/tokens/{tokenReferenceID}/deviceBinding

URL Parameters

Parameter Description

{tokenRequestorID} (Required) Unique ID assigned to the initiator of the token request.

Format: Numeric; max length 11 digits.

{tokenReferenceID} (Required) Unique ID for the token associated with the PAN. Can be
used in lieu of the token for subsequent calls, such as lifecycle events.
Format: String; max length 32 characters.

Method
POST

Request Body

Field Description

panReferenceID (Required) Unique ID for the PAN. This ID can be used in lieu of PAN for
the subsequent calls, such as life cycle events.
Format: String; max length 32 characters

walletAccountEmailAddressHash (Required) Hash of email address linked to their wallet account login.
Format: String; max length 64 characters.

clientWalletAccountID (Required) Consumer ID identifying the wallet account-holder entity.

This is provided by the client or, in some cases, by Visa.
Format: String; max length 32 characters

locale (Optional) Language in which the app communicates with the

customer. The language and country should be separated using a “_“.
Example: en_US
Format: String; ISO format for language (ISO 639-1) and alpha-2
country code (ISO 3166-1 alpha-2); max length 5 characters.

6 June 2023 Visa Confidential 150

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

deviceInfo (Required) Data associated with the device. At least, deviceIndex

and deviceID will be provided.
Format: A Device Information structure.

tokenUserInfo (Future) Information of the user that has requested the device binding.
Format: A Token User Information structure.

merchantInfo (Future) Information of the merchant that has requested the device
binding.
Format: A Merchant Information structure.

tokenInfo (Required) Token information. Use the tokenInfo structure in the

encryptedData field instead.
Deprecated
Important:   The tokenInfo structure outside of
encryptedData has been deprecated and Visa intends to
sunset it with the April, 2024 release, at which time it will no
longer be available.
Format: A tokenInfo structure.

encryptedData (Required) Blob field that can contain a tokenInfo structure. Decrypt
the blob and use the token information structure therein.
Format: String blob; max length 7000 characters

Token Information

Field Description

token (Conditional) The account number associated with a token. This is a

required field in the following APIs:

l Token Create Notification

l Token Notification
Format: String; max length 19 characters.

tokenType (Conditional) This is a required field in the following APIs:

l Approve Provisioning
l Approve Provisioning Stand-In Notification
l Token Create Notification
Format: It is one of the following values:

l SECURE_ELEMENT
l HCE
l CARD_ON_FILE
l ECOMMERCE
l QRC

6 June 2023 Visa Confidential 151

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

tokenStatus (Conditional) This is a required field in the following APIs:

l Token Create Notification

l Token Notification
Format: It is one of the following values:

l ACTIVE
l INACTIVE
l SUSPENDED
l DEACTIVATED

tokenExpirationDate (Conditional) The date upon which the token is set to expire. This field
is required in the Token Create Notification API.
Format: An Expiration Date structure.

tokenAssuranceMethod (Optional) Method of Issuer ID&V that has taken place at time of
provisioning, device binding, or cardholder initiated verification. It is
one of the following values:

l 00 ID&V Not Performed

l 10 Card Issuer Account Verification
l 11 Card Issuer Interactive Cardholder Verification - 1 Factor
l 12 Card Issuer Interactive Cardholder Verification - 2 Factor
l 13 Card Issuer Risk Oriented Non-Interactive Cardholder Authenti­
cation
l 14 Card Issuer Asserted Authentication
Format: String; max length 2 characters.

numberOfActiveTokensForPAN (Optional) Number of device tokens that are currently active for this
PAN.
Format: Integer; max length 4 digits.

numberOfInactiveTokensForPAN (Optional) Number of device tokens that are currently inactive (device
tokens have not been activated) for this PAN.
Format: Integer; max length 4 digits.

numberOfSuspendedTokensForPAN (Optional) Number of device tokens that were activated, but are
suspended for payments for this PAN.
Format: Integer; max length 4 digits.

tokenActivationDate (Optional) System date/timestamp, in GMT, of token activation into an

active state. For an inactive state, this field is left empty and populated
only when a token transitions to an active state. If a token is
suspended, this field is populated with the new date/timestamp of
when an active state resumes.
Format: String; yyyy-MM-ddTHH:mm:ss.SSSZ.

6 June 2023 Visa Confidential 152

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

tokenDeactivationDate (Optional) Date of token deactivation.

Format: String; YYYY-MM-DD.

lastTokenStatusUpdatedTime (Optional) Date/timestamp, in GMT, of the last token status update.

Format: String; yyyy-MM-ddTHH:mm:ss.SSSZ.

originalToken (Conditional) Token account number. This field is populated when

performing token-for-token provisioning only.
Format: String; max length 19 characters.

originalTokenRequestorID (Required) Unique ID assigned to the initiator of the token request. This
field is populated when performing token-for-token provisioning only.
Format: Numeric; max length 11 digits.

originalTokenReferenceID (Conditional) Unique ID for the token associated with the PAN. This ID
can be used in lieu of the token for subsequent calls, such as life cycle
events. This field is populated when performing token-for-token
provisioning only.
Format: String; max length 32 characters.

originalTokenType (Conditional) Token type of the original token. This field is populated
only when performing token for token provisioning and can be used
only in the following APIs:

l Approve Provisioning
l Approve Provisioning Stand-In Notification
l Token Create Notification
Format: It is one of the following values:

l SECURE_ELEMENT
l HCE
l CARD_ON_FILE
l ECOMMERCE
l QRC
l PSEUDO_ACCOUNT

6 June 2023 Visa Confidential 153

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

originaltokenAssuranceMethod (Conditional) Original token assurance method. This field is populated

when performing token-for-token provisioning only. It is one of the
following values:

l 00 ID&V Not Performed

l 10 Card Issuer Account Verification
l 11 Card Issuer Interactive Cardholder Verification - 1 Factor
l 12 Card Issuer Interactive Cardholder Verification - 2 Factor
l 13 Card Issuer Risk Oriented Non-Interactive Cardholder Authenti­
cation
l 14 Card Issuer Asserted Authentication
Format: String; max length 2 characters.

tokenRequestorName (Conditional) Token requester name. Populated when available in the

following APIs:

l Device Token Binding Request

l Get Cardholder Verification Methods
l Send Passcode
l Token Notification
Format: String; max length 100 characters.

autoFillIndicator (Conditional) Indicates whether the token is for an autofill use case.
This is a required field in the following APIs:

l Approve Provisioning
l Approve Provisioning Stand-In Notification
l Token Create Notification
Format: It is one of the following values:

l true — Indicates that the token (e-Commerce Enabler, or Card-on-

File) is for an autofill use case.
l false — Indicates that the token is not for an autofill use case.

Device Information
This structure is used by several APIs.

6 June 2023 Visa Confidential 154

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

deviceID (Conditional) For Secure Element (SE) wallet providers, this value will be
the SE ID in hex binary characters transformed to a 48-character string.
For Host Card Emulation (HCE) wallet providers, this field will be the
Device ID as determined by the digital wallet provider (DWP). All
alphanumeric and special characters are allowed for HCE DWPs.
Secure Element (SE) ID represents the device ID.

l For SE DWPs, this value will be the SE ID in hex binary characters

transformed to a 48-character string.
l For CBP DWPs, this field will be the device ID as determined by the
DWP. All alphanumeric and special characters are allowed for CBP
DWPs.
For Card-on-File (COF) wallets, this value will not be present.
For the initial Check Eligibility request on PAN enrollment, this value
may not be available, however Visa will send this value if it is available.
Format: String; max length 48 characters.

deviceLanguageCode (Optional) This value is any ISO 639 Version 3 Language Code, for
example, eng (English). This language code will be used by the issuer
and Visa to retrieve the Terms and Conditions (T&C). If T&Cs are not
found for the Language Code in the request, the T&Cs will return the
default :anguage Code of eng (English).
Format: String; ISO-639 Version 3 Language Code, max length 3
characters.

deviceType (Optional) Device type.

Format: It is one of the following values:

l UNKNOWN
l MOBILE_PHONE
l TABLET
l WATCH
l MOBILEPHONE_OR_TABLET
l PC
l HOUSEHOLD_DEVICE
l WEARABLE_DEVICE
l AUTOMOBILE_DEVICE

deviceName (Optional) A readable name for the device. Ideally, the customer enters
this name. It can be used to identify the device in customer support
calls.
Example: My Work Phone
Format: String; Base64URL-encoded; UTF-8; max length 128
characters.

6 June 2023 Visa Confidential 155

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

deviceNumber (Optional) Device number.

Format: String; max length 13 characters.

osType (Optional) Type of operating system.

Format: It is one of the following values:

l ANDROID
l IOS
l WINDOWS
l BLACKBERRY
l TIZEN
l OTHER

osVersion (Optional) Version of the operating system running on the device.

Example: 4.4.4
Format: String; max length 32 characters.

osBuildID (Optional) Operating system build identifier.

Example: KTU84M
Format: String; max length 32 characters.

deviceIDType (Optional) Attribute indicating the source of the Device ID value.

Example: The source for Device ID (deviceID) could be
SecureElement, TEE, or Derived
Format: String; max length 32 characters.

deviceManufacturer (Optional) Manufacturer of the device.

Example: Samsung
Format: String; max length 32 characters.

deviceBrand (Optional) Brand name of the device.

Example: Galaxy
Format: String; max length 32 characters.

deviceModel (Optional) model of the device.

Example: SGH-T999
Format: String; max length 32 characters.

deviceLocation (Optional) Obfuscated geographic location of the device. Initially, when

provisioned, this contains the general location of the device.
Information will be supplied with latitude/longitude rounded to the
nearest whole digit.
Example: +37/-121
Format: String; max length 25 characters.

6 June 2023 Visa Confidential 156

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

deviceIndex (Conditional) The index number from Visa where the deviceID is
stored. This is required for token device binding.
Format: Integer; max length 2 digits.

deviceIPAddressV4 (Optional) The IP address of the device at the time of the provisioning
request, with the value represented in 255.255.255.255 format. An
octet (255) may be 1–3 digits in length but cannot contain any leading
zeros.
Format: String; max length 15 characters.

locationSource (Optional) Source used to identify consumer location.

Format: It is one of the following values:

l WIFI
l CELLULAR
l GPS
l OTHER

tokenProtectionMethod (Optional) Method of token protection.

Format: It is one of the following values:

l SOFTWARE
l TRUSTED_EXECUTION_ENVIRONMENT
l SECURE_ELEMENT
l CLOUD

Response

Successful Response
Successful API responses will return HTTP status code in the 2xx range. The response body, if
available, will contain the response of the API as described in this specification.

6 June 2023 Visa Confidential 157

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

actionCode Action status codes.

Format: It is one of the following values:

l 00— Unconditional approval (provision and activate immediately

for payments)
l 85— Conditional approval (provision, but do not activate until
additional consumer verification is performed)
Any decline reason code present other than 00 and 85 will prevent
device provisioning.
Decline approval due to one of the following reasons:

l 54— Invalid Expiration Date

l 05— Generic Decline
l 96— Issuer Internal System Error

errorCode This is present in the case of business error codes ISEXXXXX.

Format: String; max length 8 characters.

Error Responses
If a business error is present, it is assumed that no Standard Errors were detected in the API request.
VTS domain-specific business error reason codes are as follows:

HTTP Status Action Code Error Code Error Code Description

200 05 ISE40000 ISS_ERROR_REQUIRED_DATA_MISSING

200 05 ISE40005 ISS_ERROR_INVALID_FIELD_LENGTH

200 05 ISE40006 ISS_ERROR_INVALID_FIELD_TYPE

200 05 ISE40010 ISS_ERROR_CRYPTOGRAPHY_ERROR

200 05 ISE40011 ISS_ERROR_INVALID_FIELD_VALUE

200 96 ISE40504 ISS_ERROR_INTERNAL_SYSTEM_ERROR

200 54 ISE40013 ISS_ERROR_INVALID_EXP_DATE

Sample Payloads

6 June 2023 Visa Confidential 158

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Sample Request
/vtis/v1/tokenRequestors/400...49/tokens/DNI...11/deviceBinding
{
"panReferenceID": "V-4...48",
"walletAccountEmailAddressHash": "_PI...fY",
"clientWalletAccountID": "AWM...Bd",
"deviceInfo": {
"deviceID": "zmi...zA",
"deviceLanguageCode": null,
"osType": null,
"osVersion": null,
"osBuildID": null,
"deviceType": null,
"deviceIDType": null,
"deviceManufacturer": null,
"deviceBrand": null,
"deviceModel": null,
"deviceName": null,
"deviceNumber": null,
"deviceLocation": null,
"deviceIPAddressV4": null,
"locationSource": null,
"deviceIndex": 1
},
"locale": "en_US",
"tokenUserInfo": null
}

Sample Successful Response

{
"actionCode": "85",
"errorCode": null
}

Get Cardholder Verification Methods

This service allows the issuer to provide supported methods of cardholder step-up authentication,
for example, tenured data (cardholder email, phone number) for delivering One-Time-Password
(OTP).
Alternate Flow: STIP Processing
If the issuer system does not respond with a response message within the required timeframe or
issuer returns ISE40504 error code, the Visa system will return the issuer-defined call center number
to the wallet provider on behalf of the issuer.
Note:  

6 June 2023 Visa Confidential 159

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

If there are no pre-configured card verification methods for the corresponding card, the
provision request will be declined to the wallet provider.

Request

Endpoints

Path:
{Issuer Endpoint}/vtis/v1/retrieveStepUpMethods

Method
POST

Request Body

Field Description

tokenRequestorID (Required) Unique ID assigned to the initiator of the token request.

Format: Numeric; max length 11 digits.

tokenReferenceID (Conditional) Unique ID for the token associated with the PAN. This ID
can be used in lieu of the token for subsequent calls, such as lifecycle
events.
Format: String; max length 32 characters.

panReferenceID (Conditional) Unique ID for the PAN. This ID can be used in lieu of PAN
for the subsequent calls, such as life cycle events.
Format: String; max length 32 characters.

lifeCycleTraceID (Required) A message identifier that can be used to link some

messages associated with a provisioning request. This should be used
by the issuer in event/message logging.
Format: Integer; max length 15 digits.

clientWalletAccountID (Optional) Identifies a wallet account identifier of the wallet provider.

For SE DWPs, this will be the truncated email hash, truncated to 32
characters. For other wallet providers, it will be their identifier of a
wallet account with maximum length of 24.
Format: String; alphanumeric, case-insensitive, max length 32
characters.

6 June 2023 Visa Confidential 160

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

panSource (Conditional) Source of PAN. It is required for SE tokens.

Format: It is one of the following values:

l KEY_ENTERED
l ON_FILE
l MOBILE_BANKING_APP
l TOKEN
l CHIP_DIP
l CONTACTLESS_TAP

otpReason (Required) Reason for an OTP.

Format: It is one of the following values:

l PROVISIONING
l FPAN_NOTIFICATIONS
l PAYMENT
l TOKEN_DEVICE_BINDING
l CARDHOLDER_STEPUP
l TRUSTED_LISTING_ENROLLMENT

otpMaxReached (Optional) Describes whether the Token has exceeded the number of
OTP requests and is therefore no longer a supported method for that
token. This does not apply to the payment flow.
Format: It is one of the following values:

l true
l false

encryptedData (Required) Blob field that contains the encrypted payload; see
"Cardholder Information" in the "Encrypted Payload Data Structures"
chapter for more information. Only primaryAccountNumber needs
to be provided in cardholderInfo.
Format: String; max length 7000 characters.

6 June 2023 Visa Confidential 161

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

deviceInfo (Optional) Data associated with the device. The deviceIndex field
needs to be provided when the otpReason field is
TOKEN_DEVICE_BINDING.
Format: It is one of the following values, if populated:

l deviceName
l deviceID
l deviceType
l deviceNumber
l deviceIndex
Format: A Device Info structure.

tokenUserInfo (Future) The information of the user that requests the device binding.
Format: A Token User Information structure.

merchantInfo (Future) The information of the merchant that requests the device
binding.
Format: A Merchant Information structure.

tokenInfo (Conditional) Data associated with the token for CTF use cases.
Format: A tokenInfo structure.

Device Information
This structure is used by several APIs.

6 June 2023 Visa Confidential 162

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

deviceID (Conditional) For Secure Element (SE) wallet providers, this value will be
the SE ID in hex binary characters transformed to a 48-character string.
For Host Card Emulation (HCE) wallet providers, this field will be the
Device ID as determined by the digital wallet provider (DWP). All
alphanumeric and special characters are allowed for HCE DWPs.
Secure Element (SE) ID represents the device ID.

l For SE DWPs, this value will be the SE ID in hex binary characters

transformed to a 48-character string.
l For CBP DWPs, this field will be the device ID as determined by the
DWP. All alphanumeric and special characters are allowed for CBP
DWPs.
For Card-on-File (COF) wallets, this value will not be present.
For the initial Check Eligibility request on PAN enrollment, this value
may not be available, however Visa will send this value if it is available.
Format: String; max length 48 characters.

deviceLanguageCode (Optional) This value is any ISO 639 Version 3 Language Code, for
example, eng (English). This language code will be used by the issuer
and Visa to retrieve the Terms and Conditions (T&C). If T&Cs are not
found for the Language Code in the request, the T&Cs will return the
default :anguage Code of eng (English).
Format: String; ISO-639 Version 3 Language Code, max length 3
characters.

deviceType (Optional) Device type.

Format: It is one of the following values:

l UNKNOWN
l MOBILE_PHONE
l TABLET
l WATCH
l MOBILEPHONE_OR_TABLET
l PC
l HOUSEHOLD_DEVICE
l WEARABLE_DEVICE
l AUTOMOBILE_DEVICE

deviceName (Optional) A readable name for the device. Ideally, the customer enters
this name. It can be used to identify the device in customer support
calls.
Example: My Work Phone
Format: String; Base64URL-encoded; UTF-8; max length 128
characters.

6 June 2023 Visa Confidential 163

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

deviceNumber (Optional) Device number.

Format: String; max length 13 characters.

osType (Optional) Type of operating system.

Format: It is one of the following values:

l ANDROID
l IOS
l WINDOWS
l BLACKBERRY
l TIZEN
l OTHER

osVersion (Optional) Version of the operating system running on the device.

Example: 4.4.4
Format: String; max length 32 characters.

osBuildID (Optional) Operating system build identifier.

Example: KTU84M
Format: String; max length 32 characters.

deviceIDType (Optional) Attribute indicating the source of the Device ID value.

Example: The source for Device ID (deviceID) could be
SecureElement, TEE, or Derived
Format: String; max length 32 characters.

deviceManufacturer (Optional) Manufacturer of the device.

Example: Samsung
Format: String; max length 32 characters.

deviceBrand (Optional) Brand name of the device.

Example: Galaxy
Format: String; max length 32 characters.

deviceModel (Optional) model of the device.

Example: SGH-T999
Format: String; max length 32 characters.

deviceLocation (Optional) Obfuscated geographic location of the device. Initially, when

provisioned, this contains the general location of the device.
Information will be supplied with latitude/longitude rounded to the
nearest whole digit.
Example: +37/-121
Format: String; max length 25 characters.

6 June 2023 Visa Confidential 164

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

deviceIndex (Conditional) The index number from Visa where the deviceID is
stored. This is required for token device binding.
Format: Integer; max length 2 digits.

deviceIPAddressV4 (Optional) The IP address of the device at the time of the provisioning
request, with the value represented in 255.255.255.255 format. An
octet (255) may be 1–3 digits in length but cannot contain any leading
zeros.
Format: String; max length 15 characters.

locationSource (Optional) Source used to identify consumer location.

Format: It is one of the following values:

l WIFI
l CELLULAR
l GPS
l OTHER

tokenProtectionMethod (Optional) Method of token protection.

Format: It is one of the following values:

l SOFTWARE
l TRUSTED_EXECUTION_ENVIRONMENT
l SECURE_ELEMENT
l CLOUD

6 June 2023 Visa Confidential 165

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Token Information

Field Description

token (Conditional) The account number associated with a token. This is a

required field in the following APIs:

l Token Create Notification

l Token Notification
Format: String; max length 19 characters.

tokenType (Conditional) This is a required field in the following APIs:

l Approve Provisioning
l Approve Provisioning Stand-In Notification
l Token Create Notification
Format: It is one of the following values:

l SECURE_ELEMENT
l HCE
l CARD_ON_FILE
l ECOMMERCE
l QRC

tokenStatus (Conditional) This is a required field in the following APIs:

l Token Create Notification

l Token Notification
Format: It is one of the following values:

l ACTIVE
l INACTIVE
l SUSPENDED
l DEACTIVATED

tokenExpirationDate (Conditional) The date upon which the token is set to expire. This field
is required in the Token Create Notification API.
Format: An Expiration Date structure.

6 June 2023 Visa Confidential 166

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

tokenAssuranceMethod (Optional) Method of Issuer ID&V that has taken place at time of
provisioning, device binding, or cardholder initiated verification. It is
one of the following values:

l 00 ID&V Not Performed

l 10 Card Issuer Account Verification
l 11 Card Issuer Interactive Cardholder Verification - 1 Factor
l 12 Card Issuer Interactive Cardholder Verification - 2 Factor
l 13 Card Issuer Risk Oriented Non-Interactive Cardholder Authenti­
cation
l 14 Card Issuer Asserted Authentication
Format: String; max length 2 characters.

numberOfActiveTokensForPAN (Optional) Number of device tokens that are currently active for this
PAN.
Format: Integer; max length 4 digits.

numberOfInactiveTokensForPAN (Optional) Number of device tokens that are currently inactive (device
tokens have not been activated) for this PAN.
Format: Integer; max length 4 digits.

numberOfSuspendedTokensForPAN (Optional) Number of device tokens that were activated, but are
suspended for payments for this PAN.
Format: Integer; max length 4 digits.

tokenActivationDate (Optional) System date/timestamp, in GMT, of token activation into an

active state. For an inactive state, this field is left empty and populated
only when a token transitions to an active state. If a token is
suspended, this field is populated with the new date/timestamp of
when an active state resumes.
Format: String; yyyy-MM-ddTHH:mm:ss.SSSZ.

tokenDeactivationDate (Optional) Date of token deactivation.

Format: String; YYYY-MM-DD.

lastTokenStatusUpdatedTime (Optional) Date/timestamp, in GMT, of the last token status update.

Format: String; yyyy-MM-ddTHH:mm:ss.SSSZ.

originalToken (Conditional) Token account number. This field is populated when

performing token-for-token provisioning only.
Format: String; max length 19 characters.

originalTokenRequestorID (Required) Unique ID assigned to the initiator of the token request. This
field is populated when performing token-for-token provisioning only.
Format: Numeric; max length 11 digits.

6 June 2023 Visa Confidential 167

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

originalTokenReferenceID (Conditional) Unique ID for the token associated with the PAN. This ID
can be used in lieu of the token for subsequent calls, such as life cycle
events. This field is populated when performing token-for-token
provisioning only.
Format: String; max length 32 characters.

originalTokenType (Conditional) Token type of the original token. This field is populated
only when performing token for token provisioning and can be used
only in the following APIs:

l Approve Provisioning
l Approve Provisioning Stand-In Notification
l Token Create Notification
Format: It is one of the following values:

l SECURE_ELEMENT
l HCE
l CARD_ON_FILE
l ECOMMERCE
l QRC
l PSEUDO_ACCOUNT

originaltokenAssuranceMethod (Conditional) Original token assurance method. This field is populated

when performing token-for-token provisioning only. It is one of the
following values:

l 00 ID&V Not Performed

l 10 Card Issuer Account Verification
l 11 Card Issuer Interactive Cardholder Verification - 1 Factor
l 12 Card Issuer Interactive Cardholder Verification - 2 Factor
l 13 Card Issuer Risk Oriented Non-Interactive Cardholder Authenti­
cation
l 14 Card Issuer Asserted Authentication
Format: String; max length 2 characters.

6 June 2023 Visa Confidential 168

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

tokenRequestorName (Conditional) Token requester name. Populated when available in the

following APIs:

l Device Token Binding Request

l Get Cardholder Verification Methods
l Send Passcode
l Token Notification
Format: String; max length 100 characters.

autoFillIndicator (Conditional) Indicates whether the token is for an autofill use case.
This is a required field in the following APIs:

l Approve Provisioning
l Approve Provisioning Stand-In Notification
l Token Create Notification
Format: It is one of the following values:

l true — Indicates that the token (e-Commerce Enabler, or Card-on-

File) is for an autofill use case.
l false — Indicates that the token is not for an autofill use case.

Response

Successful Response
Successful API responses will return HTTP status code in the 2xx range. The response body, if
available, will contain the response of the API as described in this specification.

6 June 2023 Visa Confidential 169

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

errorCode (Conditional )This value is present in the case of business error,

ISEXXXXX codes.
Format: String; max length 8 characters.

stepUpMethods (Conditional )If present, one or more step-up methods.

Format: An array of Step Up Methods Details structures; max 10
structures.

responseCode (Optional )This value is present when the otpReason field is

TOKEN_DEVICE_BINDING, CARDHOLDER_STEPUP, or
TRUSTED_LISTING_ENROLLMENT. This field is not present if the
issuer is onboarded for Device Token Binding Request API or 0100 DBR
and has provided the response in that API.
Format: It is one of the following values:

l APPROVED
l STEPUP
l DECLINED

6 June 2023 Visa Confidential 170

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

StepUp Methods Details

Field Description

type Required, if cardholder verification method is returned.

Format: It is one of the following values:

l OTPSMS
l OTPEMAIL
l APP_TO_APP
l CUSTOMERSERVICE
l OUTBOUNDCALL
APP_TO_APP should not be returned as a verification method if PAN
source=MOBILE_BANKING_APP on the inbound request. Bank app-
initiated provision requests should not be verified through the bank
app.
If otpMaxReachedis set to True, the issuer should send neither
OTPSMS, OTPEMAIL, nor OUTBOUNDCALL as a verification method in
the response.
Format: String; alphanumeric; max length 32 characters.

value Present if a cardholder verification method is returned. Masked values

for consumer contact information. Unmasked phone numbers for non-
consumer numbers; “user-friendly” description for mobile banking app.
Example:

l Consumer email: ‘ip****@gmail.com’

l Consumer Phone: ‘****-5045’

l Mobile Banking (APP_TO_APP): ‘Mobile Banking App’

l Call Center (CUSTOMERSERVICE): ‘1-800-555-5555’

Format: String; max length 64 characters.

identifier Present if a cardholder verification method is returned. Unique and

opaque identifier for this method. This ID should be provided by the
issuer. The issuer must maintain the association of this identifier with
the value of the Cardholder Verification Method (for example, email
address). A subsequent Send Passcode request will only provide the
Identifier to the issuer, not the actual contact method value.
Format: String; max length 32 characters.

6 June 2023 Visa Confidential 171

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

sourceAddress Indicates the source address from which the OTP is sent. This field can
be used in two different contexts:

l When used with OTPSMS or OTPEMAIL in the type field, this field
is used to support auto-vetting for sending an OTP via
cell_phone (SMS) or email. For example, if an SMS will be sent
from 382-2, then the sourceAddress would be 382-2. Auto-
vetting is not currently supported. This attribute will be ignored
until auto-vetting is supported by SE DWPs.
l When used with APP_TO_APP in the type field, a value in this field
is required if the step-up flow mobile banking app is different from
the mobile banking app used during provisioning. If used, this value
must contain the appropriate identifier for the associated issuer
mobile banking application. For Apple, this is the Apple Adam ID.
For Android, this is the Android Package name.
Format: String; alphanumeric; max length 64 characters.

otpMethodPlatform Used with the APP_TO_APP type, this field contains the appropriate
OS platform for the associated issuer mobile banking application.
Format: It is one of the following values:

l IOS
l ANDROID
l WINDOWS
l WEB

Error Responses
If a business error is present, it is assumed that no Standard Errors were detected in the API request.
VTS domain-specific business error reason codes are as follows:

HTTP Status Error Code Error Code Description

200 ISE40000 ISS_ERROR_REQUIRED_DATA_MISSING

200 ISE40001 ISS_ERROR_INVALID_PAN

200 ISE40005 ISS_ERROR_INVALID_FIELD_LENGTH

200 ISE40006 ISS_ERROR_INVALID_FIELD_TYPE

200 ISE40010 ISS_ERROR_CRYPTOGRAPHY_ERROR

200 ISE40011 ISS_ERROR_INVALID_FIELD_VALUE

200 ISE40402 ISS_ERROR_INVALID_TOKEN_VALUE

6 June 2023 Visa Confidential 172

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

HTTP Status Error Code Error Code Description

200 ISE40500 ISS_ERROR_UNKNOWN_TOKEN_REFID_VALUE

200 ISE40504 ISS_ERROR_INTERNAL_SYSTEM_ERROR

Sample Payloads

Sample Request
{
"tokenRequestorID": "400...73",
"tokenReferenceID": "DNI...08",
"panReferenceID": "V-3...55",
"clientWalletAccountID": "897...31",
"panSource": "KEY_ENTERED",
"otpReason": "TOKEN_DEVICE_BINDING",
"otpMaxReached": true,
"encryptedData": "eyJ...qQ",
"deviceInfo": {
"deviceID": "413...12",
"deviceType": "MOBILE_PHONE",
"deviceName": "Apple Ipod",
"deviceNumber": "1",
"deviceIndex": 9
}
}

All JWS and JWE elements are Base64URL-encoded.

JWS:
<JWS Header>.<JWS Payload>.<JWS Signature>
JWS payload:
<JWE>
JWE:

<Header>.<Encrypted Key>.<InitializationVector>.<Ciphertext>.
<Authentication Tag>

Decrypted data contained in JWE ciphertext element:

{
“cardholderInfo”:{
“primaryAccountNumber”: “”
},
“riskInformation”: {
“walletProviderAccountScore”: “”,
“walletProviderDeviceScore”: “”,

6 June 2023 Visa Confidential 173

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

“walletProviderReasonCodes”: “”,
“issuerSpecialConditionCodes”: “”,
“visaTokenScore”: “”,
“riskAssessmentScore”: “”
}
}

Sample Successful Response

{
"responseCode": "STEPUP",
"stepUpMethods": [
{
"type": "OTPSMS",
"value": "device Name test",
"identifier": "45b...a5",
"sourceAddress": "https://otpsms.com"
},
{
"type": "OTPEMAIL",
"value": "device Name test",
"identifier": "45b...a5",
"sourceAddress": "https://otpemail.com"
},
{
"type": "APP_TO_APP",
"value": "androidTest",
"identifier": "45b...a5",
"sourceAddress": "https://android.com",
"otpMethodPlatform": "ANDROID"
},
{
"type": "APP_TO_APP",
"value": "windowsTest",
"identifier": "45b...a5",
"sourceAddress": "https://windows.com",
"otpMethodPlatform": "WINDOWS"
},
{
"type": "OUTBOUNDCALL",
"value": "device Name test",
"identifier": "45b...a5",
"sourceAddress": "https://outboundCall.com"
}
]
}

6 June 2023 Visa Confidential 174

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Sample Business Error Response

{
“errorCode”: “ISE40000”
}

PAN Update Notification

Visa will invoke this API on the issuer side to send a notification whenever the issuer performs PAN or
PAN expiration date updates. This notification will also be sent in case of an account level
management update.

Request

Endpoints

Path:

{Issuer Endpoint}/vtis/v1/pan/notification?eventType=eventType

Method
POST

Query Parameters

Event Type

Parameter Description

eventType (Required) Confirms that the event is either a PAN update, or an

account management update.
Format: It is one of the following values:

l PAN_UPDATED—
Indicates that a PAN has been updated.
l ACCOUNT_LEVEL_RECORD— Indicates the event is an account
management update.

6 June 2023 Visa Confidential 175

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Request Body

Field Description

messageReason (Optional) Text-based description of the notification message code.

The descriptions may change and issuers should use the Message
Reason Code field for all programmatic actions. This field is for
informational purposes only.
Format: String; max length 256 characters.

messageReasonCode (Required) String representation of the message reason, corresponding

to ISO message reason codes when applicable. Additional values may
be available in the future.
Format: It is one of the following values:

l ACCOUNT_UPDATE— Account number change or Account number

and Expiry date change
l EXP_DATE_UPDATE— Expiration date change.
l ACCOUNT_LEVEL_RECORD_UPDATE— Account management
update.

dateTimeOfEvent (Required) Event timestamp in GMT.

Format: String; yyyy-MM-ddTHH:mm:ss.SSSZ.

panReferenceID (Conditional) Unique ID for the PAN. This ID can be used in lieu of the
PAN for subsequent calls, such as life cycle events.
Format: String; max length 32 characters.

encryptedData (Required) Blob field that contains the encrypted payload; see
"Cardholder Information" in the "Encrypted Payload Data Structures"
chapter for more information. For PAN update/replacement, the new
and the old PAN must share the same 9-digit BIN; the new PAN should
not have any tokens already associated to it.
If provided, the blob may contain:

l cardholderInfo

– Current PAN
– Expiration Date
l replaceCardholderInfo

– New Expiration Date

– New PAN
Format: String; max length 7000 characters.

accountLevelInfoResp (Conditional) Required when messageReasonCode is

ACCOUNT_LEVEL_RECORD_UPDATE.
Format: An Account Level Information Response structure.

6 June 2023 Visa Confidential 176

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Account Level Information Response

Field Description

rpinEnrollment (Optional) Contains response information related to RPIN enrollment

information.
Format: An RPIN Enrollment Response structure.

replaceEnrollment (Optional)Contains response information related to card replacement

request.
Format: A Replace Enrollment Response structure.

linkEnrollment (Optional)Contains response information related to the linking request

for each group type.
Format: A Link Enrollment Response structure.

RPIN Enrollment Response

Field Description

responseStatus RPIN enrollment response status.

Format: It is one of the following values:

l S— Successfully processed the request.

l F— Failed to process the request.

rejectCode Contains the Reject Code for the failure. Present only when the
Response Status = F. Refer to Appendix A for a full description of all
Reject Codes.
Format: String; alphabetic; max length 2 characters.

rejectDesc Contains the Reject Reason for the failure. Present only when the
Response Status = F. Refer to Appendix A for a full description of all
Reject Codes.
Format: String; alphanumeric; max length 100 characters.

6 June 2023 Visa Confidential 177

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Replace Enrollment Response

Field Description

responseStatus Response status value.

Format: It is one of the following values:

l S— Successfully processed the request.

l W— Successfully processed the request with a warning.
l F— Failed to process the request.

rejectCode Contains the reject code for the failure. Present only when the
Response Status = F or W. See Appendix A for a full description of all
reject codes and descriptions.
Format: String; alphabetic; max length 2 characters.

rejectDesc Contains the reject description, or reason, for the failure. Present only
when the Response Status = F or W. See Appendix A for a full
description of all reject codes and descriptions.
Format: String; alphanumeric; max length 100 characters.

Link Enrollment Response

Field Description

groupResp Group response.

Format: A Group Response structure.

Group Response

Field Description

groupType (Required) The Group Type Code from the request that is returned in
the response.
Format: String; max length 16 characters.

groupID (Required)Contains the issuer-supplied group identifier for the

specified group type received in request.
Format: String; max length 32 characters.

responseStatus (Required)Response status value.

Format: It is one of the following values:

l S— Successfully processed the request.

l W— Successfully processed the request with a warning.
l F— Filed to process the request.

6 June 2023 Visa Confidential 178

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

rejectCode (Optional)Contains the reject code for the failure. Present only when
the Response Status = F or W. See Appendix A for a full description of
all reject codes and descriptions.
Format: String; alphabetic; max length 2 characters.

rejectDesc (Optional)Contains the reject description, or reason, for the failure.

Present only when the Response Status = F or W. See Appendix A for a
full description of all reject codes and descriptions.
Format: String; alphanumeric; max length 100 characters.

Response

Successful Response
Successful API responses will return HTTP 200 status code with no response payload.

Error Response
The notification API is an asynchronous API and does not need the issuer to return anything to Visa.
The issuer returns the following error statuses as appropriate with no response payload in addition to
the Standard Errors.

HTTP Code HTTP Reason Code Description

400 Bad Request The request could not be understood by the server because of
malformed syntax. The client should not repeat the request until
modifications have been made.

401 Unauthorized Authentication credentials were missing or incorrect.

404 Not Found The server has not found anything matching the Request URI.

500 Internal Server Error An unspecified server error has occurred. Visa should attempt to
retry or contact issuer support.

Sample Payloads

6 June 2023 Visa Confidential 179

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Sample Successful Request

{
“messageReason”: “”,
“messageReasonCode”: “”,
“dateTimeOfEvent”: “”,
“panReferenceID”: “”,
“encryptedData”: “<JWS>”
}

All JWS and JWE elements are URL encoded.

JWS:
<JWS Header>.<JWS Payload>.<JWS Signature>
JWS Payload:
<JWE>
JWE:

<Header>.<Encrypted Key>.<Initialization Vector>.<Ciphertext>.

<Authentication Tag>

Decrypted data contained in JWE Ciphertext element:

{
“cardholderInfo”: {
“primaryAccountNumber”: “”,
“expirationDate”: {
“month”: “”,
“year”: “”
}
},
“replaceCardholderInfo”: {
“primaryAccountNumber”: “”,
“expirationDate”: {
“month”: “”,
“year”: “”
}
}
}

Sample Successful Response

HTTP 200 Success status with no payload.

6 June 2023 Visa Confidential 180

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Send Passcode
This service is invoked to deliver the OTP to the destination selected by the cardholder, such as an
email address, via the issuer.

Request

Endpoints

Path:

{Issuer Endpoint}/vtis/v1/sendPasscode

Method
POST

Request Body

Field Description

tokenRequestorID (Required) Unique ID assigned to the initiator of the token request.

Format: Numeric; max length 11 digits.

tokenReferenceID (Conditional) Unique ID for the token associated with the PAN. Can be
used in lieu of the token for subsequent calls, such as life cycle events.
Format: String; max length 32 characters.

panReferenceID (Conditional) Unique ID for the PAN. Can be used in lieu of PAN for
subsequent calls, such as life cycle events.
Format: String; max length 32 characters.

lifeCycleTraceID (Required) A message identifier that can be used to link some

messages associated with a provisioning request. This should be used
by the issuer in event/message logging.
Format: Integer; max length 15 digits.

clientWalletAccountID (Optional) Identifies a wallet account identifier of the wallet provider.

For SE DWPs, this will be a truncated email hash, truncated to 32
characters. For other wallet providers, it will be their identifier of a
wallet account with a maximum length of 24.
Format: String; alphanumeric; max length 32 characters.

6 June 2023 Visa Confidential 181

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

otpMethodIdentifier (Required) Unique and opaque identifier for the delivery method
selected by the cardholder.
Format: String; max length 32 characters.

otpValue (Required) OTP value. In the initial release, it will be populated with 6
digit values; in the future, the value may be expanded up to 8 digits in
length.
Format: String; max length 8 digits.

otpReason (Optional) Reason for an OTP. Additional values may be available in the
future.
Format: It is one of the following values:

l PAYMENT
l TOKEN_DEVICE_BINDING
l CARDHOLDER_STEPUP
l TRUSTED_LISTING_ENROLLMENT

otpExpirationDate (Optional) One-Time Password date/timestamp in GMT.

Format: String; yyyy-MM-ddTHH:mm:ss.SSSZ.

deviceInfo (Optional) Data associated with the device.

Format: If populated, it is one of the following values:

l deviceName
l deviceID
l deviceType
l deviceNumber
Format: A Device Information structure.

encryptedData (Required) Blob field that contains the encrypted payload; see
"Cardholder Information" in the "Encrypted Payload Data Structures"
chapter for more information. Only primaryAccountNumber needs
to be provided in cardholderInfo.
Format: String; max length 7000 characters.

tokenInfo (Conditional) Data associated with the token for CTF use cases.
Format: A tokenInfo structure.

Device Information
This structure is used by several APIs.

6 June 2023 Visa Confidential 182

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

deviceID (Conditional) For Secure Element (SE) wallet providers, this value will be
the SE ID in hex binary characters transformed to a 48-character string.
For Host Card Emulation (HCE) wallet providers, this field will be the
Device ID as determined by the digital wallet provider (DWP). All
alphanumeric and special characters are allowed for HCE DWPs.
Secure Element (SE) ID represents the device ID.

l For SE DWPs, this value will be the SE ID in hex binary characters

transformed to a 48-character string.
l For CBP DWPs, this field will be the device ID as determined by the
DWP. All alphanumeric and special characters are allowed for CBP
DWPs.
For Card-on-File (COF) wallets, this value will not be present.
For the initial Check Eligibility request on PAN enrollment, this value
may not be available, however Visa will send this value if it is available.
Format: String; max length 48 characters.

deviceLanguageCode (Optional) This value is any ISO 639 Version 3 Language Code, for
example, eng (English). This language code will be used by the issuer
and Visa to retrieve the Terms and Conditions (T&C). If T&Cs are not
found for the Language Code in the request, the T&Cs will return the
default :anguage Code of eng (English).
Format: String; ISO-639 Version 3 Language Code, max length 3
characters.

deviceType (Optional) Device type.

Format: It is one of the following values:

l UNKNOWN
l MOBILE_PHONE
l TABLET
l WATCH
l MOBILEPHONE_OR_TABLET
l PC
l HOUSEHOLD_DEVICE
l WEARABLE_DEVICE
l AUTOMOBILE_DEVICE

deviceName (Optional) A readable name for the device. Ideally, the customer enters
this name. It can be used to identify the device in customer support
calls.
Example: My Work Phone
Format: String; Base64URL-encoded; UTF-8; max length 128
characters.

6 June 2023 Visa Confidential 183

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

deviceNumber (Optional) Device number.

Format: String; max length 13 characters.

osType (Optional) Type of operating system.

Format: It is one of the following values:

l ANDROID
l IOS
l WINDOWS
l BLACKBERRY
l TIZEN
l OTHER

osVersion (Optional) Version of the operating system running on the device.

Example: 4.4.4
Format: String; max length 32 characters.

osBuildID (Optional) Operating system build identifier.

Example: KTU84M
Format: String; max length 32 characters.

deviceIDType (Optional) Attribute indicating the source of the Device ID value.

Example: The source for Device ID (deviceID) could be
SecureElement, TEE, or Derived
Format: String; max length 32 characters.

deviceManufacturer (Optional) Manufacturer of the device.

Example: Samsung
Format: String; max length 32 characters.

deviceBrand (Optional) Brand name of the device.

Example: Galaxy
Format: String; max length 32 characters.

deviceModel (Optional) model of the device.

Example: SGH-T999
Format: String; max length 32 characters.

deviceLocation (Optional) Obfuscated geographic location of the device. Initially, when

provisioned, this contains the general location of the device.
Information will be supplied with latitude/longitude rounded to the
nearest whole digit.
Example: +37/-121
Format: String; max length 25 characters.

6 June 2023 Visa Confidential 184

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

deviceIndex (Conditional) The index number from Visa where the deviceID is
stored. This is required for token device binding.
Format: Integer; max length 2 digits.

deviceIPAddressV4 (Optional) The IP address of the device at the time of the provisioning
request, with the value represented in 255.255.255.255 format. An
octet (255) may be 1–3 digits in length but cannot contain any leading
zeros.
Format: String; max length 15 characters.

locationSource (Optional) Source used to identify consumer location.

Format: It is one of the following values:

l WIFI
l CELLULAR
l GPS
l OTHER

tokenProtectionMethod (Optional) Method of token protection.

Format: It is one of the following values:

l SOFTWARE
l TRUSTED_EXECUTION_ENVIRONMENT
l SECURE_ELEMENT
l CLOUD

6 June 2023 Visa Confidential 185

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Token Information

Field Description

token (Conditional) The account number associated with a token. This is a

required field in the following APIs:

l Token Create Notification

l Token Notification
Format: String; max length 19 characters.

tokenType (Conditional) This is a required field in the following APIs:

l Approve Provisioning
l Approve Provisioning Stand-In Notification
l Token Create Notification
Format: It is one of the following values:

l SECURE_ELEMENT
l HCE
l CARD_ON_FILE
l ECOMMERCE
l QRC

tokenStatus (Conditional) This is a required field in the following APIs:

l Token Create Notification

l Token Notification
Format: It is one of the following values:

l ACTIVE
l INACTIVE
l SUSPENDED
l DEACTIVATED

tokenExpirationDate (Conditional) The date upon which the token is set to expire. This field
is required in the Token Create Notification API.
Format: An Expiration Date structure.

6 June 2023 Visa Confidential 186

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

tokenAssuranceMethod (Optional) Method of Issuer ID&V that has taken place at time of
provisioning, device binding, or cardholder initiated verification. It is
one of the following values:

l 00 ID&V Not Performed

l 10 Card Issuer Account Verification
l 11 Card Issuer Interactive Cardholder Verification - 1 Factor
l 12 Card Issuer Interactive Cardholder Verification - 2 Factor
l 13 Card Issuer Risk Oriented Non-Interactive Cardholder Authenti­
cation
l 14 Card Issuer Asserted Authentication
Format: String; max length 2 characters.

numberOfActiveTokensForPAN (Optional) Number of device tokens that are currently active for this
PAN.
Format: Integer; max length 4 digits.

numberOfInactiveTokensForPAN (Optional) Number of device tokens that are currently inactive (device
tokens have not been activated) for this PAN.
Format: Integer; max length 4 digits.

numberOfSuspendedTokensForPAN (Optional) Number of device tokens that were activated, but are
suspended for payments for this PAN.
Format: Integer; max length 4 digits.

tokenActivationDate (Optional) System date/timestamp, in GMT, of token activation into an

active state. For an inactive state, this field is left empty and populated
only when a token transitions to an active state. If a token is
suspended, this field is populated with the new date/timestamp of
when an active state resumes.
Format: String; yyyy-MM-ddTHH:mm:ss.SSSZ.

tokenDeactivationDate (Optional) Date of token deactivation.

Format: String; YYYY-MM-DD.

lastTokenStatusUpdatedTime (Optional) Date/timestamp, in GMT, of the last token status update.

Format: String; yyyy-MM-ddTHH:mm:ss.SSSZ.

originalToken (Conditional) Token account number. This field is populated when

performing token-for-token provisioning only.
Format: String; max length 19 characters.

originalTokenRequestorID (Required) Unique ID assigned to the initiator of the token request. This
field is populated when performing token-for-token provisioning only.
Format: Numeric; max length 11 digits.

6 June 2023 Visa Confidential 187

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

originalTokenReferenceID (Conditional) Unique ID for the token associated with the PAN. This ID
can be used in lieu of the token for subsequent calls, such as life cycle
events. This field is populated when performing token-for-token
provisioning only.
Format: String; max length 32 characters.

originalTokenType (Conditional) Token type of the original token. This field is populated
only when performing token for token provisioning and can be used
only in the following APIs:

l Approve Provisioning
l Approve Provisioning Stand-In Notification
l Token Create Notification
Format: It is one of the following values:

l SECURE_ELEMENT
l HCE
l CARD_ON_FILE
l ECOMMERCE
l QRC
l PSEUDO_ACCOUNT

originaltokenAssuranceMethod (Conditional) Original token assurance method. This field is populated

when performing token-for-token provisioning only. It is one of the
following values:

l 00 ID&V Not Performed

l 10 Card Issuer Account Verification
l 11 Card Issuer Interactive Cardholder Verification - 1 Factor
l 12 Card Issuer Interactive Cardholder Verification - 2 Factor
l 13 Card Issuer Risk Oriented Non-Interactive Cardholder Authenti­
cation
l 14 Card Issuer Asserted Authentication
Format: String; max length 2 characters.

6 June 2023 Visa Confidential 188

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

tokenRequestorName (Conditional) Token requester name. Populated when available in the

following APIs:

l Device Token Binding Request

l Get Cardholder Verification Methods
l Send Passcode
l Token Notification
Format: String; max length 100 characters.

autoFillIndicator (Conditional) Indicates whether the token is for an autofill use case.
This is a required field in the following APIs:

l Approve Provisioning
l Approve Provisioning Stand-In Notification
l Token Create Notification
Format: It is one of the following values:

l true — Indicates that the token (e-Commerce Enabler, or Card-on-

File) is for an autofill use case.
l false — Indicates that the token is not for an autofill use case.

Response

Successful Response
Successful API responses will return HTTP 200 status code with no response payload, e.g. "".
The response body, if available, will contain the error response of the API as described in this
specification.

Field Description

errorCode This is present in case of business error, ISEXXXXX codes.

Format: String; max length 8 characters.

Sample Business Error Response

{
“errorCode”: “ISE40000”
}

6 June 2023 Visa Confidential 189

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Error Responses
If a business error is present, it is assumed that no Standard Errors were detected in the API request.
VTS domain-specific business error reason codes are as follows:

HTTP Status Error Code Error Code Description

200 ISE40000 ISS_ERROR_REQUIRED_DATA_MISSING

200 ISE40001 ISS_ERROR_INVALID_PAN

200 ISE40005 ISS_ERROR_INVALID_FIELD_LENGTH

200 ISE40006 ISS_ERROR_INVALID_FIELD_TYPE

200 ISE40010 ISS_ERROR_CRYPTOGRAPHY_ERROR

200 ISE40011 ISS_ERROR_INVALID_FIELD_VALUE

200 ISE40402 ISS_ERROR_UNKNOWN_TOKEN_VALUE

200 ISE40500 ISS_ERROR_ UNKNOWN_TOKEN_REFID_VALUE

200 ISE40501 ISS_ERROR_ UNKNOWN_RESOLUTION_METHODID_VALUE

200 ISE40502 ISS_ERROR_ INVALID_OTP_CHANNEL

200 ISE40503 ISS_ERROR_ INVALID_RESOLUTION_METHODID_VALUE

200 ISE40504 ISS_ERROR_INTERNAL_SYSTEM_ERROR

Sample Payloads

Sample Request
{
“tokenRequestorID” : 400...52,
“tokenReferenceID” : “DNI...12”,
“panReferenceID”: “V-4200...90”,
“clientWalletAccountID”: “99E...4C”,
“otpMethodIdentifier”: “1e3...60”,
“otpValue”: “123456”,
“otpExpirationDate”: “2015-05-18T14:40:32.000Z”,
“deviceInfo”: {
“deviceID”: “043...7C”,
“deviceType”: “MOBILE_PHONE”,
“deviceName”: “My iPhone”,
“deviceNumber”: “86...30”
},
“encryptedData”: “<JWS>”
}

6 June 2023 Visa Confidential 190

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

All JWS and JWE elements are Base64URL-encoded.

JWS:
<JWS Header>.<JWS Payload>.<JWS Signature>
JWS Payload:
<JWE>
JWE:

<Header>.<Encrypted Key>.<InitializationVector>.<Ciphertext>.
<Authentication Tag>

Decrypted data contained in JWE ciphertext element:

{
“cardholderInfo”:{
“primaryAccountNumber”: “”
}
}

Token Create Notification

This API is exposed by an issuer. Visa will invoke this API call when the issuer's token has been
created.

Request

Endpoints

Path:

{Issuer Endpoint}/vtis/v2/tokenRequestors/
{tokenRequestorID}/tokens/
{tokenReferenceID}/tokenChanged?eventType=eventType

6 June 2023 Visa Confidential 191

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

URL Parameters

Parameter Description

{tokenRequestorID} (Required) Unique ID assigned to the initiator of the token request.

Format: Numeric; max length 11 digits.

{tokenReferenceID} (Required) Unique ID for the token associated with the PAN. This ID can
be used in lieu of a token for subsequent calls, such as life cycle events.
Format: String; max length 32 characters.

Method
POST

Query Parameters

Event Type — Token Created

Parameter Description

eventType (Required) Event type.

Format: It is one of the following values:

l TOKEN_CREATED
– Token created

Request Body

Field Description

messageReason (Optional) A text-based description of the notification message code.

The descriptions may change and issuers should use the Message
Reason Code for all programmatic actions. This field is for information
only.
Format: String; max length 256 characters.

messageReasonCode (Required) String representation of the message reason, which

corresponds to the ISO message reason codes when applicable.
Value is TOKEN_CREATED.

dateTimeOfEvent (Required) Event date/timestamp in GMT..

Format: String; yyyy-MM-ddTHH:mm:ss.SSSz.

6 June 2023 Visa Confidential 192

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

panReferenceID (Required) Unique ID for the PAN. This ID can be used in lieu of PAN for
subsequent calls, such as lifecycle events.
Format: String; max length 32 characters.

lifeCycleTraceID (Required) A message identifier that can be used to link some

messages associated with a provisioning request. This should be used
by the issuer in event/message logging.
Format: Integer; max length 15 digits.

walletAccountEmailAddressHash (Required) Hash of the email address linked to the wallet account login
ID.
Format: String; max length 64 characters.

clientWalletAccountID (Required) Consumer ID that identifies the wallet Account-holder entity.

This is provided by the client or, in some cases, by Visa.
Format: String; max length 32 characters.

panSource (Required) Source of PAN.

Format: It is one of the following values:

l KEY_ENTERED
l ON_FILE
l MOBILE_BANKING_APP
l TOKEN
l CHIP_DIP
l CONTACTLESS_TAP

addressVerificationResultCode (Optional) Visa-defined code that describes the result of an address

verification.
Format: String; max length 1 character.

6 June 2023 Visa Confidential 193

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

cvv2ResultsCode (Optional) Card verification value 2 (CVV2) verification result.

Format: It is one of the following values:

l M— CVV2 Match, indicates that Visa was able to verify the CVV2
value provided by the wallet provider.
l N— CVV2 No Match, indicates that Visa was not able to verify the
CVV2 value provided by the wallet provider.
l P— Not processed, indicates that Visa was unable to verify the
CVV2 value provided by the wallet provider. This applies for Issuers
opting for CVV2 Bypass only.
l S — CVV2 should be on the card: Indicates that V.I.P. or the issuer
was unable to perform CVV2 verification and notifies the merchant
that the card should contain a CVV2 value.
l U — Issuer is not available, does not participate in the CVV2 Service,
or participates but has not provided Visa with encryption keys:
Indicates that the issuer is notparticipating in the CVV2 Service or
has not provided Visa with encryption keys needed to perform
verification, or that STIP has responded to an issuer-unavailable
response.

consumerEntryMode (Optional) Method of consumer entry.

Format: It is one of the following values:

l KEY_ENTERED
l CAMERA_CAPTURED
l UNKNOWN

locale (Optional) Language in which the app communicates with the

customer. The language and country should be separated using a “_“.
Example: en_US
Format: String; ISO format for language (ISO 639-1) and alpha-2
country code (ISO 3166-1 alpha-2); max length 5 characters.

deviceInfo (Optional) Data associated with the device.

Format: A Device Information structure.

encryptedData (Required) Blob field that contains the encrypted payload; see
"Cardholder Information," "Token Information," and "Risk Information"
in the "Encrypted Payload Data Structures" chapter for more
information.
Format: String; max length 7000 characters.

termsAndConditions (Optional) Terms and conditions for consumer.

Format: A Terms and Conditions structure.

6 June 2023 Visa Confidential 194

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

actionCode (Required) Contains one of the following action status codes:

Format: It is one of the following values:

l 00— Good
l 85— Conditional approval (provision, but do not activate until
additional consumer verification is performed)
l 05— Error

tokenRequestorTspID (Conditional) Token requestor — token service provider (TR-TSP) ID;

provided by token service providers.
Format: String, numeric; 11 digits.

Device Information
This structure is used by several APIs.

Field Description

deviceID (Conditional) For Secure Element (SE) wallet providers, this value will be
the SE ID in hex binary characters transformed to a 48-character string.
For Host Card Emulation (HCE) wallet providers, this field will be the
Device ID as determined by the digital wallet provider (DWP). All
alphanumeric and special characters are allowed for HCE DWPs.
Secure Element (SE) ID represents the device ID.

l For SE DWPs, this value will be the SE ID in hex binary characters

transformed to a 48-character string.
l For CBP DWPs, this field will be the device ID as determined by the
DWP. All alphanumeric and special characters are allowed for CBP
DWPs.
For Card-on-File (COF) wallets, this value will not be present.
For the initial Check Eligibility request on PAN enrollment, this value
may not be available, however Visa will send this value if it is available.
Format: String; max length 48 characters.

deviceLanguageCode (Optional) This value is any ISO 639 Version 3 Language Code, for
example, eng (English). This language code will be used by the issuer
and Visa to retrieve the Terms and Conditions (T&C). If T&Cs are not
found for the Language Code in the request, the T&Cs will return the
default :anguage Code of eng (English).
Format: String; ISO-639 Version 3 Language Code, max length 3
characters.

6 June 2023 Visa Confidential 195

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

deviceType (Optional) Device type.

Format: It is one of the following values:

l UNKNOWN
l MOBILE_PHONE
l TABLET
l WATCH
l MOBILEPHONE_OR_TABLET
l PC
l HOUSEHOLD_DEVICE
l WEARABLE_DEVICE
l AUTOMOBILE_DEVICE

deviceName (Optional) A readable name for the device. Ideally, the customer enters
this name. It can be used to identify the device in customer support
calls.
Example: My Work Phone
Format: String; Base64URL-encoded; UTF-8; max length 128
characters.

deviceNumber (Optional) Device number.

Format: String; max length 13 characters.

osType (Optional) Type of operating system.

Format: It is one of the following values:

l ANDROID
l IOS
l WINDOWS
l BLACKBERRY
l TIZEN
l OTHER

osVersion (Optional) Version of the operating system running on the device.

Example: 4.4.4
Format: String; max length 32 characters.

osBuildID (Optional) Operating system build identifier.

Example: KTU84M
Format: String; max length 32 characters.

6 June 2023 Visa Confidential 196

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

deviceIDType (Optional) Attribute indicating the source of the Device ID value.

Example: The source for Device ID (deviceID) could be
SecureElement, TEE, or Derived
Format: String; max length 32 characters.

deviceManufacturer (Optional) Manufacturer of the device.

Example: Samsung
Format: String; max length 32 characters.

deviceBrand (Optional) Brand name of the device.

Example: Galaxy
Format: String; max length 32 characters.

deviceModel (Optional) model of the device.

Example: SGH-T999
Format: String; max length 32 characters.

deviceLocation (Optional) Obfuscated geographic location of the device. Initially, when

provisioned, this contains the general location of the device.
Information will be supplied with latitude/longitude rounded to the
nearest whole digit.
Example: +37/-121
Format: String; max length 25 characters.

deviceIndex (Conditional) The index number from Visa where the deviceID is
stored. This is required for token device binding.
Format: Integer; max length 2 digits.

deviceIPAddressV4 (Optional) The IP address of the device at the time of the provisioning
request, with the value represented in 255.255.255.255 format. An
octet (255) may be 1–3 digits in length but cannot contain any leading
zeros.
Format: String; max length 15 characters.

6 June 2023 Visa Confidential 197

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

locationSource (Optional) Source used to identify consumer location.

Format: It is one of the following values:

l WIFI
l CELLULAR
l GPS
l OTHER

tokenProtectionMethod (Optional) Method of token protection.

Format: It is one of the following values:

l SOFTWARE
l TRUSTED_EXECUTION_ENVIRONMENT
l SECURE_ELEMENT
l CLOUD

Terms and Conditions

Field Description

id (Optional) ID for Terms and Conditions that were accepted by the

consumer. It is not returned for Card on File.
Format: Alphabetic, numeric; maximum 36 characters.

date (Optional) Timestamp when Terms and Conditions are acted upon by
consumer. It is not returned for Card on File.
Format: Date. UTC Format in epoch seconds The
UNIX_UTC_timestamp is a UNIX Epoch timestamp. The value is in
seconds.

Response

Successful Response
Successful API responses will return HTTP 200 status code with no payload.

Error Response
The notification API is an asynchronous API and does not need the issuer to return anything to Visa.
The issuer returns the following error statuses, as appropriate, with no response payload, in addition
to “Standard Errors”.

6 June 2023 Visa Confidential 198

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

HTTP Status HTTP Reason Code Description

400 Bad Request The request could not be understood by the server because of
malformed syntax. The client should not repeat the request until
modifications have been made.

401 Unauthorized Authentication credentials were missing or incorrect.

404 Not Found The server has not found anything matching the Request URI.

500 Internal Server Error An unspecified server error has occurred. Visa should attempt to
retry or contact issuer support.

Sample Payloads

Sample Request
{
“messageReasonCode”: “”,
“dateTimeOfEvent”: “”,
“panReferenceID”: “”,
“walletAccountEmailAddressHash”: “”,
“clientWalletAccountId”: “”,
“panSource”: “”,
“addressVerificationResultCode”: “”,
“cvv2ResultsCode”: “”,
“consumerEntryMode”: “”,
“locale”: “”,
“deviceInfo”: {
“deviceID”: “”,
“deviceLanguageCode”: “”,
“osType”: “”,
“osVersion”: “”,
“osBuildID”: “”,
“deviceType”: “”,
“deviceIDType”: “”,
“deviceManufacturer”: “”,
“deviceBrand”: “”,
“deviceModel”: “”,
“deviceName”: “”,
“deviceNumber”: “”,
“deviceLocation”: “”,
“deviceIpAddressV4”: “”,
“locationSource”: “”,
“tokenProtectionMethod”: “”
},
}
“encryptedData”: “<JWS>”
}

All JWS and JWE elements are Base64URL-encoded.

6 June 2023 Visa Confidential 199

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

JWS:
<JWS Header>.<JWS Payload>.<JWS Signature>
JWS payload:
<JWE>
JWE:

<Header>.<Encrypted Key>.<Initialization Vector>.<Ciphertext>.

<Authentication Tag>

Decrypted data contained in JWE ciphertext element:

{
“cardholderInfo”: {
“primaryAccountNumber”: “”,
“expirationDate”: {
“month”: “”,
“year”: “”
},
“highValueCustomer”: “”
},
“tokenInfo”: {
“token”: “”,
“tokenType”: “”,
“tokenStatus”: “”,
“tokenExpirationDate”: {
“month”: “”,
“year”: “”
},
“tokenAssuranceMethod”: “”,
“numberOfActiveTokensForPAN”: “”,
“numberOfInactiveTokensForPAN”: “”,
“numberOfSuspendedTokensForPAN”: “”
},
“riskInformation”: {
“walletProviderRiskAssessment”: “”,
“walletProviderRiskAssessmentVersion”: “”,
“walletProviderAccountScore”: “”,
“walletProviderDeviceScore”: “”,
“walletProviderReasonCodes”: “”,
“deviceBluetoothMac”: “”,
“deviceIMEI”: “”,
“deviceSerialNumber”: “”,
“deviceTimeZone”: “”,
“deviceTimeZoneSetting”: “”,
“osID”: “”,
“simSerialNumber”: “”,
“deviceLostMode”: “”,
“daysSinceConsumerDataLastAccountChange”: “”,
“accountHolderName”: “”,
“walletProviderPANAge”: “”,
“walletAccountHolderCardNameMatch”: “”,
“accountToDeviceBindingAge”: “”,
“userAccountFirstCreated”: “”,

6 June 2023 Visa Confidential 200

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

“provisioningAttemptsOnDeviceIn24Hours”: “”,
“distinctCardholderNames”: “”,
“deviceCountry”: “”,
“walletAccountCountry”: “”,
“suspendedCardsInAccount”: “”,
“daysSinceLastAccountActivity”: “”,
“numberOfTransactionsInLast12months”: “”,
“numberOfActiveTokens”: “”,
“deviceWithActiveTokens”: “”,
“activeTokensOnAllDeviceForAccount”: “”
“visaTokenScore”: “”,
“visaTokenDecisioning”: “”,
“issuerSpecialConditioncodes”: “”
}
}

Token Created Event

https://{Issuer Endpoint}/vtis/v2/tokenRequestors/40010062941
/tokens/DNI../tokenChanged?eventType=TOKEN_CREATED

{
"panReferenceID": "V-30...25",
"walletAccountEmailAddressHash": "5AB...6D",
"clientWalletAccountID": "400...41",
"panSource": "ON_FILE",
"encryptedData": "eyJ...2Q",
"deviceInfo": {
"deviceLanguageCode": "eng",
"tokenProtectionMethod": "CLOUD"
},
"lifeCycleTraceID": 300...56,
"messageReasonCode": "TOKEN_CREATED",
"dateTimeOfEvent": "2020-07-17T22:11:43.000Z",
"actionCode": "00"
}

Sample Successful Response

HTTP 200 Success status with no payload.

Token Notification
This API is exposed by an issuer. Visa will invoke this API call when the issuer's token status has
changed.

Request

6 June 2023 Visa Confidential 201

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Endpoints

Path:

{Issuer Endpoint}/vtis/v2/tokenRequestors/
{tokenRequestorID}/tokens/
{tokenReferenceID}/tokenChanged?eventType=eventType

URL Parameters

Parameter Description

{tokenRequestorID} (Required) Unique ID assigned to the initiator of the token request.

Format: Numeric; max length 11 digits.

{tokenReferenceID} (Required) Unique ID for the token associated with the PAN. This ID can
be used in lieu of the token for subsequent calls, such as lifecycle
events.
Format: String; max length 32 characters.

Method
POST

Query Parameters

Event Type — Token Status Updated

Parameter Description

eventType (Required) Event type.

Format: It is one of the following values:

l TOKEN_STATUS_UPDATED
– Token status updated

6 June 2023 Visa Confidential 202

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Request Body

Field Description

messageReason (Optional) Text-based description of the notification message code.

The descriptions may change and issuers should use the Message
Reason Code for all programmatic actions. This field is for information
only.
Format: String; max length 256 characters.

messageReasonCode (Required) String representation of the message reason, corresponding

to ISO message reason codes when applicable. Additional values may
be available in the future.
Format: It is one of the following values:

l TOKEN_DEACTIVATED
l TOKEN_SUSPEND
l TOKEN_RESUME
l DEVICE_PROVISIONING_RESULT
l OTP_VERIFICATION_RESULT
l CALL_CENTER_ACTIVATION
l MOBILE_BANK_APP_ACTIVATION
l LUK_REPLENISHMENT
l DEVICE_PROVISIONING_REPERSONALIZATION_RESULT
l TOKEN_EXPIRY_DATE_UPDATED
l TOKEN_DEVICE_BINDING_RESULT
l CARDHOLDER_STEPUP_RESULT
l TRUSTED_LISTING_ENROLLMENT_RESULT Reserved for future
use.
l TOKEN_DEVICE_BINDING_REMOVED

dateTimeOfEvent (Required) Event date/timestamp in GMT.

Format: String; yyyy-MM-ddTHH:mm:ss.SSSZ.

panReferenceID (Required) Unique ID for the PAN. This ID can be used in lieu of the
PAN for subsequent calls, such as life cycle events.
Format: String; max length 32 characters.

lifeCycleTraceID (Optional) A message identifier that can be used to link some

messages associated with a provisioning request. This should be used
by the issuer in event/message logging.
Format: Integer; max length 15 digits.

6 June 2023 Visa Confidential 203

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

deviceID (Conditional) For SE wallet providers, this value is the SE ID in hex

binary characters, transformed to a 48–character string. For HCE wallet
providers, this field is the device ID as determined by the digital wallet
provider (DWP). All alphanumeric and special characters are allowed
for HCE DWP’s.
Format: String; max length 48 characters.

encryptedData (Conditional) Blob field that contains the encrypted payload; see
"Cardholder Information" and "Token Information" in the "Encrypted
Payload Data Structures" chapter for more information.
Required if messageReasonCode is one of the following and the
notification contains PII data:

l TOKEN_DEACTIVATED
l TOKEN_SUSPEND
l TOKEN_RESUME
l DEVICE_PROVISIONING_RESULT
l OTP_VERIFICATION_RESULT
l CALL_CENTER_ACTIVATION
l MOBILE_BANK_APP_ACTIVATION
l LUK_REPLENISHMENT
l DEVICE_PROVISIONING_REPERSONALIZATION_RESULT
l TOKEN_EXPIRY_DATE_UPDATED
Format: String; max length 7000 characters.

deviceInfo (Optional) Data associated with the device.

Format: A Device Information structure.

tokenUserInfo (Future) The information of the user that requests the device binding.
Format: A Token User Information structure.

merchantInfo (Future) The information of the merchant that requests the device
binding.
Format: A Merchant Information structure.

actionCode (Required) Contains one of the following action status codes:

Format: It is one of the following values:

l 00 — Good
l 05 — Decline
l 06 — Error

6 June 2023 Visa Confidential 204

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

activationVerificationResult (Conditional) This field contains one of the following verification result
values for OTP_VERIFICATION_RESULT and
MOBILE_BANK_APP_ACTIVATION. Additional values may be available
in the future.
Format: It is one of the following values:

l VERIFICATION_SUCCESS
l VERIFICATION_CODE_EXPIRED
l VERIFICATION_CODE_FAILED
l VERIFICATION_CODE_MISSING
l VERIFICATION_CODE_RETRIES_EXCEEDED

cardHolderStepupResult (Conditional) This field contains one of the following card holder verifi­
cation result values for CARDHOLDER_STEPUP_RESULT. Additional
values may be available in the future.
Format: It is one of the following values:

l CARDHOLDER_STEPUP_OTP
l CARDHOLDER_STEPUP_CALL_CENTER
l CARDHOLDER_STEPUP_ISSUER_APP
l CARDHOLDER_STEPUP_APPROVED

deviceBindingResult (Conditional) This field contains one of the following device binding
result values for TOKEN_DEVICE_BINDING_RESULT. Additional
values may be available in the future.
Format: It is one of the following values:

l DEVICE_BINDING_APPROVED
l DEVICE_BINDING_OTP
l DEVICE_BINDING_CALL_CENTER
l DEVICE_BINDING_ISSUER_APP
l DEVICE_BINDING_REMOVED

trustedListingResult Reserved for future use. (Conditional) This field contains one of the
following trusted listing result values for
TRUSTED_LISTING_ENROLLMENT_RESULT. Additional values may
be available in the future.
Format: It is one of the following values:

l TRUSTED_LISTING_ADDED
l TRUSTED_LISTING_REMOVED

6 June 2023 Visa Confidential 205

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

tokenRequestorTspID (Conditional) Token requestor — token service provider (TR-TSP) ID;

provided by token service providers.
Format: String, numeric; 11 digits.

tokenInfo (Conditional) Data associated with the token for CTF use cases.
Format: A tokenInfo structure.

Token Information

Field Description

token (Conditional) The account number associated with a token. This is a

required field in the following APIs:

l Token Create Notification

l Token Notification
Format: String; max length 19 characters.

tokenType (Conditional) This is a required field in the following APIs:

l Approve Provisioning
l Approve Provisioning Stand-In Notification
l Token Create Notification
Format: It is one of the following values:

l SECURE_ELEMENT
l HCE
l CARD_ON_FILE
l ECOMMERCE
l QRC

tokenStatus (Conditional) This is a required field in the following APIs:

l Token Create Notification

l Token Notification
Format: It is one of the following values:

l ACTIVE
l INACTIVE
l SUSPENDED
l DEACTIVATED

tokenExpirationDate (Conditional) The date upon which the token is set to expire. This field
is required in the Token Create Notification API.
Format: An Expiration Date structure.

6 June 2023 Visa Confidential 206

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

tokenAssuranceMethod (Optional) Method of Issuer ID&V that has taken place at time of
provisioning, device binding, or cardholder initiated verification. It is
one of the following values:

l 00 ID&V Not Performed

l 10 Card Issuer Account Verification
l 11 Card Issuer Interactive Cardholder Verification - 1 Factor
l 12 Card Issuer Interactive Cardholder Verification - 2 Factor
l 13 Card Issuer Risk Oriented Non-Interactive Cardholder Authenti­
cation
l 14 Card Issuer Asserted Authentication
Format: String; max length 2 characters.

numberOfActiveTokensForPAN (Optional) Number of device tokens that are currently active for this
PAN.
Format: Integer; max length 4 digits.

numberOfInactiveTokensForPAN (Optional) Number of device tokens that are currently inactive (device
tokens have not been activated) for this PAN.
Format: Integer; max length 4 digits.

numberOfSuspendedTokensForPAN (Optional) Number of device tokens that were activated, but are
suspended for payments for this PAN.
Format: Integer; max length 4 digits.

tokenActivationDate (Optional) System date/timestamp, in GMT, of token activation into an

active state. For an inactive state, this field is left empty and populated
only when a token transitions to an active state. If a token is
suspended, this field is populated with the new date/timestamp of
when an active state resumes.
Format: String; yyyy-MM-ddTHH:mm:ss.SSSZ.

tokenDeactivationDate (Optional) Date of token deactivation.

Format: String; YYYY-MM-DD.

lastTokenStatusUpdatedTime (Optional) Date/timestamp, in GMT, of the last token status update.

Format: String; yyyy-MM-ddTHH:mm:ss.SSSZ.

originalToken (Conditional) Token account number. This field is populated when

performing token-for-token provisioning only.
Format: String; max length 19 characters.

originalTokenRequestorID (Required) Unique ID assigned to the initiator of the token request. This
field is populated when performing token-for-token provisioning only.
Format: Numeric; max length 11 digits.

6 June 2023 Visa Confidential 207

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

originalTokenReferenceID (Conditional) Unique ID for the token associated with the PAN. This ID
can be used in lieu of the token for subsequent calls, such as life cycle
events. This field is populated when performing token-for-token
provisioning only.
Format: String; max length 32 characters.

originalTokenType (Conditional) Token type of the original token. This field is populated
only when performing token for token provisioning and can be used
only in the following APIs:

l Approve Provisioning
l Approve Provisioning Stand-In Notification
l Token Create Notification
Format: It is one of the following values:

l SECURE_ELEMENT
l HCE
l CARD_ON_FILE
l ECOMMERCE
l QRC
l PSEUDO_ACCOUNT

originaltokenAssuranceMethod (Conditional) Original token assurance method. This field is populated

when performing token-for-token provisioning only. It is one of the
following values:

l 00 ID&V Not Performed

l 10 Card Issuer Account Verification
l 11 Card Issuer Interactive Cardholder Verification - 1 Factor
l 12 Card Issuer Interactive Cardholder Verification - 2 Factor
l 13 Card Issuer Risk Oriented Non-Interactive Cardholder Authenti­
cation
l 14 Card Issuer Asserted Authentication
Format: String; max length 2 characters.

6 June 2023 Visa Confidential 208

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

Field Description

tokenRequestorName (Conditional) Token requester name. Populated when available in the

following APIs:

l Device Token Binding Request

l Get Cardholder Verification Methods
l Send Passcode
l Token Notification
Format: String; max length 100 characters.

autoFillIndicator (Conditional) Indicates whether the token is for an autofill use case.
This is a required field in the following APIs:

l Approve Provisioning
l Approve Provisioning Stand-In Notification
l Token Create Notification
Format: It is one of the following values:

l true — Indicates that the token (e-Commerce Enabler, or Card-on-

File) is for an autofill use case.
l false — Indicates that the token is not for an autofill use case.

Response

Successful Response
HTTP 200 Success status with no payload.

Error Response
The notification API is an asynchronous API and does not need the issuer to return anything to Visa.
The issuer returns the following error statuses, as appropriate, with no response payload, in addition
to “Standard Errors”.

HTTP Status HTTP Reason Code Description

400 Bad Request The request could not be understood by the server because of
malformed syntax. The client should not repeat the request until
modifications have been made.

401 Unauthorized Authentication credentials were missing or incorrect.

6 June 2023 Visa Confidential 209

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

HTTP Status HTTP Reason Code Description

404 Not Found The server has not found anything matching the Request URI.

500 Internal Server Error An unspecified server error has occurred. Visa should attempt to
retry or contact issuer support.

Sample Payloads

Sample Request
{
"messageReason": "TOKEN_DEVICE_BINDING_RESULT",
"messageReasonCode": "TOKEN_DEVICE_BINDING_RESULT",
"dateTimeOfEvent": "2020-03-02T18:56:16.947Z",
"panReferenceID": "V-58...42",
"deviceID": "95c...0b",
"encryptedData": "eyJ...pw",
"actionCode": "00",
"deviceBindingResult": "DEVICE_BINDING_ISSUER_APP",
"deviceInfo": {
"deviceID": "95c...0b",
"deviceIndex": 1
}
}

All JWS and JWE elements are URL encoded.

JWS:
<JWS Header>.<JWS Payload>.<JWS Signature>
JWS payload:
<JWE>
JWE:

<Header>.<Encrypted Key>.<Initialization Vector>.<Ciphertext>.

<Authentication Tag>

Decrypted data contained in JWE ciphertext element:

{
“cardholderInfo”: {
“primaryAccountNumber”: “”
},
“tokenInfo”:{
“token”: “”,
“tokenType”: “”,
“tokenStatus”: “”,

6 June 2023 Visa Confidential 210

Visa Token Service – Issuer API Specifications (JSON)
Outbound API Specifications (From Visa)

“tokenExpirationDate”: {
“month”: “”,
“year”: “”
},
}
}

Note:  
For a complete list of possible contents for the encrypted payload, see “Encrypted Payload
Data.”

Sample Successful Response

HTTP 200 Success status with no payload.

6 June 2023 Visa Confidential 211

Chapter 7
Visa Card Enrollment Hub (VCEH)

Push Card Enrollment to Wallet API

This API allows issuers to push card enrollments to participating token requestors.
Issuer can call this API to initiate a push provisioning via Visa Card Enrollment Hub (VCEH). Visa will
validate the request and send an acknowledgment back to the issuer. Upon successful validation, Visa
will forward the provisioning request to token requestor. One request can send push provisioning to
multiple token requestor, which are associated with the same PAN and email address or phone
number.

Request

Endpoints

Path:

{Visa host}/vtis/v1/pushCardEnrollmentToWallet?apiKey=key

6 June 2023 Visa Confidential 212

Visa Token Service – Issuer API Specifications (JSON)
Visa Card Enrollment Hub (VCEH)

Method
POST

Query Parameters

Parameter Description

apiKey (Required) Client-specific API Key issued during onboarding.

Format: String; alphabetic, numeric; max length 64 characters.

Request Body

Field Description

encryptedData (Required) BLOB field (Base64URL–encoded) that represents the

encrypted payload for the payment instrument. JWS with RSA PKI
scheme using PKI made available at the time of onboarding.
Format: An Encrypted Payment Instrument structure; max 8192 bytes.

route (Optional) The route by which to reach the token requestor for the
enrollment. It is one of the following values:

l SYNC_DIRECT – Issuer manages the interaction with token

requestor. Response will include a URI to launch the token
requestor's app.
l ASYNC (default) – VCEH will notify the token requestor of this
enrollment by calling their backend API.

uriType (Conditional) The kind of app to launch at the token requestor's URI.
Required if the route is SYNC_DIRECT. It is one of the following
values:

l IOS — iOS app

l ANDROID — Android app
l WEB — Browser-based app

Unencrypted Data

6 June 2023 Visa Confidential 213

Visa Token Service – Issuer API Specifications (JSON)
Visa Card Enrollment Hub (VCEH)

Enrollment

Field Description

tsp (Required) Token service provider.

Format: It is one of the following values:

l V — Visa
l MC — Mastercard

paymentInstrument (Conditional) Payment instrument.

Only populate this field, if tsp is V.
Format: A paymentInstrument structure.

payload (Conditional) A BLOB from a non-Visa TSP.

Only populate this field, if tsp is not V.
Format: String; maximum 256 characters.

Payment Instrument

Field Description

accountNumber (Required) Primary account number of the card to be enrolled and

provisioned.
Format: String; max length 19 characters.

name (Optional) The full name on the Visa card associated with the enrolled
payment instrument.
Format: String; UTF-8; max length 256 characters.

expirationDate (Optional) Expiration date of the payment instrument.

Format: An Expiration Date structure.

billingAddress (Optional) Billing address associated with the payment instrument.

Format: An Address structure.

Expiration Date
This structure is used by several APIs.

6 June 2023 Visa Confidential 214

Visa Token Service – Issuer API Specifications (JSON)
Visa Card Enrollment Hub (VCEH)

Field Description

month (Required) The month upon which the payment instrument is set to
expire.
Example: "month": "9"
Format: String; numeric; max length 2 digits.

year (Required) The year upon which the payment instrument is set to
expire.
Example: "year": "2024"
Format: String; numeric; length 4 digits.

Address
This structure is used by several APIs.

Field Description

line1 (Optional) First line associated with the address.

Format: String; alphanumeric; UTF-8, white space, comma (,),
underscore (_), hashtag (#), colon (:), forward slash (/), period (.), single
quote (‘), asterisk (*), and hyphens (-) are allowed; max length 64
characters.

line2 (Optional) Second line associated with the address.

Format: String; alphanumeric; UTF-8, white space, comma (,),
underscore (_), hashtag (#), colon (:), forward slash (/), period (.), single
quote (‘), asterisk (*), and hyphens (-) are allowed; max length 64
characters.

city (Optional) City associated with the address.

Format: String; alphanumeric; UTF-8, white space, carat (^), period (.),
single quote (‘), asterisk (*), and hyphens (-) are allowed; max length 32
characters.

state (Optional) State or province code associated with the address.

Example: NY
Format: String; ISO 3166-2; max length 2 characters.

postalCode (Optional) The postal code associated with the address.

Format: String; alphanumeric, valid for the country; whitespace and
hyphens (-) are allowed; max length 10 characters.

country (Optional) Code for a country; default is US.

Example: US
Format: String; ISO 3166-1 alpha-2; max length 2 characters.

6 June 2023 Visa Confidential 215

Visa Token Service – Issuer API Specifications (JSON)
Visa Card Enrollment Hub (VCEH)

Payment Instrument Provider

Field Description

intent (Required) The intent of the encryption; what is the encryption of the
data trying to do.
Specify PUSH_PROV_ONFILE for Secure Remote Commerce.
Format: It is one of the following values:

l PUSH_PROV_CROSS_USER
l PUSH_PROV_CROSS_DEVICE
l PUSH_PROV_ONFILE
l PUSH_PROV_MOBILE

clientWalletProvider (Optional) The token requestor’s ID (tokenRequestorID), to which

the client wants to add the credential.
Format: String, alphabetic, numeric, hyphens ( - ), underscores ( _ ),
e.g. spaces are not allowed; and max length 50 characters.

clientWalletAccountID (Optional) Client-provided consumer ID that identifies the wallet

account holder’s entity.
Format: String; alphabetic, numeric, hyphens ( - ), underscores ( _ ),
e.g. spaces are not allowed; max length 24 characters.

clientDeviceID (Optional) Unique identifier set by wallet provider for the device. When
a wallet provider enrolls the PAN, the clientDevicetId field should
have the same value.
Format: String; max length 24 characters.

clientAppID (Optional) Unique Identifier for the client application, used to provide
some of the encrypted values. Example: Issuer’s AppID
(vClientAppID) used to select the PAN and the wallet.
Format: String; max length 36 characters.

isIDnV (Optional) Whether the issuer wants ID&V to be performed.

Format: It is one of the following values:

l true
l false

issuerAccountID (Conditional) Uniquely represents “pushing” account from issuer

system. May be different from PAN holder account. Required for
Secure Remote Commerce.
Format: String; alphabetic, numeric, hyphens ( - ), underscores ( _ ),
e.g. spaces are not allowed; and max length 24 characters.

6 June 2023 Visa Confidential 216

Visa Token Service – Issuer API Specifications (JSON)
Visa Card Enrollment Hub (VCEH)

Field Description

issuerClientInformation (Required) Client information shared from issuer to token requestor as

per information captured in the issuer systems about the PAN owner.
This information will be decrypted and shared with the token
requestor.
Format: A Client Information structure.

passcode (Optional) Passcode generated by the issuer. Do not specify for Secure
Remote Commerce.
Format: A Passcode structure.

returnURIType (Optional) The kind of URI for the return app.

Format: It is one of the following values:

l IOS— iOS app

l ANDROID— Android app
l WEB— Browser-based app

returnURI (Optional) URI provided by the issuer to the token requestor to return
control to the issuer app. This can be an app or a web URL.

Format: String; Base64URL-encoded; max length 512 characters.

issuerTraceID (Required) This ID is used to uniquely identify a JWE received from the
issuer. Used to address vulnerability to replay attacks.
Format: String; max length 32 characters.

isTsAndCsAccepted (Optional) Value set by the issuer to indicate to the wallet provider
whether or not the customer already accepted the issuer terms and
conditions up-front. If true, the wallet provider can suppress
displaying terms and conditions to the customer and just submit the
terms and conditions GUID to Visa as though the customer has already
accepted the terms and conditions.
Format: It is one of the following values:

l true
l false (default)

6 June 2023 Visa Confidential 217

Visa Token Service – Issuer API Specifications (JSON)
Visa Card Enrollment Hub (VCEH)

Client Information

Field Description

source (Optional) Indicates the source of the information.

Format: It is one of the following values:

l ISSUER
l TOKEN_REQUESTOR

clientWalletAccountID (Optional) Client-provided consumer ID that identifies the wallet

account holder’s entity.
Format: String; alphabetic, numeric, hyphens ( - ), underscores ( _ ),
e.g. spaces are not allowed; max length 24 characters.

firstName (Conditional) First name of client. Issuer to populate with the

information they have for the client. Required for issuer push token
provisioning across user or across device.
Format: String, max length 80 characters.

middleName (Conditional) Middle name of the client. Issuer to populate with the
information they have for the client. Required for issuer push token
provisioning across user or across device.
Format: String; max length 80 characters.

lastName (Conditional) Last name of the client. Issuer to populate with the
information they have for the client. Required for issuer push token
provisioning across user or across device.
Format: String; max length 80 characters.

issuerAccountID (Conditional) Issuer account ID as provided by the issuer to the token

requestor. Required for Secure Remote Commerce.
Format: String; alphabetic, numeric, hyphens ( - ), underscores ( _ ),
e.g. spaces are not allowed; max length 24 characters.

clientDeviceID (Conditional) Unique identifier set by wallet provider for the device.
Required for device token in status notification to issuer from Visa or in
client information returned to issuer by token requestor.
Format: String; max length 24 characters.

tokenReferenceID (Conditional) A unique ID associated with a single token. The ID is

created upon initial provisioning of a token to a device. Required for
successful provisioning in status notification to issuer from Visa or in
client information returned to issuer by token requestor.
Format: String; max length 32 characters.

paymentAccountReference (Optional) Payment account reference ID if available for this payment

instrument.
Format: String; alphabetic, numeric; max length 29 characters.

6 June 2023 Visa Confidential 218

Visa Token Service – Issuer API Specifications (JSON)
Visa Card Enrollment Hub (VCEH)

Field Description

phoneNumber (Conditional) Mobile phone number of the client as per issuer records.
Either phone number or contact email must be provided. Phone
numbers do not contain country codes.
Format: String, max 16 characters.

contactEmail (Conditional) Email address of client as per issuer records. Either phone
number or contact email must be provided.
Format: String; UTF-8; max length 48 characters.

country (Optional) Country code. Default is US.

Format: String; alphabetic, ISO 3166-1 alpha-2, max length 2
characters.

locale (Optional) Language in which the app communicates with the

customer. The language and country should be separated using an
underscore (_). The default is en_US.
Format: String; ISO format for language (ISO 639-1) and alpha-2
country code (ISO 3166-1 alpha-2); max length 5 characters.

campaignID (Optional) Co-brand campaign identifier.

Format: String; alphabetic, numeric, hyphens ( - ), underscores ( _ ),
e.g. spaces are not allowed; max length 100 characters.

campaignDescription (Optional) Co-brand campaign description.

Format: String; alphabetic, numeric, hyphens ( - ), underscores ( _ ),
and spaces; max length 250 characters.

Passcode

Field Description

type (Required) More values can be added to this enum in the future.
Format: It is one of the following values:

l PASSCODE

value (Conditional) The passcode generated by the issuer and validated by

Visa during PAN enrollment. Do not provide if the Payment Instrument
Provider’s intent is PUSH_PROV_ONFILE; otherwise it is required.
Format: String; max length 50 characters.

6 June 2023 Visa Confidential 219

Visa Token Service – Issuer API Specifications (JSON)
Visa Card Enrollment Hub (VCEH)

Field Description

passCodeConversationID (Conditional) This is returned when a passcode is required.

passCodeConversationID is returned to Visa by the token
requestor in a subsequent Enroll PAN call. This attribute should not be
sent by the issuer. If the issuer sends a value for this attribute in the
encrypted payment instrument, it should be ignored.
Format: String; max length 32 characters.

maxRetries (Optional) Number of times the One-Time Password (OTP) can be

retried.
Format: Integer.

Response

Successful Response
Successful API responses will return HTTP status code in the 2xx range. The response body, if
available, will contain the response of the API as described in this specification.

Field Description

status Format: It is the following values:

ACCEPTED— With HTTP Status code 200.

uri URI to launch VCEH web UI or token requestor app. The URI depends
on the kind of route.
Format: It is the following templates; max 2048 characters:

l For SYNC_VCEH_WEB routes, it is a URI to launch a VCEH_WEB

proxy, as in the following example:

https://VCEH_URL/pushCardEnrollment/
v1#session=sessionId

l For SYNC_DIRECT routes, it is a URI to launch to a token requestor

app, as in the following example:

TR URI scheme?pushData="JWS payload per TR

spec"

Error Responses
If a business error is present, it is assumed that no “Standard Errors” were detected in the API
request.

6 June 2023 Visa Confidential 220

Visa Token Service – Issuer API Specifications (JSON)
Visa Card Enrollment Hub (VCEH)

VTS domain-specific business error reason codes are as follows:

HTTP Status Error Code Error Code Description

400 VSE40000 VSE_ERROR_INVALID_DATA

400 VSE40010 VSE_ERROR_CRYPTOGRAPHY_ERROR

500 VSE40009 VSE_INTERNAL_SYSTEM_ERROR

Sample Payloads

Sample Request
{
"encryptedData": "<JWS>",
"route": "SYNC_DIRECT",
"uriType": "ANDROID"
}

All JWS and JWE elements are Base64URL-encoded.

JWS:
<JWS Header>.<JWS Payload>.<JWS Signature>

{
"iss": "e93...01", // vClientID of Issuer
"aud": "781...9a", // vClientID of Token Requestor
"kid": "83F4EEB2",
"typ": "JOSE",
"enc": "A256GCM",
"iat": 1588891891,
"alg": "RSA-OAEP-256",
"exp": "1590091891"
}

JWS payload:
<JWE>
JWE:
Note:  You must set the iss and aud fields in the JWE header.

<Header>.<Encrypted Key>.<InitializationVector>.<Ciphertext>.
<Authentication Tag>

6 June 2023 Visa Confidential 221

Visa Token Service – Issuer API Specifications (JSON)
Visa Card Enrollment Hub (VCEH)

Unencrypted Payment Instrument:

{
"enrollments": [
{
"paymentInstrument": {
"accountNumber": "414...88",
"expirationDate": {
"month": "12",
"year": "2022"
},
"name": "VTS",
"billingAddress": {
"line1": "801MetroCentreBlvd",
"line2": "second floor",
"line3": "suite 90",
"line4": "metrocenter",
"line5": "metrocenter5",
"city": "FosterCity",
"postalCode": "94404",
"state": "CA",
"country": "US"
}
},
"tsp": "V"
}
],
"provider": {
"intent": "PUSH_PROV_ONFILE",
"clientWalletProvider": "40000000052",
"clientWalletAccountID": "clientWalletHolderentity",
"clientDeviceID": "0_enOI",
"clientAppID": "bbe4c1f7-1df7-4aef-9e8f-726504c4b87b",
"isIDnV": false,
"issuerClientInformation": {
"source": "ISSUER",
"firstName": "ClientFristName",
"lastName": "ClientLastName",
"issuerAccountID": "4147780005805070",
"clientDeviceID": "0_enOI",
"tokenReferenceID": "DNITHE381919776682001531",
"paymentAccountReference": "asdascac",
"phoneNumber": "...",
"contactEmail": "...",
"locale": "en_US",
"campaignID": "dd",
"campaignDescription": "qwedwefvwewsvb234234 _kwmkwrfr-",
"userPersonalID": "w214234"
},
"passcode": {
"maxRetries": "3",
"value": "zOZYuS",
"type": "PASSCODE"
},
"returnURIType": "IOS",
"returnURI": "aHR0cDovL2JhbmtvZmFtZXJpY2EuY29t",
"issuerTraceID": "0TDFfL1OmJJ5AHONhn5Z2GxTS5ZOoVja"

6 June 2023 Visa Confidential 222

Visa Token Service – Issuer API Specifications (JSON)
Visa Card Enrollment Hub (VCEH)

}
}

Sample Response

SYNC_DIRECT Route

{
"status": "ACCEPTED",
"uri": "https://www.testapp.com?pushData=eyJhbGciOiJQUzI"
}

ASYNC Route

{
"status": "ACCEPTED"
}

VCEH Web Proxy

The Visa Card Enrollment Hub (VCEH) enables cardholders to enroll their payment credentials to any
merchant of their choice through their issuer app/web.

VCEH Proxy Request

Issuer app launches the default web browser with the pushCardEnrollment request:
Sandbox

GET https://vceh.sandbox.consumerapi.digital.visa.com/
vceh/pushCardEnrollment/v1#pushData=<JWS<JWE>>

Live

GET https://vceh.consumerapi.digital.visa.com/
vceh/pushCardEnrollment/v1#pushData=<JWS<JWE>>

VCEH then invokes the token requestor’s app/web on the customer device to complete enrollment.

pushData Request

6 June 2023 Visa Confidential 223

Visa Token Service – Issuer API Specifications (JSON)
Visa Card Enrollment Hub (VCEH)

JWS Header

Field Description

iat (Required) Timestamp (in UTC) when JWE was issued, expressed in
UNIX epoch time (seconds since 1 January, 1970).
Format: String; numeric digits

alg (Required) Description of the algorithm used to encrypt the randomly

generated symmetric Content Encryption Key (CEK).
Format: Value is PS256.

kid (Required) Key identifier that identifies the key used to encrypt the
CEK, which is the Issuer’s API key.
Format: String; max length 64 characters.

JWE Header

Field Description

iat (Required) Timestamp (in UTC) when JWE was issued, expressed in
UNIX epoch time (seconds since 1 January, 1970).
Format: String; numeric digits

alg (Required) Description of the algorithm used to encrypt the randomly

generated symmetric Content Encryption Key (CEK).
Format: Value is A256GCMKW.

kid (Required) Key identifier that identifies the key used to encrypt the
CEK, which is the Issuer’s API key.
Format: String; max length 64 characters.

exp (Optional) Expiration time of the payload. This field is optional and
should be evaluated in conjunction with the ttl default defined with
use case.
exp can be used to reduce the default ONLY. If exp represents a time
greater than iat + ttl then iat + ttl will be used.
Format: yyyy-MM-ddTHH:mm:ss.SSSZ.

iss (Required) Message originator's client ID, which is the issuer's

vClientID of the issuer that has been registered with VDCS.
Format: String; alphanumeric; max length 64 characters.

aud (Required) Desired recipient, which is a token requestor's vClientID

value that has been registered with VCEH.
Format: String; alphanumeric; max length 256 characters.

JWE Body

Encrypted data should be a JSON payload with following structure.

6 June 2023 Visa Confidential 224

Visa Token Service – Issuer API Specifications (JSON)
Visa Card Enrollment Hub (VCEH)

Field Description

enrollments (Required) An array of enrollment payloads, which identify the token

service provider (TSP) and contains an opaque payload from the TSP.
Format: An array of 10 or fewer enrollment payloads.

provider (Required) Information from the provider of the payment instrument

and the context under which it is provided.
Format: A payment instrument provider.

Enrollment

Field Description

tsp (Required) Token service provider.

Format: It is one of the following values:

l V — Visa
l MC — Mastercard

paymentInstrument (Conditional) Payment instrument.

Only populate this field, if tsp is V.
Format: A paymentInstrument structure.

payload (Conditional) A BLOB from a non-Visa TSP.

Only populate this field, if tsp is not V.
Format: String; maximum 256 characters.

Payment Instrument

Field Description

accountNumber (Required) Primary account number of the card to be enrolled and

provisioned.
Format: String; max length 19 characters.

cvv2 (Optional) CVV2 value associated with the primary account number on
the card.
Format: String; max length 4 characters.

name (Optional) The full name on the Visa card associated with the enrolled
payment instrument.
Format: String; UTF-8; max length 256 characters.

6 June 2023 Visa Confidential 225

Visa Token Service – Issuer API Specifications (JSON)
Visa Card Enrollment Hub (VCEH)

Field Description

expirationDate (Conditional) Expiration date of the payment instrument; required for

Secure Remote Commerce.
Format: An Expiration Date structure.

billingAddress (Conditional) Billing address associated with the payment instrument;

required for Secure Remote Commerce and if the billing address is
shared with a token requestor in the Get Push Enrollment Info API.
Format: An Address structure.

Expiration Date
This structure is used by several APIs.

Field Description

month (Required) The month upon which the payment instrument is set to
expire.
Example: "month": "9"
Format: String; numeric; max length 2 digits.

year (Required) The year upon which the payment instrument is set to
expire.
Example: "year": "2024"
Format: String; numeric; length 4 digits.

Address
This structure is used by several APIs.

Field Description

line1 (Optional) First line associated with the address.

Format: String; alphanumeric; UTF-8, white space, comma (,),
underscore (_), hashtag (#), colon (:), forward slash (/), period (.), single
quote (‘), asterisk (*), and hyphens (-) are allowed; max length 64
characters.

line2 (Optional) Second line associated with the address.

Format: String; alphanumeric; UTF-8, white space, comma (,),
underscore (_), hashtag (#), colon (:), forward slash (/), period (.), single
quote (‘), asterisk (*), and hyphens (-) are allowed; max length 64
characters.

city (Optional) City associated with the address.

Format: String; alphanumeric; UTF-8, white space, carat (^), period (.),
single quote (‘), asterisk (*), and hyphens (-) are allowed; max length 32
characters.

6 June 2023 Visa Confidential 226

Visa Token Service – Issuer API Specifications (JSON)
Visa Card Enrollment Hub (VCEH)

Field Description

state (Optional) State or province code associated with the address.

Example: NY
Format: String; ISO 3166-2; max length 2 characters.

postalCode (Optional) The postal code associated with the address.

Format: String; alphanumeric, valid for the country; whitespace and
hyphens (-) are not supported; max length 10 characters.

country (Optional) Code for a country; default is US.

Example: US
Format: String; ISO 3166-1 alpha-2; max length 2 characters.

Payment Instrument Provider

Field Description

intent (Required) The intent of the encryption; what is the encryption of the
data trying to do.
Specify PUSH_PROV_ONFILE for Secure Remote Commerce.
Format: It is one of the following values:

l PUSH_PROV_CROSS_USER
l PUSH_PROV_CROSS_DEVICE
l PUSH_PROV_ONFILE
l PUSH_PROV_MOBILE

clientWalletProvider (Optional) The token requestor’s ID (tokenRequestorID), to which

the client wants to add the credential.
Format: String, alphabetic, numeric, hyphens ( - ), underscores ( _ ),
e.g. spaces are not allowed; and max length 50 characters.

clientWalletAccountID (Optional) Client-provided consumer ID that identifies the wallet

account holder’s entity.
Format: String; alphabetic, numeric, hyphens ( - ), underscores ( _ ),
e.g. spaces are not allowed; max length 24 characters.

clientDeviceID (Optional) Unique identifier set by wallet provider for the device. When
a wallet provider enrolls the PAN, the clientDevicetId field should
have the same value.
Format: String; max length 24 characters.

clientAppID (Optional) Unique Identifier for the client application, used to provide
some of the encrypted values. Example: Issuer’s AppID
(vClientAppID) used to select the PAN and the wallet.
Format: String; max length 36 characters.

6 June 2023 Visa Confidential 227

Visa Token Service – Issuer API Specifications (JSON)
Visa Card Enrollment Hub (VCEH)

Field Description

isIDnV (Optional) Whether the issuer wants ID&V to be performed.

Format: It is one of the following values:

l true
l false

issuerAccountID (Conditional) Uniquely represents “pushing” account from issuer

system. May be different from PAN holder account. Required for
Secure Remote Commerce.
Format: String; alphabetic, numeric, hyphens ( - ), underscores ( _ ),
e.g. spaces are not allowed; and max length 24 characters.

issuerClientInformation (Required) Client information shared from issuer to token requestor as

per information captured in the issuer systems about the PAN owner.
This information will be decrypted and shared with the token
requestor.
Format: A Client Information structure.

passcode (Optional) Passcode generated by the issuer. Do not specify for Secure
Remote Commerce.
Format: A Passcode structure.

returnURIType (Optional) The kind of URI for the return app.

Format: It is one of the following values:

l IOS— iOS app

l ANDROID— Android app
l WEB— Browser-based app

returnURI (Optional) URI provided by the issuer to the token requestor to return
control to the issuer app. This can be an app or a web URL.

Format: String; Base64URL-encoded; max length 512 characters.

issuerTraceID (Required) This ID is used to uniquely identify a JWE received from the
issuer. Used to address vulnerability to replay attacks.
Format: String; max length 32 characters.

isTsAndCsAccepted (Optional) Value set by the issuer to indicate to the wallet provider
whether or not the customer already accepted the issuer terms and
conditions up-front. If true, the wallet provider can suppress
displaying terms and conditions to the customer and just submit the
terms and conditions GUID to Visa as though the customer has already
accepted the terms and conditions.
Format: It is one of the following values:

l true
l false (default)

6 June 2023 Visa Confidential 228

Visa Token Service – Issuer API Specifications (JSON)
Visa Card Enrollment Hub (VCEH)

Client Information

Field Description

source (Optional) Indicates the source of the information.

Format: It is one of the following values:

l ISSUER
l TOKEN_REQUESTOR

clientWalletAccountID (Optional) Client-provided consumer ID that identifies the wallet

account holder’s entity.
Format: String; alphabetic, numeric, hyphens ( - ), underscores ( _ ),
e.g. spaces are not allowed; max length 24 characters.

firstName (Conditional) First name of client. Issuer to populate with the

information they have for the client. Required for issuer push token
provisioning across user or across device.
Format: String, max length 80 characters.

middleName (Conditional) Middle name of the client. Issuer to populate with the
information they have for the client. Required for issuer push token
provisioning across user or across device.
Format: String; max length 80 characters.

lastName (Conditional) Last name of the client. Issuer to populate with the
information they have for the client. Required for issuer push token
provisioning across user or across device.
Format: String; max length 80 characters.

issuerAccountID (Conditional) Issuer account ID as provided by the issuer to the token

requestor. Required for Secure Remote Commerce.
Format: String; alphabetic, numeric, hyphens ( - ), underscores ( _ ),
e.g. spaces are not allowed; max length 24 characters.

clientDeviceID (Conditional) Unique identifier set by wallet provider for the device.
Required for device token in status notification to issuer from Visa or in
client information returned to issuer by token requestor.
Format: String; max length 24 characters.

tokenReferenceID (Conditional) A unique ID associated with a single token. The ID is

created upon initial provisioning of a token to a device. Required for
successful provisioning in status notification to issuer from Visa or in
client information returned to issuer by token requestor.
Format: String; max length 32 characters.

paymentAccountReference (Optional) Payment account reference ID if available for this payment

instrument.
Format: String; alphabetic, numeric; max length 29 characters.

6 June 2023 Visa Confidential 229

Visa Token Service – Issuer API Specifications (JSON)
Visa Card Enrollment Hub (VCEH)

Field Description

phoneNumber (Conditional) Mobile phone number of the client as per issuer records.
Either phone number or contact email must be provided. Phone
numbers do not contain country codes.
Format: String, max 16 characters.

contactEmail (Conditional) Email address of client as per issuer records. Either phone
number or contact email must be provided.
Format: String; UTF-8; max length 48 characters.

country (Optional) Country code. Default is US.

Format: String; alphabetic, ISO 3166-1 alpha-2, max length 2
characters.

locale (Optional) Language in which the app communicates with the

customer. The language and country should be separated using an
underscore (_). The default is en_US.
Format: String; ISO format for language (ISO 639-1) and alpha-2
country code (ISO 3166-1 alpha-2); max length 5 characters.

campaignID (Optional) Co-brand campaign identifier.

Format: String; alphabetic, numeric, hyphens ( - ), underscores ( _ ),
e.g. spaces are not allowed; max length 100 characters.

campaignDescription (Optional) Co-brand campaign description.

Format: String; alphabetic, numeric, hyphens ( - ), underscores ( _ ),
and spaces; max length 250 characters.

Passcode

Field Description

type (Required) More values can be added to this enum in the future.
Format: It is one of the following values:

l PASSCODE

value (Conditional) The passcode generated by the issuer and validated by

Visa during PAN enrollment. Do not provide if the Payment Instrument
Provider’s intent is PUSH_PROV_ONFILE; otherwise it is required.
Format: String; max length 50 characters.

6 June 2023 Visa Confidential 230

Visa Token Service – Issuer API Specifications (JSON)
Visa Card Enrollment Hub (VCEH)

Field Description

passCodeConversationID (Conditional) This is returned when a passcode is required.

passCodeConversationID is returned to Visa by the token
requestor in a subsequent Enroll PAN call. This attribute should not be
sent by the issuer. If the issuer sends a value for this attribute in the
encrypted payment instrument, it should be ignored.
Format: String; max length 32 characters.

maxRetries (Optional) Number of times the One-Time Password (OTP) can be

retried.
Format: Integer.

VCEH Returns to Issuer App

The VCEH web UI redirects the user back to issuer’s app specified by the Issuer Return URI, which is
specified in the returnURI field in Issuer’s pushData. The URL parameter results carries the
enrollment results:

[Issuer Return URI]?results=<JWS <JWE payload >>

results Response

JWS Header

Field Description

iat (Required) Timestamp (in UTC) when JWE was issued, expressed in
UNIX epoch time (seconds since 1 January, 1970).
Format: String; numeric digits

alg (Required) Description of the algorithm used to encrypt the randomly

generated symmetric Content Encryption Key (CEK).
Format: Value is PS256.

kid (Required) Key identifier that identifies the key used to encrypt the
CEK, which is the Issuer’s API key.
Format: String; max length 64 characters.

6 June 2023 Visa Confidential 231

Visa Token Service – Issuer API Specifications (JSON)
Visa Card Enrollment Hub (VCEH)

JWE Header

Field Description

iat (Required) Timestamp (in UTC) when JWE was issued, expressed in
UNIX epoch time (seconds since 1 January, 1970).
Format: String; numeric digits

results JWE Body

Field Description

enrollments An array of enrollment results, which identify the token service

provider and contains an opaque payload from the TSP.
Format: An array of 10 or fewer enrollments.

issuerTraceId The issuerTraceId in the pushData parameter from the issuer.

Format: String; maximum 32 characters.

error An error response.

Format: An error response structure.

Enrollment Results

Field Description

tsp Token service provider.

Format: It is one of the following values:

l V — Visa
l MC — Mastercard

payload An opaque payload for the TSP, which is passed to the TSP for token
provisioning. For Visa cards, it contains the last 4 digits of the PAN
Format: String; maximum 256 characters.

status Enrollment status.

Format: It is one of the following values:

l PENDING — Enrollment is pending at token requestor.

l SUCCESS — The payment instrument is enrolled successfully
l CANCEL — User cancels the enrollment

6 June 2023 Visa Confidential 232

Visa Token Service – Issuer API Specifications (JSON)
Visa Card Enrollment Hub (VCEH)

Error Response

Field Description

code Error code.

Format: String.

message Error message.

Format: String; maximum 256 characters.

Sample Payloads
Issuer to VCEH
Invocation URL

POST https://vceh.sandbox.consumerapi.digital.visa.com/
vceh-web/pushCardEnrollment/v1#pushData=eyJr...dQ

JWS Header

{"alg":"PS256","typ":"JOSE","kid":"QS0...Tc"}

JWE Header

{"iss":"d1c...01","aud":"3ee...01","exp":"1615231207",
"alg":"A256GCMKW","enc":"A256GCM","typ":"JOSE",
"kid":"bb...8","iat":"1614367207"}

Decrypted pushData field

{
"enrollments": [
{
"tsp": "V",
"paymentInstrument": {
"accountNumber": "...",
"expirationDate": {
"month": "12",
"year": "2022"
},
"name": "...",
"billingAddress": {
"state": "CA",
"line1": "...",
"country": "US",
"city": "FosterCity",
"postalCode": "94404"
}
}

6 June 2023 Visa Confidential 233

Visa Token Service – Issuer API Specifications (JSON)
Visa Card Enrollment Hub (VCEH)

},
{
"tsp": "V",
"paymentInstrument": {
"accountNumber": "...",
"expirationDate": {
"month": "12",
"year": "2022"
},
"name": "...",
"billingAddress": {
"state": "CA",
"line1": "...",
"country": "US",
"city": "FosterCity",
"postalCode": "94404"
}
}
},
{
"tsp": "MC",
"payload": "8sC5xeRoAx"
},
{
"tsp": "MC",
"payload": "VwjUW5pohd"
}
],
"provider": {
"intent": "PUSH_PROV_ONFILE",
"issuerAccountID": "customerid",
"issuerClientInformation": {
"phoneNumber": "...",
"contactEmail": "...",
"firstName": "...",
"middleName": "...",
"lastName": "..."
},
"returnURI": "aHR...==",
"issuerTraceID": "Jss...Vf",
"returnURIType": "IOS",
"isTsAndCsAccepted": "true"
}
}

VCEH to Issuer
Return URL:

[Issuer Return URI]?results=eyJ...tw

Decrypted results field:

{
"enrollments": [
{

6 June 2023 Visa Confidential 234

Visa Token Service – Issuer API Specifications (JSON)
Visa Card Enrollment Hub (VCEH)

"status": "SUCCESS",
"payload": "5865",
"tsp": "V"
},
{
"status": "PENDING",
"payload": "6960",
"tsp": "V"
},
{
"status": "CANCEL",
"payload": "5238",
"tsp": "V"
},
{
"status": "SUCCESS",
"payload": "FsbH7qcWy3",
"tsp": "MC"
},
{
"status": "PENDING",
"payload": "53YPZ5iIK2",
"tsp": "MC"
},
{
"status": "CANCEL",
"payload": "XIVpdNFIxa",
"tsp": "MC"
}
],
"issuerTraceId": "s0D...SM"
}

Push Provisioning Status Notification

This API is exposed by an issuer. Visa will invoke this API to send notification to issuer for updating
the push provisioning status. The notification is per wallet provider per provisioning action. If the
issuer pushes a payment instrument to multiple wallet providers, it will receive multiple notifications
for that payment instrument.

Request

6 June 2023 Visa Confidential 235

Visa Token Service – Issuer API Specifications (JSON)
Visa Card Enrollment Hub (VCEH)

Endpoints

Path:

{Issuer Endpoint}/vtis/v1/tokenRequestors/
{tokenRequestorID}/cardEnrollment/notification?eventType=eventType

URL Parameters

Parameter Description

{tokenRequestorID} (Required) Unique ID assigned to the initiator of the token request.

Format: Numeric; max length 11 digits.

Method
POST

Query Parameters

Parameter Description

eventType (Required) Requested event type.

Format: It is one of the following values:

l PUSH_PROVISIONING_STATUS
— push provisioning notification

6 June 2023 Visa Confidential 236

Visa Token Service – Issuer API Specifications (JSON)
Visa Card Enrollment Hub (VCEH)

Request Body

Field Description

statusCode (Required) Action status codes. Additional values may be available in

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

l SUCCESS— Token is provisioned successfully.

l NOTIFICATION_FAILURE— Failed to send push provision notifi­
cation to the wallet provider.
l PROVISION_FAILURE— Failed to provision the token.

issuerTraceID (Optional) The field will help issuer to trace the VCEH session. The
value of this field is initially set by issuer in JWE with issuerTraceID.
Format: String; max length 32 characters.

encryptedData (Conditional) Blob field that contains the encrypted payload; see
"Cardholder Information" in the "Encrypted Payload Data Structures"
chapter for more information. Populated with the client info as
maintained by the wallet provider.
Format: String; max length 7000 characters.

Response

Successful Response
Successful API responses will return HTTP 200 status code with no response payload.

Error Response
The notification API is an asynchronous API and does not need the issuer to return anything to Visa.
The issuer returns the following error statuses as appropriate with no response payload in addition to
the Standard Errors.

HTTP Code HTTP Reason Code Description

400 Bad Request The request could not be understood by the server because of
malformed syntax. The client should not repeat the request until
modifications have been made.

401 Unauthorized Authentication credentials were missing or incorrect.

6 June 2023 Visa Confidential 237

Visa Token Service – Issuer API Specifications (JSON)
Visa Card Enrollment Hub (VCEH)

HTTP Code HTTP Reason Code Description

404 Not Found The server has not found anything matching the Request URI.

500 Internal Server Error An unspecified server error has occurred. Visa should attempt to
retry or contact issuer support.

Sample Payloads

Sample Request

{
“status”: “SUCCESS”,
“issuerTraceID”: “...”,
“encryptedData”: “<JWS>”
}

All JWS and JWE elements are URL encoded.

JWS:
<JWS Header>.<JWS Payload>.<JWS Signature>
JWS payload:
<JWE>
JWE:

<Header>.<Encrypted Key>.<Initialization Vector>.<Ciphertext>.

<Authentication Tag>

Decrypted data contained in JWE ciphertext element:

{
“source”: “ISSUER”
“firstName”: “ClientFristName”,
“middleName”: “ClientMiddleName”,
“lastName”: “ClientLastName”,
“phoneNumber”: “555-555-5555”,
“contactEmail”: “[email protected]”,
“locale”: “en_US”,
“clientDeviceID”: “...”,
“tokenReferenceID”: “...”
}

6 June 2023 Visa Confidential 238

Visa Token Service – Issuer API Specifications (JSON)
Visa Card Enrollment Hub (VCEH)

Sample Successful Response

HTTP 200 Success status with no payload.

6 June 2023 Visa Confidential 239

Chapter 8
Update Card Metadata Batch
Specifications

Introduction
This chapter gives specifications for the batch process allowing issuers to make bulk updates to their
card metadata. Contact your Visa representative for more information.
The batch process is a file-based solution that accepts a request file with multiple card metadata
records in JSON format. The corresponding response file contains the results of the operation.

Batch
The batch request file includes an array of Update Card Metadata requests. The file should be
constructed in such a way that each row in the array represents one request for the card metadata
update and should be in a single line with no white spaces.

6 June 2023 Visa Confidential 240

Visa Token Service – Issuer API Specifications (JSON)
Update Card Metadata Batch Specifications

File Naming Convention

The batch file name should contain the issuer client ID, the date, and the time. The issuer should use
the following format for naming a batch file:

^(UCM_REQ_[a-zA-Z-0-9]+_(\\d{4}-\\d{2}\\d{2}T\\d{2}.\\d{2}.\\d{2}).json)
$

The following is an example of a file name:

UCM_REQ_d1cd558e-30fa-cd1f-b354-126c7562650_2018-10-11T08.00.22.json

Batch Record Specification

The specification below outlines the JSON content of each record in the batch request file.

Batch Request
Field Description

updateCardMetadata (Required) This field identifies the beginning of the batch file request.
Format: An array; max size 50000.

Batch Record Request

Field Description

rowId (Required) Unique ID assigned for each request row in the batch file.
Maximum value can be 50000.
Format: String; max length 5 characters.

tokenRequestorID (Required) Unique ID assigned to the initiator of the token request.

Format: Numeric; max length 11 digits.

tokenReferenceID (Required) Unique ID for the token associated with the PAN. This ID can
be used in lieu of the token for subsequent calls, such as lifecycle
events.
Format: String; max length 32 characters.

operatorID (Optional) Operator ID of either the person or system performing the

operation.
Format: String; max length 16 characters.

6 June 2023 Visa Confidential 241

Visa Token Service – Issuer API Specifications (JSON)
Update Card Metadata Batch Specifications

Field Description

operationReason (Required) Populate the reason for card metadata change.

Format: String; max length 128 characters.

cardMetadataInfo (Required) Format: A Card Metadata Information structure.

Sample Batch File

Request
{
“updateCardMetadata”: [{
“rowId”: “1”,
“tokenRequestorID”: 400...00,
“tokenReferenceID”: “DNITHE 400...32”,
“operatorID”: “OPERATOR123”,
“operationReason”: “Updating Card Description”,
“cardMetadataInfo”: {
“cardIssuer”: “Bank1”,
“foregroundColor”: “rgb(112,533,123)”,
“backgroundColor”: “rgb(223,122,235)”,
“labelColor”: “rgb(255,122,235)”,
“shortDescription”: “4EJ...B4”,
“longDescription”: “n0h...oq”,
“cardArtData”: {
“cardArtRefID”: [
“aa4...ad”,“ga4...ad”,
“aaa...a2”,“2aa...aa”,
“2d6...df”]
},
“termsAndConditionsID”: “test”,
“privacyPolicyURL”: “https://privacyPolicyURLab.com/abc128”,
“termsAndConditionsURL”:
“https://termsAndConditionURL.com/abc128”,
“contactInfo”:{
“contactWebsite”: “www.bank1.com”,
“contactEmail”: “[email protected]”,
“contactNumber”: "987...21”,
“contactName”: “UCMTest”
},
“applicationInfo”: {
“supportsTokenNotifications”: true,
“supportsFPANNotifications”: true,
“transactionServiceURL”:
“https://vntsnotificationservice.visa.com/TxnHist/1”,
“messageServiceURL”: “https://messageserviceurlnfh.com”,
“transactionPushTopic”: “55q...0j”,
“messagePushTopic”: “https://messagepushtopic_udf...l6.com”,
“appLaunchURL”: “https://appLaunch.com/abc128”,
“appLaunchURLScheme”: “868...95”,
“associatedStoreIdentifiers”: [“123”,“456”],

6 June 2023 Visa Confidential 242

Visa Token Service – Issuer API Specifications (JSON)
Update Card Metadata Batch Specifications

“associatedApplicationIdentifiers”:
[“PROFILE_ID_103”,“PROFILE_ID_113”]
}
}
},
{
“rowId”:“2”,
“tokenRequestorID”: 400...01,
“tokenReferenceID": “DNI...33”,
“operatorID”: “OPERATOR123”,
“operationReason”: “Updating Card Description”,
“cardMetadataInfo”:{
“cardIssuer”: “Bank1”,
“foregroundColor”: “rgb(112,533,123)”,
“backgroundColor”: “rgb(223,122,235)”,
“labelColor”: “rgb(255,122,235)”,
“shortDescription”: “4EJ...B4”,
“longDescription”: “n0h...oq”,
“cardArtData”:{
“cardArtRefID”: [“aa4...ad”,“aaa...a1”,
“aaa...a2”,“2aa...aa”,“2d6...df”]
},
“termsAndConditionsID”: “test”,
“privacyPolicyURL”: “https://privacyPolicyURLab.com/abc128”,
“termsAndConditionsURL”:
“https://termsAndConditionURL.com/abc128”,
"contactInfo”:{
“contactWebsite”: “www.bank1.com”,
“contactEmail”: “[email protected]”,
“contactNumber”: “987...21”,
“contactName”: “UCMTest”
},
“applicationInfo”: {
“supportsTokenNotifications”: true,
“supportsFPANNotifications”: true,
“transactionServiceURL”:
“https://vntsnotificationservice.Visa.com/TxnHist/1”,
“messageServiceURL”: “https://messageserviceurlnfh.com”,
“transactionPushTopic”: “55q...0j”,
“messagePushTopic”:
“https://messagepushtopic_udf...l6.com”,
“appLaunchURL”: “https://appLaunch.com/abc128”,
“appLaunchURLScheme”: “868...95”,
“associatedStoreIdentifiers”: [“123",“456”],
“associatedApplicationIdentifiers”:
[“PROFILE_ID_103”,“PROFILE_ID_113”]
}
}
}
]
}

Success Response
{
“header”:{

6 June 2023 Visa Confidential 243

Visa Token Service – Issuer API Specifications (JSON)
Update Card Metadata Batch Specifications

“successCount”: 5,
“failureCount”: 0,
“correlationID”: “1_1...66m_BATCH-WEB”
},
“details”:[
{
“responseDetails”:[
{
“taskID”: “fc3...df”,
“tokenRequestorID”: 400...73,
“tokenReferenceID”: “DNI...21”,
“panReferenceID”: “V-3...04”,
“statusCode”: “PENDING”
}
],
“X-RESPONSE-ID”: “154...80_1”,
“rowId”: “1”
},
{
“responseDetails”:[
{
“taskID”: “ba9fc768-8e4...2a”,
“tokenRequestorID”: 400...73,
“tokenReferenceID”: “DNI...21”,
“panReferenceID”: “V-3...04”,
“statusCode”: “PENDING”
}
],
“X-RESPONSE-ID”: “154...09_2”,
“rowId”: “2”
},
{
“responseDetails”:[
{
“taskID”: “3cb...6e”,
“tokenRequestorID”: 400...73,
“tokenReferenceID”: “DNI...21”,
“panReferenceID”: “V-3...04”,
“statusCode”: “PENDING”
}
],
“X-RESPONSE-ID”: "154...39_3”,
“rowId”: “3”
},
{
“responseDetails”:[
{
“taskID”: “07b...55”,
“tokenRequestorID”: 400...73,
“tokenReferenceID”: “DNI...21”,
“panReferenceID”: “V-3...04”,
“statusCode”: “PENDING”
}
],
“X-RESPONSE-ID”: “154...68_4”,
“rowId": “4”
},
{

6 June 2023 Visa Confidential 244

Visa Token Service – Issuer API Specifications (JSON)
Update Card Metadata Batch Specifications

"responseDetails”:[
{
“taskID”: “786...e4”,
“tokenRequestorID”: 400...73,
“tokenReferenceID”: “DNI...21”,
“panReferenceID”: “V-38...04”,
“statusCode”: “PENDING”
}
],
“X-RESPONSE-ID”: “154...98_5”,
“rowId”: “5”
}
]
}

Failure Response
{
“header”:{
“successCount”: 2,
“failureCount”: 3,
“correlationID”: “1_15...6m_BATCH-WEB”
},
“details”:[
{
“responseDetails”:[
{
“taskID”: “fa3...37”,
“tokenRequestorID”: 400...73,
“tokenReferenceID”: “DNI...85”,
“panReferenceID”: “V-38...87”,
“statusCode”: “PENDING”
}
],
“X-RESPONSE-ID”: “154...05_1”,
“rowId”: “1”
},
{
“responseDetails”:[
{
“taskID”: “227...e0”,
“tokenRequestorID”: 400...73,
“tokenReferenceID”: “DNI...85”,
“panReferenceID”: “V-38...87”,
“statusCode”: “PENDING”
}
],
“X-RESPONSE-ID”: “154...34_2”,
“rowId”: “2”
},
{
“errorResponse”:{
“status”: 400,
“message”: “VSE_ERROR_INVALID_DATA”,
“reason”: “VSE40000”
},

6 June 2023 Visa Confidential 245

Visa Token Service – Issuer API Specifications (JSON)
Update Card Metadata Batch Specifications

“X-RESPONSE-ID”: “154...64_3”,
“rowId”: “3”
},
{
“errorResponse”:{
“status”: 400,
“message”: “VSE_ERROR_INVALID_DATA”,
“reason”: “VSE40000”
},
“X-RESPONSE-ID”: “154...94_4”,
“rowId”: “4”
},
{
“errorResponse”:{
“status”: 400,
“message”: “VSE_ERROR_INVALID_PROFILE_ID”,
“reason”: “VSE40004”
},
“X-RESPONSE-ID”: “154...22_5”,
“rowId”: “5”
}
]
}

6 June 2023 Visa Confidential 246

Chapter 9
Performance Targets

Expected API Response Times

The following table lists the expected response time for selected APIs.

API Name Expected Response Time From Issuer (In Seconds)

Approve Provisioning 1.5

Device Binding Request 1.5

Check Eligibility 2.5

Get Cardholder Verification Methods 2.5

Send Passcode 2.5

6 June 2023 Visa Confidential 247

Appendix A
Reject Codes

Reject Codes
RPIN Enrollment/Customer Contact Info Reject Code

Reject Code Description

A1 Invalid action.
Valid action codes are:

l Add
l Change
l Delete

A2 Last name missing.

A3 First name missing.

A7 Account number is invalid, does not begin with 4 or does not pass
check.

A8 Account number is not in an eligible account range for this issuer.

6 June 2023 Visa Confidential 248

Visa Token Service – Issuer API Specifications (JSON)
Reject Codes

Reject Code Description

B2 Name prefix is invalid.

B3 Name suffix is invalid.

B4 Address line 1 is missing on change to field.

B5 City is missing on change to field.

B6 State code is invalid.

B7 Statement ZIP code is invalid.

C1 Registered Program Identification Number (RPIN) is invalid.

C2 Product ID is invalid.

C3 Product ID does not match product ID of RPM account range.

C4 RPIN Product Category does not match Product Category of the VCIS
account range.

C7 Account product ID cannot be lower than product ID of VCIS account

range.

DE CMF input not allowed for this Registered Program Identification

Number (RPIN).

D2 Preferred method of contact is invalid.

D5 Account is not in a registered account range and has no program ID.

D6 Missing program ID.

D7 Account is not in a registered account range.

D9 Email address is missing.

G1 Product is not registered for account range.

G6 Mobile telephone number is missing.

G7 Mobile telephone number is invalid.

G8 Account opened date is invalid.

G9 Account opened date is missing.

H1 RPIN portfolio effective date is invalid.

IF Invalid field length.

6 June 2023 Visa Confidential 249

Visa Token Service – Issuer API Specifications (JSON)
Reject Codes

Replace Enrollment/Link Enrollment Reject Code

Reject Code Description

A1 Invalid action.
Valid action codes are:

l Add
l Change
l Delete

A7 Account number is invalid.

DE CMF input not allowed for this Registered Program Identification

Number (RPIN).

IF Invalid field length.

LA Deletion of the primary account from a link group is invalid.

LB Link group ID is invalid.

LC This account already exists in another link group.

LD Primary account indicator must be supplied.

LE Link group type is invalid.

LF Group type is not configured for this sender/sub-sender.

LZ Other account-linking–related error.

L1 Unlinking accounts that are not linked.

L2 Link reason code is invalid.

L3 Unlink indicator is invalid.

L4 Linked Card Number is specified but both Link Reason Code and
Unlink Indicator contain spaces.

L5 Linking already linked accounts.

L6 Cannot have values in both link reason code and unlink indicator. Only
one field may be used at a time.

L7 Linked card number is invalid.

L8 Linked card number is not in an eligible account range for this issuer.

N1 Linking account from a different country.

6 June 2023 Visa Confidential 250

Visa Token Service – Issuer API Specifications (JSON)
Reject Codes

Reject Code Description

N2 Invalid action code.

Valid action codes are:

l Add
l Change
l Delete

N3 Invalid group code. A variety of custom group types may be available.

Please refer to your Product Implementation Guide for information on
custom group types pertaining to your region.
Valid group code/types are:

l Replace
l LOC
l Customer
l VIP1
l ISEGMENT

N4 Invalid primary card indicator. Cardholder Maintenance File Issuer/

Processor Guide May 2019 Visa Confidential 63 Reject Reasons

N5 Account number exists with a different sender/sub-sender.

N6 Invalid change request.

N7 Invalid link; attempt to link account to more than one account.

N8 Primary card and replaced card are the same.

N9 Cyclic link; attempt to link replacement card with older card in

replacement chain.

NA Same card present in another spend assessed group

NB Duplicate change record.

NC Duplicate delete record.

ND Add and delete record for same account in the same file.

NE Invalid product ID

NF Invalid CMF product ID

NG Invalid issuer BID linking This reject reason code will be used when
there is an attempt to link accounts that are from different issuers.

NH Invalid cross product category link

NI Product Platform does not match Account Range Platform

6 June 2023 Visa Confidential 251

Visa Token Service – Issuer API Specifications (JSON)
Reject Codes

Reject Code Description

NJ Invalid ADD/CHANGE/DELETE of a Small Business Primary Card.

Valid action codes are:

l Add
l Change
l Delete

V1 The card exists as a virtual card

V2 The card cannot be treated as a virtual card Warning Reasons

WL Link is already present.

6 June 2023 Visa Confidential 252