To simplify the integration efforts for Issuers, 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. All data provided will be linked to this identifier. |
|
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} |
|
{
"intent": {
"type": "PRODUCT_CODE",
"value": "CLICK_TO_PAY"
},
"consumerInformation": {
"externalConsumerID": "63421837-d597-4f0f-89e4-930c1a7b9e85",
"firstName": "Alex",
"middleName": "Noa",
"lastName": "Miller",
"phones": [
"16504005555"
],
"emails": [
"[email protected]"
],
"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"
},
"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",
"firstName": "Alex",
"middleName": "Noa",
"lastName": "Miller",
"phones": [
"16504005555"
],
"emails": [
"[email protected]"
],
"locale": "en_US",
"countryCode": "USA"
}
}
A successful response body will be a 202. The outcome of the update 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"
},
"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 the update 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"
}
}
{
"data": [
{
"intent": {
"type": "PRODUCT_CODE",
"value": "CLICK_TO_PAY"
},
"consumerInformation": {
"externalConsumerID": "63421837-d597-4f0f-89e4-930c1a7b9e85",
"firstName": "Alex",
"middleName": "Noa",
"lastName": "Miller",
"phones": [
"16504323200"
],
"emails": [
"[email protected]"
],
"locale": "en_US",
"countryCode": "USA"
},
"paymentInstruments": [
{
"type": "CARD",
"accountNumber": "4111111145551140",
"nameOnCard": "Alex Miller",
"expirationDate": "2030-01",
"billingAddress": {
"addressLine1": "98 Montgomery Street",
"addressLine2": "Building 109",
"addressLine3": "Suite 26",
"city": "San Francisco",
"postalCode": "94104",
"state": "CA",
"country": "USA"
},
{
"type": "CARD",
"accountNumber": "4111111145551141",
"nameOnCard": "Alex Miller",
"expirationDate": "2030-12",
"billingAddress": {
"addressLine1": "1000 Market Streets",
"addressLine2": "Building 56",
"addressLine3": "Suite 101",
"city": "San Francisco",
"postalCode": "94105",
"state": "CA",
"country": "USA"
}
}
]
}
]
}
{
"intent": {
"type": "PRODUCT_CODE",
"value": "CLICK_TO_PAY"
},
"consumerInformation": {
"externalConsumerID": "63421837-d597-4f0f-89e4-930c1a7b9e85"
}
}
A successful response body will be a 202. The outcome of the update 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"
},
"paymentInstruments": {
"type": "CARD",
"accountNumber": "4111111145551141"
}
}
A successful response body will be a 202. The outcome of the update 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"
},
"details": [
{
"intent": {
"type": "PRODUCT_CODE",
"value": "CLICK_TO_PAY"
},
"status": "FAILED",
"errorDetails": [
{
"field": "paymentInstruments[0].type",
"reason": "VIDC-1001"
}
]
}
]
}
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.
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:
|
|
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.
Click to Pay applies the following rules when processing Enroll Payment Instruments request that was forwarded by Visa ID and Credential API.
Issuers can use this API to enroll a payment instrument to Click to Pay for an existing consumer. As part of the request processing, a token will be generated for the enrolled payment instrument.
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:
|
Table 4. Consumer Information – Enroll Payment Instruments request
For payment instrument data, Click to Pay will throw an error when the following conditions are met.
paymentInstruments |
|
Click to Pay will give an error when the following conditions are met:
Note: For initial release, only one payment instrument will be supported. If more than one payment instruments are provided, Visa ID and Credential platform will respond with error – the request will not be forwarded to Click to Pay. Issuers are advised to send only one payment instrument in the request. |
|
type |
Click to Pay will give an error when the following conditions are met:
Click to Pay only supports type=CARD |
|
accountNumber |
Click to Pay will give an error when the following conditions are met:
|
|
nameOnCard |
Click to Pay will give an error when the following conditions are met:
|
|
expirationDate |
Click to Pay will give an error when the following conditions are met:
|
|
issuerName |
Note: Click to Pay does not use this currently. Click to Pay will ignore this parameter if provided in the request. This parameter is optional. |
|
cardType |
Note: Click to Pay does not use this currently. Click to Pay will ignore this parameter if provided in the request. This parameter is optional. |
|
billingAddress |
Click to Pay will give an error when the following conditions are met:
Please refer to Table 3 for the billingAddress’ sub-fields. |
Table 5. Payment Instrument – Enroll Payment Instruments request.
Click to Pay applies the following rules when processing Manage Consumer Information request that was forwarded by Visa ID and Credential API.
This operation will completely overwrite existing data for that consumer. It is recommended for Issuers to invoke Get Data API before Manage Consumer Information API to know the latest state of the consumer information in Click to Pay and ensure other data fields are not updated unintentionally.
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:
|
|
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 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 the following conditions are met:
|
Table 6. Consumer Information – Manage Consumer Information Data request
Click to Pay applies the following rules when processing Manage Payment Instruments Data request that was forwarded by Visa ID and Credential API.
This API will only update existing payment instrument data. It will not delete any payment instruments from the consumer record. If the accountNumber provided matches a payment instrument from the consumer record, then the updates will only be applied to that payment instrument.
For maintaining the latest state of the consumer’s payment instrument information in Click to Pay without unintentional updates to other data fields, Issuers should invoke the Get Data API prior to the Manage Payment Instruments Data API and populate all data fields correctly.
The following data fields will not be updated via this API even if a different value is provided in the request – accountNumber and expirationDate. Click to Pay will throw an error
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:
|
Table 7. Consumer Information – Manage Payment Instruments Data request
For payment instrument data, Click to Pay will throw an error when the following conditions are met.
paymentInstruments |
|
Click to Pay will give an error when the following conditions are met:
Note: For initial release, only one payment instrument will be supported. If more than one payment instruments are provided, Visa ID and Credential platform will respond with error – the request will not be forwarded to Click to Pay. Issuers are advised to send only one payment instrument in the request. |
|
type |
Click to Pay will give an error when the following conditions are met:
Click to Pay only supports type=CARD |
|
accountNumber |
Click to Pay will give an error when the following conditions are met:
|
|
nameOnCard |
Click to Pay will give an error when the following conditions are met:
|
|
expirationDate |
Click to Pay will give an error when the following conditions are met:
|
|
issuerName |
Note: Click to Pay does not use this currently. Click to Pay will ignore this parameter if provided in the request. This parameter is optional. |
|
cardType |
Note: Click to Pay does not use this currently. Click to Pay will ignore this parameter if provided in the request. This parameter is optional. |
|
billingAddress |
Click to Pay will give an error when the following conditions are met:
Please refer to Table 3 for the billingAddress’ sub-fields. |
Table 8. Payment Instrument – Manage Payment Instruments Data request
Click to Pay applies the following rules when processing Delete Consumer Information request that was forwarded by Visa ID and Credential API.
Issuers can use this API to delete all data that it previously sent to Click to Pay for that consumer including all payment instruments (incl. tokens) that are linked to the consumer record. This will not affect the data that was sent to Click to Pay by another Issuer for the same consumer.
Note: There is no re-activate option for the deleted consumer. To re-enroll the consumer, Issuers can use the same/different externalConsumerID as per the Issuer implementation for as long as the externalConsumerID being sent to Click to Pay is persisted against that consumer in the Issuer’s database. Please use Enroll Data API to re-enroll the consumer/payment instruments in Click to Pay.
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:
|
Table 9. Consumer Information – Delete Consumer Information request
Click to Pay applies the following rules when processing Delete Payment Instruments Data request that was forwarded by Visa ID and Credential API.
Issuers can use this API to delete one payment instrument (incl. token) from a consumer record in Click to Pay. Click to Pay will throw an error if the accountNumber provided does not exist in the consumer record.
Note: Deleting the last payment instrument from a consumer record does not automatically delete the consumer record itself. Issuers must use the Delete Consumer Information API to delete the consumer record from Click to Pay.
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:
|
Table 10. Consumer Information – Delete Payment Instruments Data request
For payment instrument data, Click to Pay will throw an error when the following conditions are met.
paymentInstruments |
|
Click to Pay will give an error when the following conditions are met:
|
|
type |
Click to Pay will give an error when the following conditions are met:
Click to Pay only supports type=CARD |
|
accountNumber |
Click to Pay will give an error when the following conditions are met:
|
Table 11. Payment Instrument – Delete Payment Instruments Data request
Click to Pay applies the following rules when processing Get Data request that was forwarded by Visa ID and Credential API.
Issuers can use this API to retrieve all information about the consumer stored in Click to Pay. Click to Pay will throw an error if the consumer does not exist in Click to Pay.
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:
|
Table 12. Consumer Information – Get Data request
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 |
The errors below will be returned in the Request Status by Request Trace ID API response.
Reason Code |
Error Description |
---|---|
VIDC-1000 |
Required field missingTBC |
VIDC-1001 |
Invalid value / Request ID not found |
VIDC-1002 |
Length checks failed |
VIDC-1003 |
Array length failed |
VIDC-2000 |
Consumer is already enrolled – Enroll Data |
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 |
VIDC-2002 |
Payment instrument is not issued by the Issuer that sends the request - Enroll Data, Enroll Payment Instruments, Manage Payment Instruments Data, and Delete Payment Instruments Data For example: Issuer A sends a request with card_1, and card_1 is issued by Issuer B. |
VIDC-2003 |
Payment instrument is expired |
VIDC-2004 |
Payment instrument already exist |
VIDC-2005 |
Payment instrument is not enrolled |
VIDC-2006 |
Payment instrument is not a Visa card |
VIDC-2007 |
Payment instrument’s issuer is not configured for Issuer Offered Click to Pay |
VIDC-2008 |
This information cannot be updated. This currently applies to expirationDate. |
VIDC-7000 |
Payment instrument's tokenization declined / PAN is not eligible for tokenisation |
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.