Visa Click to Pay

Issuers

Start a Project Start a Project API Overview API Overview
Navigate to...
keyboard_arrow_down

How to Enroll and Manage Customer Data

Introduction

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 common API set.

This API set will also support enrollment and management of credentials for use with Alias Directory Service.

Benefits of a Common Solution

Click to Pay and Alias Directory are two distinct products that benefit digital payments for Issuers and the ecosystem in different ways. However, both products require similar data to be shared with Visa. Consequently, Visa has made it easier for Issuers to process the required data flows for both products by providing a common interface for enrollment and ongoing management of consumer and payment instrument data. This benefits Issuers for both the initial implementation and in the long term by making it easier to manage and update cardholder data in both services.

How It Works

Enrollment

  • Client submits enrollment data and indicates the product to enroll it to
  • Visa enrolls the data to the relevant product
  • Client retrieves the status of the request 

Management of Customer Information

  • Clients send a request to update / delete / retrieve data and indicates whether it applies to specific product or both
  • Visa updates / retrieves / deletes the data on the relevant product
  • Client retrieves the status of the request 

API Overview

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.
  • Alias Directory (ALIAS_DIRECTORY)
  • Click to Pay (CLICK_TO_PAY)
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.
  • Name
  • Phone Number
  • Email Address
paymentInformation This object contains information about the payment instrument.
  • Card details
  • Bank details

The swagger for the initial release is available below. When implementing this set of APIs, please note that additional parameters may be added in future versions. Please ensure that your implemention is robust enough to accommodate such future changes.

Download Swagger

Available Endpoints

Endpoint Overview

Enroll Data

POST /enrollData
  • Create consumer and payment instrument information
  • A consumer can be enrolled in a single product (e.g., Alias Directory or Click to Pay) with a single API call. Another API call will be required to enroll consumer in another product 

Enroll Payment Instruments

POST /enrollPaymentInstruments

 

  • Enroll payment instrument to an existing consumer

 

Manage Consumer Information 

PUT /manageConsumerInformation

 

  • Update consumer information

 

Manage Payment Instrument Data

PUT /managePaymentInstruments     

 

  • Update payment instrument information

 

Get Data

POST /getData
  • Retrieve consumer and payment instrument information 
  • Only data from a single product can be retrieved with a single API call

Delete Consumer Information

POST /deleteConsumerInformation
  • Delete consumer information 
  • The consumer's payment instruments will be deleted as well

Delete Payment Instrument Data

POST /deletePaymentInstruments
  • Delete payment instrument information

Request Status by Request Trace ID

GET /requestStatus/{requestTraceId}
  • Retrieve status of enrollment, consumer information management, payment instrument management, consumer information deletion, and payment instrument deletion requests submitted to Visa

Enroll Data

  • The Enroll Data API allows clients to submit data and specify the service for the data to be enrolled into. 
  • The consumerInformation.externalConsumerID is the unique resource for identifying the consumer and is provided by the issuer. 
  • Below is an example of a Click to Pay enrollment request body.
{
    "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.

Enroll Payment Instruments API

  • Enroll Payment Instruments API allows clients to enroll an additional payment instrument to an existing externalConsumerID.
  • The consumerInformation.externalConsumerID provided by the Issuer must exist in the product.  
  • Below is an example of a Click to Pay Enroll Payment Instruments request body.
{
    "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.

Manage Consumer Information API

  • Update the consumer information such as customer name, email, or phone number.
  • Clients are advised to perform a Get Data API call prior to making updates. 
  • Below is an example request body. 
{
    "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.

Manage Payment Instruments Data API

  • Update the payment information such Billing Address or Name on Card. The account number and expiration date will not be updated via this API. 
  • Clients are advised to perform a Get Data API call prior to making updates. 
  • Below is an example request body.
{
    "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.

Get Data API

  • Retrieve the data stored in each product (e.g., Click to Pay or Alias Directory Service).
  • Only data from a single product can be returned in a single API call. 
  • Clients are advised to perform a Get Data API call prior to making updates.
  • Below is an example request body.  
{
    "intent": {
        "type": "PRODUCT_CODE",
        "value": "CLICK_TO_PAY"
    },
    "consumerInformation": {
        "externalConsumerID": "63421837-d597-4f0f-89e4-930c1a7b9e85"
    }
}
  • This is a synchronous call and details will be provided in the API response. A successful response body will be a 200.
 
  • Below is an example of Click to Pay retrieve data response.
{
    "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"
                         }
                    }  
              ]
          }
     ]
}

Delete Consumer Information API

  • Delete the data stored in each product (e.g., Click to Pay or Alias Directory Service).
  • Data can be deleted from both products with a single API call.  The consumer's payment instruments will be deleted as well.
  • Below is an example request body. 
{
    "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.

Delete Payment Instruments Data API

  • Delete the payment instruments stored in Click to Pay for a given consumer. 
  • Data can be deleted from both products with a single API call. 
  • Below is an example request body. 
{
    "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.

Request Status by Request Trace ID API

  • Results of the Enroll Data, Enroll Payment Instrument, Manage Consumer Information, Manage Payment Instrument Data, Delete Consumer Information and Delete Payment Instrument requests will be available via this API. 
  • Clients can use the requestTraceID (which is generated and returned by Visa) to retrieve the details of the request.  The requestTraceID is valid for 7 days from the time of receipt.
  • The requestTraceId to be queried is added in the path parameter.
  • Below is an example of a request status response for an enrollment to Click to Pay.
{
    "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"
                    }
                ]
            }
       ]
}

Validations and Processing Logic

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.

  • required parameters are missing 
  • value provided is not supported
  • value provided did not meet the length restriction
  • number of elements provided in the array did not meet the number of elements restriction
  • entitlement checks failed
  • prior request is currently in-progress
  • the consumer already exist – for Enroll Data
  • the consumer does not exist – for Enroll Payment Instruments, Manage Consumer Information, Manage Payment Instruments Data, Get Data, Delete Consumer Information, and Delete Payment Instruments Data

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.

Enroll Data

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:

  • missing

 

externalConsumerID

Click to Pay will give an error when the following conditions are met:

  • missing
  • length restriction not met
  • already exist

 

firstName

Click to Pay will give an error when the following conditions are met:

  • missing
  • length restriction not met

 

middleName

Click to Pay will give an error when the following conditions are met:

  • length restriction not met

 

lastName

Click to Pay will give an error when the following conditions are met:

  • missing
  • length restriction not met

 

phones

Click to Pay will give an error when the following conditions are met:

  • missing
  • length restriction not 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:

  • missing
  • length restriction not 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:

  • missing
  • length restriction not met
  • value not supported

Note: This parameter is optional in the specification as it is not used in Alias Directory Service, but this is required for Click to Pay.

 

countryCode

Click to Pay will give an error when the following conditions are met:

  • missing
  • length restriction not met
  • value not supported

 

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:

  • missing
  • value not supported

  Supported values are:

  • PASSPORT
  • DRIVING_LICENSE
  • NATIONAL_IDENTITY

For nationalIdentifiers[ ].value

  Click to Pay will give an error when following conditions are met:

  • missing
  • length restriction not 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.

paymentInstruments

 

Click to Pay will give an error when the following conditions are met:

  • missing

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:

  • missing
  • value not supported

Click to Pay only supports type=CARD
 

 

accountNumber

Click to Pay will give an error when the following conditions are met:

  • missing
  • length restriction not met

 

nameOnCard

Click to Pay will give an error when the following conditions are met:

  • missing
  • length restriction not met

 

expirationDate

Click to Pay will give an error when the following conditions are met:

  • missing
  • length restriction not met
  • expirationexpiry date value is expired

 

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:

  • missing

Please refer to Table 3 for the billingAddress’ sub-fields.

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:

  • length restriction not met

 

addressLine2

Click to Pay will give an error when the following conditions are met:

  • length restriction not met

 

addressLine3

Click to Pay will give an error when the following conditions are met:

  • length restriction not met

 

city

Click to Pay will give an error when the following conditions are met:

  • length restriction not met

 

postalCode

Click to Pay will give an error when the following conditions are met:

  • length restriction not met

 

state

Click to Pay will give an error when the following conditions are met:

  • length restriction not met

 

country

Click to Pay will give an error when the following conditions are met:

  • missing
  • length restriction not met
  • value not supported

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.

Enroll Payment Instruments

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:

  • missing

 

externalConsumerID

Click to Pay will give an error when the following conditions are met:

  • missing
  • length restriction not met
  • does not exist

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:

  • missing

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:

  • missing
  • value not supported

Click to Pay only supports type=CARD

 

accountNumber

Click to Pay will give an error when the following conditions are met:

  • missing
  • length restriction not met
  • already exist

 

nameOnCard

Click to Pay will give an error when the following conditions are met:

  • missing
  • length restriction not met

 

expirationDate

Click to Pay will give an error when the following conditions are met:

  • missing
  • length restriction not met
  • expirationexpiry date value is expired

 

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:

  • missing

Please refer to Table 3 for the billingAddress’ sub-fields.

Table 5. Payment Instrument – Enroll Payment Instruments request.

Manage Consumer Information

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:

  • missing

 

externalConsumerID

Click to Pay will give an error when the following conditions are met:

  • missing
  • length restriction not met
  • does not exist

 

firstName

Click to Pay will give an error when the following conditions are met:

  • missing
  • length restriction not met

 

middleName

Click to Pay will give an error when the following conditions are met:

  • length restriction not met

 

lastName

Click to Pay will give an error when the following conditions are met:

  • missing
  • length restriction not met

 

phones

Click to Pay will give an error when the following conditions are met:

  • missing
  • length restriction not 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:

  • missing
  • length restriction not 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:

  • missing
  • length restriction not met
  • value not supported

Note: This parameter is optional in the specification as it is not used in Alias Directory Service, but this is required for Click to Pay.

 

countryCode

Click to Pay will give an error when the following conditions are met:

  • missing
  • length restriction not met
  • value not supported

 

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:

  • missing
  • value not supported

  Supported values are:

  • PASSPORT
  • DRIVING_LICENSE
  • NATIONAL_IDENTITY

For nationalIdentifiers[ ].value

Click to Pay will give an error when the following conditions are met:

  • missing
  • length restriction not met

Table 6. Consumer Information – Manage Consumer Information Data request

Manage Payment Instrument Data

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

  • If the accountNumber provided does not exist in the consumer record.
  • If the expirationDate provided is different from what is stored for the payment instrument that matches the accountNumber provided in the request.

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:

  • missing

 

externalConsumerID

Click to Pay will give an error when the following conditions are met:

  • missing
  • length restriction not met
  • does not exist

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:

  • missing

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:

  • missing
  • value not supported

Click to Pay only supports type=CARD

 

accountNumber

Click to Pay will give an error when the following conditions are met:

  • missing
  • length restriction not met
  • does not exist

 

nameOnCard

Click to Pay will give an error when the following conditions are met:

  • missing
  • length restriction not met

 

expirationDate

Click to Pay will give an error when the following conditions are met:

  • missing
  • length restriction not met
  • expiration date value is different from what is stored in the record.

 

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:

  • missing

Please refer to Table 3 for the billingAddress’ sub-fields.

Table 8. Payment Instrument – Manage Payment Instruments Data request

Delete Consumer Information

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:

  • missing

 

externalConsumerID

Click to Pay will give an error when the following conditions are met:

  • missing
  • length restriction not met
  • does not exist

Table 9. Consumer Information – Delete Consumer Information request

Delete Payment Instrument Data

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.

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:

  • missing

 

externalConsumerID

Click to Pay will give an error when the following conditions are met:

  • missing
  • length restriction not met
  • does not exist

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:

  • missing

 

type

Click to Pay will give an error when the following conditions are met:

  • missing
  • value not supported

Click to Pay only supports type=CARD

 

accountNumber

Click to Pay will give an error when the following conditions are met:

  • missing
  • length restriction not met
  • does not exist

Table 11. Payment Instrument – Delete Payment Instruments Data request

Get Data

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:

  • missing

 

externalConsumerID

Click to Pay will give an error when the following conditions are met:

  • missing
  • length restriction not met
  • does not exist

Table 12. Consumer Information – Get Data request

Errors

Visa ID and Credentials

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

Click to Pay

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

FAQs

1. What is externalConsumerID?

  • externalConsumerID is a consumer ID that is a unique identifier of the consumer from the Issuer’s perspective. This is distinct from any payment instrument identifier as multiple payment instruments may be associated to a single externalConsumerID.  It should be generated / provided by the Issuer. The ID provides the link between enrollment and data management functions to ensure that updates are applied to the correct consumer record.

2. Can I enroll into products separately through the common API?

  • The unified solution currently provides the capability to enrol onto a single product (either Click to Pay or Alias Directory) in a single API call. To enroll into Click to Pay, the intent field must include the Product Code “CLICK_TO_PAY”.  The Issuer can make a further API call to enroll into another product such as Alias Directory.

3. Do I need to check consumer provided data before sending it to Visa?

  • Issuers must only enroll or update consumer and payment instrument related data for their own customers which they know to be accurate. It is the Issuer's responsibility to perform relevant KYC checks on their customer and address data and to validate the consumer has access to all email addresses and phone numbers supplied over the API. The Issuer is solely responsible for ensuring the accuracy of all data provided to Visa, including the validity of the payment instrument(s), that the payment instrument(s) belongs to the enrolled consumer, and that the correct email/phone is matched with the payment instrument(s).

4. As an Issuer who is already integrated to Click to Pay via VCEH, do I need to migrate to this common API solution?

  • Issuers that have an existing VCEH integration for Click to Pay enrollment can continue to use VCEH for card enrollment. Please contact you Visa representative for further information on the use of VCEH for card enrollment in conjunction with this API for consumer data management.

5. Is billing address a required field for Click to Pay?

  • Issuers are required to provide the complete billing address when enrolling cards to Click to Pay.
  • In the API specification, the sub-fields of the billing address are defined as optional as they are not required by all products offered via the Visa ID & Credentials APIs.

6. Where can I find more information?

  • The content on this page is intended to support developers as they build integrations with Click to Pay.  There are extensive additional materials available for Visa clients on Visa Online including:
    • Visa Click to Pay - Issuer-offered Click to Pay as a Card Level Feature—Issuer Guide
    • Click to Pay Issuer Requirements

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.