Visa ID and Credential

Lifecycle Management Tool for Click to Pay

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

How to Use Visa ID and Credential

The following is a list of services and use cases supported by Visa ID & Credential API. 

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

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

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.

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.