To simplify the integration efforts for Issuers (or their VisaNet Processor, Visa Scheme Processor (Europe Region) or Third-Party Agent performing enrollment/lifecycle management on their behalf), a common set of Visa APIs has been developed to allow Issuers to enroll payment instruments to Click to Pay and in the future other Visa products. Issuers can now enroll and manage customer and payment instrument(s) information for Click to Pay using this API set.
The APIs allow clients to modify the following categories of data.
Category | Description | Examples |
---|---|---|
intent |
This specifies the service which the data needs to be enrolled in. |
|
consumerInformation | This object contains information about the consumer. Issuers are required to provide an externalConsumerID to represent each consumer. Issuers are required to provide the BID of the Payment Card Issuer who has the relationship with the consumer (maintains the consumer profile) in the externalConsumerIDOwnerBID. The externalConsumerID together with the externalConsumerIDOwnerBID, uniquely identifies a consumer in the VICA and Click to Pay systems. All data provided will be linked to the combination of these two identifiers. |
|
paymentInformation | This object contains information about the payment instrument. |
|
Endpoint | Overview |
---|---|
Enroll Data POST /v1/enrollData |
|
Enroll Payment Instruments POST /v1/enrollPaymentInstruments |
|
Manage Consumer Information PUT /v1/manageConsumerInformation |
|
Manage Payment Instrument Data PUT /v1/managePaymentInstruments |
|
Get Data POST /v1/getData |
|
Delete Consumer Information POST /v1/deleteConsumerInformation |
|
Delete Payment Instrument Data POST /v1/deletePaymentInstruments |
|
Request Status by Request Trace ID GET /v1/requestStatus/{requestTraceId} |
|
Last Updated on April 1, 2025
{
"intent": {
"type": "PRODUCT_CODE",
"value": "CLICK_TO_PAY"
},
"consumerInformation": {
"externalConsumerID": "63421837-d597-4f0f-89e4-930c1a7b9e85",
"externalConsumerIDOwnerBID": "10098765",
"firstName": "Alex",
"middleName": "Noa",
"lastName": "Miller",
"phones": [
"16504005555"
],
"emails": [
"alexmiller@mail.com"
],
"locale": "en_US",
"countryCode": "USA"
},
"paymentInstruments": [
{
"type": "CARD",
"accountNumber": "4111111145551140",
"nameOnCard": "Alex Miller",
"expirationDate": "2030-01",
"billingAddress": {
"addressLine1": "1000 Market Street",
"addressLine2": "Building 56",
"addressLine3": "Suite 101",
"city": "San Francisco",
"postalCode": "94105",
"state": "CA",
"country": "USA"
}
}
]
}
A successful response body will be a 202. The outcome of enrollment can be retrieved via the Request Status by Request Trace ID API using the requestTraceId provided in the response.
{
"intent": {
"type": "PRODUCT_CODE",
"value": "CLICK_TO_PAY"
},
"consumerInformation": {
"externalConsumerID": "63421837-d597-4f0f-89e4-930c1a7b9e85",
"externalConsumerIDOwnerBID": "10098765"
},
"paymentInstruments": [
{
"type": "CARD",
"accountNumber": "4111111145551141",
"nameOnCard": "Alex Miller",
"expirationDate": "2030-12",
"billingAddress": {
"addressLine1": "1000 Market Street",
"addressLine2": "Building 56",
"addressLine3": "Suite 101",
"city": "San Francisco",
"postalCode": "94105",
"state": "CA",
"country": "USA"
}
}
]
}
A successful response body will be a 202. The outcome of enrollment can be retrieved via the Request Status by Request Trace ID API using the requestTraceId provided in the response.
{
"intent": {
"type": "PRODUCT_CODE",
"value": "CLICK_TO_PAY"
},
"consumerInformation": {
"externalConsumerID": "63421837-d597-4f0f-89e4-930c1a7b9e85",
"externalConsumerIDOwnerBID": "10098765",
"firstName": "Alex",
"middleName": "Noa",
"lastName": "Miller",
"phones": [
"16504005555"
],
"emails": [
"alexandermiller@mail.com"
],
"locale": "en_US",
"countryCode": "USA",
"status": "ACTIVE"
}
}
A successful response body will be a 202. The outcome of enrollment can be retrieved via the Request Status by Request Trace ID API using the requestTraceId provided in the response.
{
"intent": {
"type": "PRODUCT_CODE",
"value": "CLICK_TO_PAY"
},
"consumerInformation": {
"externalConsumerID": "63421837-d597-4f0f-89e4-930c1a7b9e85",
"externalConsumerIDOwnerBID": "10098765"
},
"paymentInstruments": [
{
"type": "CARD",
"accountNumber": "4111111145551140",
"nameOnCard": "Alex Miller",
"expirationDate": "2030-01",
"billingAddress": {
"addressLine1": "98 Montgomery Street",
"addressLine2": "Suite 24",
"city": "San Francisco",
"postalCode": "94104",
"state": "CA",
"country": "USA"
}
}
]
}
A successful response body will be a 202. The outcome of enrollment can be retrieved via the Request Status by Request Trace ID API using the requestTraceId provided in the response.
{
"intent": {
"type": "PRODUCT_CODE",
"value": "CLICK_TO_PAY"
},
"consumerInformation": {
"externalConsumerID": "63421837-d597-4f0f-89e4-930c1a7b9e85",
"externalConsumerIDOwnerBID": "10098765"
}
}
{
"data": [
{
"intent": {
"type": "PRODUCT_CODE",
"value": "CLICK_TO_PAY"
},
"consumerInformation": {
"externalConsumerID": "63421837-d597-4f0f-89e4-930c1a7b9e85",
"externalConsumerIDOwnerBID": "10098765",
"firstName": "Alex",
"middleName": "Noa",
"lastName": "Miller",
"phones": [
"16504323200"
],
"emails": [
"alexandermiller@mail.com"
],
"locale": "en_US",
"countryCode": "USA",
"status": "ACTIVE"
},
"paymentInstruments": [
{
"type": "CARD",
"accountNumber": "4111111145551140",
"nameOnCard": "Alex Miller",
"expirationDate": "2030-01",
"tokenDetails": {
"tokenReferenceID": "DNI...99",
"tokenRequestorID": "400...51"
},
"paymentAccountReference": "V00...47",
"billingAddress": {
"addressLine1": "98 Montgomery Street",
"addressLine2": "Building 109",
"addressLine3": "Suite 26",
"city": "San Francisco",
"postalCode": "94104",
"state": "CA",
"country": "USA"
},
"status": "ACTIVE"
},
{
"type": "CARD",
"accountNumber": "4111111145551141",
"nameOnCard": "Alex Miller",
"expirationDate": "2030-12",
"tokenDetails": {
"tokenReferenceID": "DNI...99",
"tokenRequestorID": "400...51"
},
"paymentAccountReference": "V00...48",
"billingAddress": {
"addressLine1": "1000 Market Streets",
"addressLine2": "Building 56",
"addressLine3": "Suite 101",
"city": "San Francisco",
"postalCode": "94105",
"state": "CA",
"country": "USA"
},
"status": "ACTIVE"
}
]
}
]
}
{
"intent": {
"type": "PRODUCT_CODE",
"value": "CLICK_TO_PAY"
},
"consumerInformation": {
"externalConsumerID": "63421837-d597-4f0f-89e4-930c1a7b9e85",
"externalConsumerIDOwnerBID": "10098765"
}
}
A successful response body will be a 202. The outcome of enrollment can be retrieved via the Request Status by Request Trace ID API using the requestTraceId provided in the response.
{
"intent": {
"type": "PRODUCT_CODE",
"value": "CLICK_TO_PAY"
},
"consumerInformation": {
"externalConsumerID": "63421837-d597-4f0f-89e4-930c1a7b9e85",
"externalConsumerIDOwnerBID": "10098765"
},
"paymentInstruments": {
"type": "CARD",
"accountNumber": "4111111145551141"
}
}
A successful response body will be a 202. The outcome of enrollment can be retrieved via the Request Status by Request Trace ID API using the requestTraceId provided in the response.
{
"status": "COMPLETED",
"consumerInformation": {
"externalConsumerID": "63421837-d597-4f0f-89e4-930c1a7b9e85",
"externalConsumerIDOwnerBID": "10098765"
},
"details": [
{
"intent": {
"type": "PRODUCT_CODE",
"value": "CLICK_TO_PAY"
},
"status": "FAILED",
"errorDetails": [
{
"field": "consumerInformation.locale",
"reason": "VIDC-1000",
"message": "The consumerInformation.locale is missing"
}
]
}
]
}
This section describes some rules that Click to Pay applies when processing the request it receives via Visa ID and Credentials platform. Note: This section provides an overview of the validations and processing logic applied when an API request is received, it does not replace the API specification.
Visa ID and Credentials APIs perform initial checks on the parameters and follow some rules before securely passing the request to products like Click to Pay. It will return an error if the following conditions occur.
Once the initial checks have been performed by Visa ID and Credentials APIs, request is passed to Click to Pay and further validations and processing logic is applied as detailed below.
Click to Pay applies the following rules when processing Enroll Data request that was forwarded by Visa ID and Credential API.
Issuers can use this API to enroll a consumer and payment instrument to Click to Pay. As part of the request processing, a token will be generated for the enrolled payment instrument.
The status of the consumer and the payment instrument are set to ACTIVE after a successful enrollment.
For consumer information data, Click to Pay will throw an error when the following conditions are met.
consumerInformation |
|
Click to Pay will give an error when the following conditions are met: |
|
externalConsumerID |
Click to Pay will give an error when the following conditions are met:
|
externalConsumerIDOwnerBID | Click to Pay will give an error when the following conditions are met:
|
|
|
firstName |
Click to Pay will give an error when the following conditions are met:
|
|
middleName |
Click to Pay will give an error when the following conditions are met:
|
|
lastName |
Click to Pay will give an error when the following conditions are met:
|
|
phones |
Click to Pay will give an error when the following conditions are met:
Note: For initial release, only one phone number will be supported. If more than one phone number is provided, the first element in the array will be used. Issuers are advised to send only one phone number in the request. |
|
emails |
Click to Pay will give an error when the following conditions are met:
Note: For initial release, only one email address will be supported. If more than one email address is provided, the first element in the array will be used. Issuers are advised to send only one email address in the request. |
|
locale |
Click to Pay will give an error when the following conditions are met:
Note: This parameter is optional in the specification, but this is required for Click to Pay. |
|
countryCode |
Click to Pay will give an error when the following conditions are met:
|
|
consent |
Note: Click to Pay does not use this currently. Click to Pay will ignore this parameter if provided in the request. |
|
nationalIdentifiers |
Note: Only one national identifier will be supported. If more than one national identifier is provided, the first element in the array will be used. Issuers are advised to send only one national identifier in the request. This parameter is optional. For nationalIdentifiers[ ].type Click to Pay will give an error when following conditions are met:
Supported values are:
For nationalIdentifiers[ ].value Click to Pay will give an error when following conditions are met:
|
Table 1. Consumer Information – Enroll Data request
For payment instruments data, Click to Pay will throw an error when the following conditions are met.
Table 2. Payment Instrument – Enroll Data request
For billing address data, Click to Pay will throw an error when the following conditions are met.
billingAddress |
|
|
|
addressLine1 |
Click to Pay will give an error when the following conditions are met:
|
|
addressLine2 |
Click to Pay will give an error when the following conditions are met:
|
|
addressLine3 |
Click to Pay will give an error when the following conditions are met:
|
|
city |
Click to Pay will give an error when the following conditions are met:
|
|
postalCode |
Click to Pay will give an error when the following conditions are met:
|
|
state |
Click to Pay will give an error when the following conditions are met:
|
|
country |
Click to Pay will give an error when the following conditions are met:
|
Table 3. Billing Address
Issuers must send the complete billing address when enrolling in Click to Pay, even though most of the sub-fields are not required.
The errors below will be returned in the API’s response.
HTTP Code |
Reason Code |
Error Description |
---|---|---|
400 |
VIDC-1000 |
Require field missing |
400 |
VIDC-1001 |
Invalid value / Request ID not found |
400 |
VIDC-1002 |
Length checks failed |
400 |
VIDC-1003 |
Array length failed |
400 |
VIDC-2000 |
Consumer is already enrolled - Enroll Data |
400 |
VIDC-2001 |
Consumer is not enrolled - Enroll Payment Instruments, Manage Consumer Information, Manage Payment Instruments Data, Get Data, Delete Consumer Information, and Delete Payment Instruments Data |
400 |
VIDC-2002 |
Entitlement checks failed - Enroll Data, Enroll Payment Instruments |
409 |
VIDC-3000 |
Concurrent checks failed - Enroll Payment Instruments, Manage Consumer Information, Manage Payment Instruments Data, Get Data, Delete Consumer Information, and Delete Payment Instruments Data For example, when an Issuer sends Enroll Data request for consumer_1 and then sends Enroll Payment Instruments for the same consumer_1. If the Enroll Data request is not yet completed, then the Enroll Payment Instruments request will get a concurrency error response. |
500 |
VIDC-5000 |
Internal Service Error |
Disclaimer: This page is provided on an “as is, where is” basis, “with all faults” known and unknown. This page 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 document. VISA may make improvements and/or changes in the product(s) and/or the program(s) described in this document at any time. Where potential future functionality is highlighted, visa does not provide any warranty on whether such functionality will be available or if it will be delivered in any particular time. To the maximum extent permitted by applicable law, visa explicitly disclaims all warranties, express or implied, regarding the information contained herein, including any implied warranty of merchantability, fitness for a particular purpose, and non-infringement.
If you have technical questions or questions regarding a Visa service or questions about this document, please contact your Visa representative.