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

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
  • Clients receives notification if consumer attempts to enroll to Click to Pay

Management of Consumer 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.
  • 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
  • Status
paymentInformation This object contains information about the payment instrument.
  • Card details

Available Endpoints

Endpoint Overview

Enroll Data

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

Enroll Payment Instruments

POST /v1/enrollPaymentInstruments
  • Enroll payment instrument to an existing consumer

Manage Consumer Information 

PUT /v1/manageConsumerInformation
  • Update consumer information

Manage Payment Instrument Data

PUT  /v1/managePaymentInstruments
  • Update payment instrument information

Get Data

POST /v1/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  /v1/deleteConsumerInformation
  • Delete consumer information 
  • The consumer's payment instruments will be deleted as well

Delete Payment Instrument Data

POST /v1/deletePaymentInstruments
  • Delete payment instrument information

Request Status by Request Trace ID

GET /v1/requestStatus/{requestTraceId}
  • Retrieve status of enrollment, consumer information management, payment instrument management, consumer information deletion, and payment instrument deletion requests submitted to Visa
Download Swagger (v1.3)

Last Updated on December 12, 2024

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.

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",
        "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.

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 enrollment 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).
  • 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",
                "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"
                }
            ]
        }
    ]
}

Delete Consumer Information API

  • Delete the data stored in each product (e.g., Click to Pay).
  • 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 enrollment 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",
        "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.

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": "consumerInformation.locale",
                    "reason": "VIDC-1000",
                    "message": "The consumerInformation.locale is missing"
                }
            ]
        }
    ]
}

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.

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:

  • 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, 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.

The status of the payment instrument is 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:

  • 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, 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
  status
  • Click to Pay will give an error when the following conditions are met:
    • value not supported
  • Supported values are:
    • ACTIVE - default value if status is not provided in the request
    • DISABLED - this value can be used by Issuers to temporarily disable a consumer from Click to Pay which could be possibly due to pending fraud investigation, the consumers exercising their rights to restriction, or other reasons the Issuer may have that warrants temporary restriction.

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.

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:

  • 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 Credential

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

Frequently Asked Questions

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 seperately through the common API?

  • The unified solution currently provides the capability to enroll onto a single product in a single API call. To enroll into Click to Pay, the intent field must include the Product Code “CLICK_TO_PAY”.

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 Assist including:
    • Visa Click to Pay - Issuer-offered Click to Pay as a Card Level Feature—Issuer Guide
    • Click to Pay Issuer Requirements

7. What happens to the payment Instruments in the consumer record when the status of the consumer is updated?

  • The status of the payment instruments are not affected when updating the the status at a consumer-level.

8. What happens after an Issuer (Issuer_A) disables a consumer (Consumer_1)?

  • When the consumer logs-in at checkout using the identity (email address) linked to Consumer_1's record, all cards issued by Issuer_A will not be returned.
  • When the consumer logs-in at destination site using the identity (email address) linked to Consumer_1's record, all cards issued by Issuer_A will not be shown.
  • When Issuer_A enrolls another card to Consumer_1, the enrollment is allowed.
  • When Issuer_A updates the payment instruments data (name on card / billing address) of Consumer_1's card, then the update is allowed.
  • When Issuer_A deletes Consumer_1, the deletion is allowed.
  • When Issuer_A deletes Consumer_1's card, the deletion is allowed.
  • When Issuer_A updates the consumer information of Consumer_1's record, then the update is allowed only if the status in the request is set to ACTIVE (or status is not provided in the request).  As this operation is an overwrite, Consumer_1's record will be updated with data provided in the request.  If the status in the request is set to DISABLED, then the update will not be performed and Click to Pay will give an 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.