Visa Pay

Visa Pay API Endpoints

Available for use by:
Independent developers

Enrollment Endpoints

Visa Pay enrollment endpoints allow clients to enroll a digital wallet or A2A Scheme account for Visa Pay services by generating a Visa format token.

Enrollment Endpoints Overview

Pre-Requisites: Clients must have completed all VisaNet setup (BIN Config, etc.) and completed Visa Pay Program Setup (refer to Getting Started) which will result in a Program_ID.

API Category Description: Visa Pay enrollment endpoints allow clients to enroll a digital wallet or A2A Scheme account for Visa Pay services by generating a Visa format token. The API provides these functionalities:

Functionality Endpoint Description

Request Initial Enrollment

POST

/enroll

Initiates the enrollment in an asynchronous process to support batch enrollments and to avoid timeouts within the same request. Multiple token types can be requested on the same request. This POST request to enroll will only return a success / failure confirmation, but the token details that were issued must be retrieved through a subsequent GET enrollment call.

Retrieve Enrollment and Tokens

GET

/enrollments/{Account ID}

Initiates a request to retrieve: all tokens provisioned for the wallet account, current account status, enrollment timestamps. This endpoint will only be successful if a POST /enroll has been submitted to this account. Required fields to request GET for this endpoint: Account_ID and Program_ID.

Request Additional Token

POST

/enrollments/ {Account ID}/ token

Requests an additional token provisioning for a previously enrolled account. This call is only possible if request is done for a token_type that is not already provisioned for the enrolled account (i.e. requesting an ecomm_token for account that only has device token). Additional token call will require using the GET Enrollment to retrieve the full details of the newly provisioned token.

Search

Enrollments

POST

/enrollments/search

This endpoint allows searching enrollments by email address, phone number, document number, or wallet account ID. Results are paginated and include complete enrollment details including status, associated tokens, and account information. Search results support cursor-based pagination using page tokens for efficient navigation through large result sets. The search is case- insensitive and returns partial matches where applicable.

Recommendations to use Visa Pay Enrollment Endpoints: Clients are recommended to adhere to the following best practices to ensure a smooth Visa Pay implementation.

  • Activate Entire User Base (via Batch call): Perform batch enrollment using an asynchronous process for all account holders in order for Visa Pay solutions to be effective. Visa Pay supports batch enrollment, to be called sequentially by clients.
  • Activate New Users (via individual calls): Clients are encouraged to include Visa Pay enrollment flows into standard account issuance workflows.
  • Recommended to request all necessary token types in a single API call: Combining enrollments into a single call minimizes multiple retrieval calls.

Request Initial Enrollment [POST]

Endpoint Description: This endpoint initiates the Visa Pay card and token generation process and return the enrollment ID field that will be used to identify the client end user's enrollment within Visa Pay. The enrollment ID is mapped one-to-one to the client's end user identifier (one enrollment ID per user, regardless of number of Visa Pay enrollment calls). The enroll endpoint is the core of the Visa Pay API, from which all other features are enabled. Within the enroll endpoint the Visa Pay API performs the following functions, (i) user Account creation, (ii) client credentialization (associated with the Program_ID) without need for client PCI DSS compliance and (iii) Token provisioning.

Endpoint Details:

  • API URL: https://api.bra01-pci.sandbox.visapay.visa.com/pay-by-wallet/v1/enroll
  • Command: POST
  • Requestor: Wallet Client
  • Receiver: Visa Pay

Required Parameters

Parameters Type Format Description
Content-Type Header String (header) Content type of the request/response Default value: application/json

Overview of Required API Input Fields: The enroll endpoint requires three key inputs (details in table)

  • Program_ID: A necessary pre-requisite identifier that is configured through the Visa Pay control center and identifies which Visa BIN is being used for the tokens. In most cases, clients will only have one Program_ID (since there is one BIN), but in select cases, clients may also have multiple Program_IDs to support multiple BINs for Visa Pay.
  • Wallet / User Data: Generating Visa Pay tokens requires a combination of mandatory and optional user specific fields (such as Device_ID).
  • Token Type: Clients can request multiple types of tokens; currently Visa Pay supports two token types (more will be added over time). Clients can request one ecommerce token and one device token per device currently.
  • Ecommerce tokens: May be used for e-commerce transactions as well as
  • Device Tokens: Used for Tap to Pay transactions has more mandatory fields than eCommerce tokens
  • Scan Token (coming soon): An ecomm token type that is specifically used for Scan To Pay transactions (requires device binding)
  • Blank: If the token type is left blank, no token is generated but an enrollment identifier (ID) is still generated; this can be used to retrieve other Visa and Pismo numerics through separate API endpoints.

Request Body Fields Deep Dive: The table below shows all the details of the API input fields.

Request Body Fields Type Format Description
Program_id Mandatory Integer Visa Pay Program ID, provided by onboarding process on control center
Wallet_data Mandatory Object of type WalletData Wallet related uer information
tokens Optional Array of object type TokenRequestObj

Overview of API Output Fields:

Enrollment Identifier (ID): If the enrollment is successful, the endpoint returns a single value which is the ID.

Input Field Type Format Description
Program_id Mandatory Integer Visa Pay Program ID, provided by onboarding process on control center
Account_id Mandatory String < characters Wallet Account ID, provided by client
Wallet Data Object (contains) Customer_id   String < 100 characters Pismo Card ID, provided by enrollment feature
(contains) e-mail_id Optional String Network brand of the card, provided by ISO 8583 message
(contains) Phone_number Optional String < 15 characters Transaction type code based on ISO 8583
(contains) Country_code Optional String < 5 characters Phone number country code
(contains) Full_name Optional String < 60 characters Transaction settlement amount in local currency, provided by ISO 8583 message.
(contains) User_name Optional String < 64 characters Transaction currency code based on ISO 4217 numeric code, provided by ISO 8583 message
(contains) Document_number Optional String Transaction settlement currency code based on ISO 4217 numeric code
Token Type Object (contains) Type* Mandatory String Type of token being requested to provision (DEVICE or ECOMMERCE_COF)
(contains) Client_app_id* Mandatory(Device) String Client App ID example: "05043cb8-a07c-4cdc-b986-ceda85182d3"
(contains) Os_type   String OS Type (iOS)
(contains) Locale*   String Region (Americas/Sao_Paulo)
(contains) Device_id   String Device ID (ex: 12345)
(contains) Device_type   String Device type (PHONE)
(contains) Device_name Optional String Device name (John's iPhone)
(contains) Client_wallet_account_ email_address_hash* Optional String Wallet account email address hash
(contains) Platform_type* Optional String Platform type (ANDROID)

*Indicates fields that are required for both token types (Ecommerce and Device Tokens)

Sample Response Schema

Retrieve Generated Account & Tokens [GET]

Endpoint Description: This endpoint retrieves the enrollment information from a previously enrolled user Account_ID. Call will return all previously submitted account and program details during the enrollment request, as well as newly issued numerics / details such as Token Item Object, if requested, and card reference id. The Token ID is the source of payments from enrolled account to Visa Pay, for which an account will be issued per token type requested.

Endpoint Details:

  • API URL: https://api.bra01-pci.sandbox.visapay.visa.com/pay-by-wallet/v1/enrollments/:walletAccountId?programId=:programId
  • Endpoint: v1/enrollments/{external-id}
  • Command: GET
  • Direction: Wallet Client
  • Receiver: Visa Pay

Overview of Required Input Parameters: The GET enrollments endpoint has the following required input parameters (no additional required fields):

  • Program_ID: A necessary pre-requisite identifier that is configured through the Visa Pay control center and identifies which Visa BIN is being used for the tokens.
  • Account_ID: This is the client-side external account identifier that has been used to perform the initial enrollment request.

Some best practices when using GET enrollment endpoint to retrieve the account, enrollment and token details from a previously enrolled account.

  • Check Enrollment Status: Due to the asynchronous nature of the enrollment process, that consists of multiple operations within the enroll endpoint and potentially large volumes of simultaneous batch enrollments, a complete enrollment may take 1-2 seconds. Clients can setup a loop to check the status of the GET request on a periodic basis through the current-enrollment-status field to ensure that the token is ready.
  • Subsequent GET enrollment calls: The get enrollment will return all associated tokens with each Account_ID every time the API is called.

Required Paramaters

Parameters Type Format Description
Content-Type Header String

Content type of the request/response

Default value: application/json
Account_id Path String Wallet Account ID, provided by client (this is simultaneously used the API call header)
Program_ID Query String (Integer) Program ID to which the enrollment belongs

Overview of API Output Fields:

  1. Enrollment Identifier (ID). Returns the enrollment identifier of the initial request.
  2. Current Enrollment Status: Used to check if enrollment process is complete.
  3. Wallet / Account Data Object: Returns all relevant user account data that was shared during the initial enrollment request (includes Account_ID).
  4. Visa Pay Core Attributes (not needed, except for specific, optional configuration tasks) such as Account Status Object, Card Information Object, Program_ID.
  5. Generated Token Attributes: Returns all the generated tokens (device, ecomm, etc.) along with any associated meta data.
Output Fields (Selected) Format Description
ID string Enrollment ID of the initial request
Current_enrollment_status Object Used to check if enrollment process is complete
(contains) Name String Returns completion status of the entire enrollment request across multiple tokens. This will show as complete only if all underlying tokens have been generated. Refer to below section for details.
Wallet_Data Object Object See Previous section for details
Account Object Visa Pay internal identifier not used for most operations
Card Object Visa Pay internal identifier not used for most operations
Program Object Contains Program_ID (BIN Configuration) which can be used to check which Program the tokens are being associated with
Token Item Object Object One Token Item object returned per token generated
(contains) ID String This is the Token item ID can be used for various future token LCM calls
(contains) Token String Returns the Visa 16-digit token*
(contains) Token Requestor Data Object Includes the provisioned_token_ID (string) and pan_enrollment_ID (string) which are variables returned from the VTS APIs
(contains) current_token_enrollment_status Object Returns the token generation status of each individual token. Refer to below section for details.
(contains) request Object Returns the type of token in the type (string) field and can be used to distinguish between Ecomm, Device & Scan tokens. Other fields in this object are specific to the HCE / device token type.

Sample Response Schema

Deep dive into Current_Enrollment_Status Options: This object returns the completion status of the entire enrollment request across multiple tokens. This will show as complete only if all underlying tokens have been generated. Please see below for all possible response states along with the visual representation of the states.

  • PENDING: The enrollment process is in progress.
  • ACCOUNT_CREATED: Account creation process is complete.
  • CARD_REQUESTED: Card creation process has been initiated.
  • CARD_CREATED: Card creation process is successfully completed.
  • CARD_ERROR: An error has occurred during card creation process.
  • TOKEN_REQUESTED: Token creation process has been initiated.
  • TOKEN_COMPLETED: Token has been successfully generated.
  • TOKEN_ERROR: An error has occurred during token creation process for any 1 of the requested tokens within the enrollment call; refer to individual current_token_enrollment_status to troubleshoot.
  • COMPLETED: Enrollment process is successfully completed

Deep dive into Current_Token_Enrollment_Status Options: This object returns the completion status of the individual token request. This is a list of all possible responses:

  • PENDING: A token creation is in progress
  • TOKEN_REQUESTED: A token creation has been initiated
  • TOKEN_REQUEST_ERROR: An error occurred during token creation.
  • TOKEN_PROVISIONING_ERROR: An error occurred during token provisioning process
  • TOKEN_COMPLETED: A token has been generated successfully.

Add Tokens To Enrollment [POST]

Endpoint Description: This endpoint allows clients to request additional tokens as part of a previous account enrollment flow. The request will fail if an initial enrollment has not been performed on the Account_ID in question. This endpoint can be used for the following use cases:

  • Request a subsequent, new token type on an existing enrollment (e.g. request a device token when only an ecommerce token has been generated)
  • Request additional tokens of the same/different token type(s) on an existing enrollment (e.g. request a second device token (requires separate device ID) or a second ecommerce token)

Endpoint Details:

  • API URL: https://api.bra01-pci.sandbox.visapay.visa.com/pay-by-wallet/v1/enrollments/:walletAccountId?programId=:programId
  • Endpoint: /v1/enrollments/{external-id}/tokens:
  • Command: POST
  • Direction: Wallet Client
  • Receiver: Visa Pay

Overview of Required Input Parameters: The POST Add Tokens endpoint has the following required input parameters (no additional required fields):

  • Account_ID & Program_ID: This is the client-side external account identifier that has been used to perform the initial enrollment request. Program_ID identifies the BIN.
  • Token Type: Clients can request multiple types of tokens; currently Visa Pay supports two token types (more will be added over time).
    • Ecommerce tokens: May be used for e-commerce transactions as well as
    • Device Tokens: Used for Tap to Pay transactions has more mandatory fields than eCommerce tokens
    • Scan Token (coming soon): An ecomm token type that is specifically used for Scan To Pay transactions (requires device binding)
Parameters Type Format Description
Content-Type Mandatory String (header)

Content type of the request/response

Default value: application/json
Account_id (external_ID) Mandatory String (query) Wallet Account ID, provided by client (this is used in API call header)
Program_ID Mandatory String (query) Program ID to which the enrollment belongs
Tokens Mandatory Array [Object] Contains required fields as described in the initial enrollment request section

Overview of API Output Fields:

  • Enrollment Identifier (ID): Returns the enrollment identifier of the initial request.
  • Account_ID: The unique identifier for the account (wallet_account).
  • Status: The status of the add token process, similar response options to current_token_enrollment_status

Sample Response Schema:

To retrieve the generated tokens, clients need to use the 'Retrieve Generated Tokens' GET endpoint described in section 5.3. The response field from v1/enrollments/{external-id} endpoint such as Tokens_ID and Request_Type can be used to differentiate between tokens.

Search Enrollments [POST]

Endpoint Description: This endpoint enables enrollment lookup by email address, phone number, document number, or wallet account Id. Results are paginated and include complete enrollment details including status, associated tokens, and account information. The search results support cursor-based pagination using page tokens for efficient navigation through large result sets. The search is case-insensitive and returns partial matches where applicable.

Endpoint Details

  • API URL: https://api.bra01-pci.sandbox.visapay.visa.com/pay-by-wallet/v1/enrollments/:walletAccountId?programId=:programId
  • Endpoint: /v1/enrollments/search
  • Command: POST
  • Direction: Wallet Client
  • Receiver: Visa Pay
Parameters Type Format Description
Content-Type Header String (header)

Content type of the request/response

Default value: application/json 

Request Body Fields:

Input Field Type Format Description
Search_type Mandatory Enum Type of search to perform. Select from “EMAIL”, “PHONE_NUMBER”, ”DOCUMENT_NUMBER” or “WALLET_ACCOUNT_ID”
Search_value Mandatory String Value of the search type selected
Page_size Optional Integer Number of search results per page. Default 50.
Page_token Optional String Pagination token to retrieve next set of results.

Overview of API Output Fields:

1. Enrollments: Array of EnrollmentSearchResult object.

2. Page Info: Pagination Metadata Object

Responce Field                     

Type                              

 Description                                                       

enrollments - array of EnrollmentSearchResult

search_metadata  object

Additional metadata related to the search match
emails  array of string (email)  Email addresses associated with the enrollment
phones array of Phone Phone numbers associated with the enrollment
EnrollmentFinderOutput

Object of type

EnrollmentFinderOutput

  
 
Page_Info Object
 
has_more                       boolean                         Indicates if there are more results available 
page_token  string  Token to use for retrieving the next page of results

Sample Response Schema:

Summary of Enrollment Endpoint Error Codes

In case of unsuccessful enroll calls, the table below provides additional error codes. These messages are largely consistent across enrollment endpoints; variations called out separately.

Code Example Description / Causes
200 Code: Successful Enrollment Responses vary by endpoint as shown above
400 Code: INVALID_REQUEST Message: "The request payload is invalid" Bad request error
404 Code: NOT_FOUND Message: " The entity with provided key was not found." Enrollment not found – the Account_ID has not been previously enrolled; GET call and 'Add Token' cannot be used before initial enrollment has taken place.
409 Code: CONFLICT Message: "The idempotency key has already been used" Conflict error – enrollment id has already been issued for this user. Attempting to re-enroll same user. Tip: for additional tokens use endpoint "Add Token to Enrollment" Conflict Error – Device ID has already been enrolled for device token enrollment
500 Code: INTERNAL_ERROR Message: "An Internal Error has occurred" Visa Pay side server error

Payments and Auth Endpoints

Visa Pay payments and authorization endpoints enable transaction authorization callbacks and cryptogram data retrieval for secure payment processing.

Payments & Auth Endpoints Overview

Pre-Requisites: Clients must have completed all VisaNet setup (BIN Config, etc.) and Visa Pay Program Setup (refer to Getting Started) which will result in a Program_ID. Enrollments endpoints must also have been used to request Visa Pay device or ecommerce tokens.

Functionality Overview

Output Fields

Functionality Overview

Recommended Use of Authorization Callback: Clients when receiving the authorization callback webhook from Visa Pay need to respond back to Visa Pay within 3 seconds to avoid timeouts; the recommended time to respond for most Visa clients is between 800 - 1000 ms.

Functionality Endpoint Description

Authorization Webhook

Callback

 {wallet-defined-authorize-endpoint} This is an outbound call from Visa Pay that requires clients to set up and communicate to Visa the endpoint that will be called to send the payload with an authorization request. Visa Pay receives transaction information and processes it accordingly before sending a callback to the endpoint defined by client, which will be routed back to Visa for completion of transaction.

Retrieve Cryptogram Data

GET

 /v1/enrollments/{external-id}/cryptogram-data Request cryptogram information for a specific wallet account and token id. The cryptogram is used for ecommerce transactions and can be in the form of TAVV or DTVV.

Recommended Use of Authorization Callback: Clients when receiving the authorization callback webhook from Visa Pay need to respond back to Visa Pay within 3 seconds to avoid timeouts; the recommended time to respond for most Visa clients is between 800 - 1000 ms.

Authorization Webhook Callback

API provides the following functionalities: Authorization Webhook Callback Visa Pay clients making use of the Visa Pay API will leverage a simplified authorization messaging flow for streamlined authorization decision making.

Visa Pay clients must expose an inbound API endpoint for Visa to call clients requesting an authorization response, which will be sent through Visa Pay's outbound endpoint "/{wallet-defined-authorize-endpoint}". This call will contain the reduced subset of the ISO message for simplified decision making, while also including all of the ISO message fields encapsulated in a JSON format within the original_network_data element of the body.

Connecting to the API requires a setup that is detailed in the following section (3). Below are the details of the authorization callback, for which clients must create a process to handle authorization requests.

Request Body elements included in outbound API call to "/{wallet-defined-authorize-endpoint}":

  • id – Unique transaction identifier

    Example: face7e59-8885-49ec-a842-8ddd1f0bfd0f

  • entity – Entity Type

    Example: "transaction"

Response Schema

{
  "id": "face7e59-8885-49ec-a842-8ddd1f0bfd0f",
  "entity": "transaction",
  "fields": {
    "account_id": 0,
    "program_id": 0,
    "card_id": 0,
    "payment_card_brand": "VISA, Mastercard",
    "transaction_code": "0",
    "local_amount": 0.1,
    "settlement_amount": 0.1,
    "local_currency": "986",
    "settlement_currency": "986",
    "merchant_name": "string",
    "merchant_city": "string",
    "merchant_state_or_country_code": "string",
    "merchant_date_time": "2025-06-01T12:10:20",
    "network_scheme_metadata": {
      "mti": "0100",
      "response_code": "string",
      "authorization_code": "string",
      "retrieval_reference_number": "string",
      "transaction_identifier": "string"
    },
    "pay_by_wallet_reference_data": {
      "wallet_account_id": "0100",
       "enrollment_metadata": {
        "additionalProp1": {}
      }
    },
    "token": "string",
    "original_network_data": {}
  }
}
Copied!

Summary of Fields in Authorization Callback

Field Format Description
Account_id Integer Pismo Account ID, provided by enrollment feature
Program_id Integer Pismo Program ID, provided by enrollment feature
card_id Integer Pismo Card ID, provided by enrollment feature
Payment_card_brand String Network brand of the card, provided by ISO 8583 message
Transaction_code String Transaction type code based on ISO 8583
Local_amount number (float) Transaction local amount in local currency, provided by ISO 8583 message
Settlement_amount number (float) Transaction settlement amount in local currency, provided by ISO 8583 message.
Local_currency String Transaction currency code based on ISO 4217 numeric code, provided by ISO 8583 message
Settlement_currency String Transaction settlement currency code based on ISO 4217 numeric code
Merchant_name String Merchant Name – Raw Descriptor
Merchant_city String Merchant City
Merchant_state_or_ country_code object Merchant state or country.
Merchant_date_time String (date-time) Merchant date and time
Network_scheme_metadata Object Fields below
Mti String MTI provided by ISO 8583 message
Response_Code String Response code, this value should be two characters string according with ISO-8583 and card network specifications.
Authorization_code String Authorization code
Retrieval_reference_number String Retrieval reference number, provided by ISO 8583 message
Transaction_identifier String Transaction identifier, provided by ISO 8583 message
Pay_by_wallet_reference_data Object Fields below
Wallet_account_id String MTI provided by ISO 8583 message
Enrollment_metadata Object Metadata related to the enrollment
Token String Token ID
Original_network_data Object Raw ISO8583 message without PCI fields

Summary of Fields in Authorization Response: The response output for the authorization request must be present in the following structure:

Authorization Response Fields

Field Format Description

Response_code

 string Response code, this value should be two numbers string according with ISO-8583 and card network specifications

Sample Response:


{
  "response_code": "00",
}
Copied!
Summary of Fields in Authorization Callback
Authorization Response Fields

Available response codes for Visa Pay clients:

Response Codes

Response Codes
Code Definition
00 Approval and completed successfully
05 Do Not Honor (generic)
12 Invalid Transaction
51 Not Sufficient Funds
78 Blocked Account
N0 System Malfunction – Force STIP

Clients will have to respond to this Visa Pay POST call within 3 seconds to avoid timeouts and automatic declines to VisaNet. In the event that a response is not provided within this 3 second window, Visa Pay will automatically decline the transaction to VisaNet. In order to track this flow client must set up real-time clearing events or request Visa Advice services – more details in the next section.

For complete documentation on the on the MTI codes and other details, please refer to the separate Payload Authorization Webhook document.

Get Cryptogram Data (POST)

Endpoint Description: This endpoint allows clients to request a payment cryptogram to initiate an ecommerce or scan transaction when the user needs it using Account_ID, Program_ID, and Token Identifiers (provisioned_token_ID) which is a field shared during the enrollment flow. The endpoint can generate the following types of cryptograms:

  • TAVV: Used for general ecommerce use cases and is the primary cryptogram type that is required for Visa token transactions. TAVV is larger format value and is not designed to be keyed in.
  • DTVV: Used for special purpose key entry ecomm transactions and the value is similar to a 3-digit CVV used for physical card transactions.

Endpoint Details:

Endpoint Information

Endpoint Information
API URL https://api.bra01-pci.sandbox.visapay.visa.com/pay-by-wallet/v1/enrollments/{external-id}/payment-data
Endpoint /v1/enrollments/{external-id}/payment-data
Command POST
Direction Wallet Client
Receiver Visa Pay

Overview of Required Input Parameters: The GET endpoint has the following required input parameters (no additional required fields):

Input Parameters

Input Parameters
Input Field Type Format Description

Content-Type

 Mandatory String (header) Content type of the request/response Default value: application/json

Account_id(external_ID)

 Mandatory String (query) Wallet Account ID, provided by client (this is used in API call header)

Program_ID

 Mandatory String (query) Program ID to which the enrollment belongs

Provisioned_token_ID

 Mandatory String VTS Generates field to identify the token

client_payment_data_id

 Mandatory String Reference identifier defined by client. No uniqueness required.

Cryptogram_type

 Mandatory String Input TAVV or DTVV

Overview of API Output Fields:

Output Fields

Field Description
Cryptogram Returns the TAVV.
Dtvv_cryptogram Returns the DTVV
atc VTS generated field that accompanies the TAVV

Lifecycle Management Endpoints

Visa Pay lifecycle management endpoints enable comprehensive token and account management including blocking, updating, and replenishing tokens for enrolled accounts.

Lifecycle Management Endpoints Overview

Pre-Requisites: Clients to have completed all VisaNet setup (BIN Config, etc.) & completed Visa Pay Program Setup (refer to Section 1) which will result in a Program_ID. Enrollments endpoints need to also have been used to request Visa Pay device or ecommerce tokens.

Functionality Endpoint Description

Block Account / Enrollment

PATCH

 /v1/enrollments/{external-id}/status This endpoint is used to block all Visa functionality for an enrolled account

Block Token

PATCH

 /v1/enrollments/{external-id}/tokens/{token-id}/status This endpoint is used to block payment functionality for a single token

UpdateEnrollment

PATCH

 /v1/enrollments/{external-id} This endpoint is used to update enrollment data / attributes of each previously enrolled account

Replenish HCE Token

POST

 /v1/enrollments/{external-id}/replenish Refreshes token cryptographic keys and replenishes counter-based payment credentials for HCE / device tokens

Block Enrolled Account (PATCH)

Endpoint Description: This endpoint allows clients to block or unblock the entire enrolled Visa Pay account. This endpoint will block all payment use case across all tokens – this can be used to delete/ block a user who has opted out of Visa Pay capabilities.

Endpoint Details:

  • API URL: https://api.bra01-pci.sandbox.visapay.visa.com/pay-by-wallet/v1/enrollments/{External-Id}/{status}
  • Endpoint: /v1/enrollments/{external-id}/status
  • Command: PATCH
  • Direction: Wallet Client
  • Receiver: Visa Pay

Overview of Required Input Parameters: The PATCH endpoint has the following required input parameters (no additional required fields):

Input Field Type Format Description

Content-Type

 Mandatory String (header) Content type of the request/response Default value: application/json

Account_id(external_ID)

 Mandatory String (query) Wallet Account ID, provided by client (this is used in API call header)

Program_ID

 Mandatory String (query) Program ID to which the enrollment belongs

Status

 Mandatory String Client can select between BLOCKED NORMAL and CANCELLED

Overview of API Output Fields: The PATCH endpoint has the following output parameters in the response body.

  • Enrollment ID: Identifier of the original enrollment request
  • Status: Returns new status of account (blocked / normal/ cancelled)

Adjacent Operations: The PATCH endpoint can also be used to unblock the enrolled account. A separate call can also be made to query the status of the enrolled account.

Block Token (PATCH)

Endpoint Description: This endpoint allows clients to block or unblock individual tokens within an enrolled account. This provides granular control over token functionality while maintaining the overall account enrollment.

Endpoint Details:

  • API URL: https://api.bra01-pci.sandbox.visapay.visa.com/pay-by-wallet/v1/enrollments/{external-id}/tokens/{token-id}/status
  • Endpoint: /v1/enrollments/{external-id}/tokens/{token-id}/status
  • Command: PATCH
  • Direction: Wallet Client
  • Receiver: Visa Pay

Overview of Required Input Parameters:

Input Field Type Format Description
Content-Type Mandatory String (header) Content type of the request/response Default value: application/json
Account_id(external_ID) Mandatory String (query) Wallet Account ID, provided by client
Program_ID Mandatory String (query) Program ID to which the enrollment belongs
Token_ID Mandatory String (path) Specific token identifier to be blocked or unblocked
Status Mandatory String Token status: BLOCKED, NORMAL, or CANCELLED

Overview of API Output Fields:

  • Token ID: Identifier of the specific token
  • Status: Returns new status of the token
  • Enrollment ID: Associated enrollment identifier

Update Enrollment (PATCH)

Endpoint Description: This endpoint allows clients to update enrollment data and attributes for previously enrolled accounts. This enables modification of account information without requiring re-enrollment.

Endpoint Details:

  • API URL: https://api.bra01-pci.sandbox.visapay.visa.com/pay-by-wallet/v1/enrollments/{external-id}
  • Endpoint: /v1/enrollments/{external-id}
  • Command: PATCH
  • Direction: Wallet Client
  • Receiver: Visa Pay

Overview of Required Input Parameters:

Parameters Type Format Description

Content-Type

 Mandatory String (header)

Content type of the request/response

Default value: application/json

Account_id (external_ID)

 Mandatory String (query) Wallet Account ID, provided by client (this is used in API call header)

Program_ID

 Mandatory String (query) Program ID to which the enrollment belongs

Tokens

 Mandatory Array [Object] Contains required fields as described in the initial enrollment request section

Overview of API Output Fields:

  • Enrollment ID: Identifier of the updated enrollment
  • Updated_Fields: Confirmation of fields that were successfully updated
  • Status: Current enrollment status after update

Replenish HCE Token (POST)

Endpoint Description: This endpoint refreshes token cryptographic keys and replenishes counter-based payment credentials for HCE (Host Card Emulation) and device tokens. This is essential for maintaining secure token operations over time.

Endpoint Details:

  • API URL: https://api.bra01-pci.sandbox.visapay.visa.com/pay-by-wallet/v1/enrollments/{external-id}/replenish
  • Endpoint: /v1/enrollments/{external-id}/replenish
  • Command: POST
  • Direction: Wallet Client
  • Receiver: Visa Pay

Overview of Required Input Parameters:

Input Field Type Format Description
Content-Type Mandatory String (header) Content type of the request/response Default value: application/json
Account_id(external_ID) Mandatory String (query) Wallet Account ID, provided by client
Program_ID Mandatory String (query) Program ID to which the enrollment belongs
Token_ID Mandatory String Specific HCE/device token identifier to be replenished
Replenish_Type Optional String Type of replenishment: KEYS, COUNTERS, or FULL

Overview of API Output Fields:

  • Token ID: Identifier of the replenished token
  • Replenishment_Status: Status of the replenishment operation
  • New_Key_Data: Updated cryptographic key information
  • Counter_Reset: Confirmation of counter-based credential reset

Use Cases for HCE Token Replenishment:

  • Scheduled Maintenance: Regular key rotation for security compliance
  • Counter Exhaustion: Refresh payment credentials when counters approach limits
  • Security Events: Immediate replenishment after security incidents
  • Token Lifecycle Management: Proactive maintenance of token health

Bind Token To Device [POST]

Endpoint Description: This endpoint binds a previously provisioned Visa Pay token to a specific client device. Device binding associates the token with a unique device identifier, enabling secure, device‑based payment transactions and preventing the token from being used on unauthorized devices.

Endpoint details

  • API URL: https://api.bra01-pci.sandbox.visapay.visa.com/pay-by-wallet/v1/enrollments/{external-id}/tokens/{token-id}/device-binding
  • Endpoint: /v1/enrollments/{external-id}/tokens/{token-id}/device-binding
  • Command: Post
  • Direction: Wallet Client
  • Reciever: Visa Pay

Required Parameters: The Bind Token to Device endpoint has the following required input parameters

Input Field Type Format Description
Content-Type Header String Content type of the request/response. Default value : application/json
externalId  Path String  External ID of the enrollment(wallet_account_id)
tokenId Path String Token ID to be bound to the device

Overview of Request Body Fields

Input Field Type Format Description
program_id  Mandatory Integer Program ID to which the enrollment belongs
sig_binding_request  Mandatory String (JWS format)  Signed binding request data
device_id  Mandatory String, max 24 characters  Unique device identifier
client_ref_id  Optional String, max 36 characters   Client reference ID for tracking
email Optional String, email format  Email address associated with the device
platform_type  Mandatory String, Enum:ANDROID, IOS,WINDOWS Platform type of the device

Overview of API Output Fields: The Bind Token to Device endpoint has the following output

parameters in the response body.

1. Code: HTTP status code representing the outcome of the request

2. Message: As per the code, a message describing the result of the operation

Sample Response Schema:

Unbind Token from Device [POST]

Endpoint Description: This endpoint unbinds a previously bound device from an existing Visa Pay token. Unbinding removes the association between the token and the device, preventing the token from being used for device‑based payment transactions until it is bound again.

Endpoint Details:

  • API URL: https://api.bra01-pci.sandbox.visapay.visa.com/pay-by-wallet/v1/enrollments/{external-id}/tokens/{token-id}/device-unbinding
  • Endpoint: /v1/enrollments/{external-id}/tokens/{token-id}/device-unbinding
  • Command: Post
  • Direction: Wallet Client
  • Reciever: Visa Pay

Required Parameters: The Unbind Token from Device endpoint has the following required input parameters

Input Field Type Format Description
Content-Type Header String Content type of the request/response. Default value : application/json
externalId  Path String  External ID of the enrollment(wallet_account_id)
tokenId Path String Token ID to be bound to the device

Overview of Request Body Fields:

Input Field Type Format Description
program_id  Mandatory Integer  Program ID to which the enrollment belongs

Overview of API Output Fields: The Unbind Token to Device endpoint has the following output

parameters in the response body.

1. Code: HTTP status code representing the outcome of the request

2. Message: As per the code, a message describing the result of the operation

Sample Response Schema:

Confirm Token Provision [POST]

Endpoint Description: This endpoint confirms the provisioning status of a Visa Pay token after the device‑side provisioning flow completes. The wallet application must invoke this endpoint once the device provisioning process concludes, regardless of whether the provisioning succeeded or failed, in order to report the outcome back to the token requestor service and allow the token lifecycle state to be updated accordingly.

For successful NFC‑HCE token provisioning, the api (Account Parameter Index) field is required. In the case of NFC‑SE provisioning failures, the optional apdu_reason_code array may be provided to supply GP‑compliant APDU error details.

When confirming a repersonalization flow, the request must set reperso to true and include the v_notification_id returned during the repersonalization initiation step.

Endpoint Details:

  • API URL: https://api.bra01-pci.sandbox.visapay.visa.com/pay-by-wallet/v1/enrollments/{external-id}/tokens/{token-id}/confirm
  • Endpoint: /v1/enrollments/{external-id}/tokens/{token-id}/confirm
  • Command: Post
  • Direction: Wallet Client
  • Receiver: Visa Pay

Required Parameters: The Confirm Token Provision endpoint has the following required input parameters

Input Field Type Format Description
Content-Type Header String Content type of the request/response. Default value : application/json
x-tenant  Header String Tenant ID
externalId  Path String  External ID of the enrollment(wallet_account_id)
tokenId Path String Token ID to be bound to the device

Overview of Request Body Fields:

Input Field Type Format Description
program_id  Mandatory  Integer  Program ID to which the enrollment belongs 
provisioning_status  Mandatory  String, Enum:SUCCESS, FAILURE Status flag indicating whether provisioning was successful or failed
api Conditional String  Account Parameter Index (API). Required when provisioning_status= SUCCESS for NFC-HCE tokens
failure_reason  Optional  String Reason description if available during a provisioning failure for NFC-HCE or NFC-SE
apdu_reason_code  Optional Array of Object type ApduReasonCode Array of APDU line numbers and GP-compliant reason codes. Used only for NFC-SE failures 
reperso Optional Boolean Default: false  Indicates whether the confirmation is for a repersonalization flow
v_notification_id  Conditional String Repersonalization notification ID. Required when reperso = true

Overview of API Output Fields:

Input Field Type Description
id String  Enrollment ID
token String Provisioned token value
requested_token_id  String Token ID originally requested during provisioning
token_requestor_data Object of type TokenRequestorData  Token requestor–specific data
current_token_enrollment_status  Object of type TokenStatus Current enrollment status of the token

Sample Response Schema:

Simulate Endpoint (Sandbox Only)

Prerequisites: Client has exposed an endpoint configured as per the description in the Auth Webhook Payload.

Endpoint Description: Provides a testing environment to simulate wallet authorization transactions without connecting to the live payment network.

Endpoint details:

  • API URL: https://api.bra01-pci.sandbox.visapay.visa.com/pay-by-wallet/v1/simulate
  • Endpoint: /v1/simulate
  • Command: Post
  • Direction: Visa Pay
  • Receiver: Wallet
Input Field Type Format Description
mti Mandatory String MTI provided by ISO 8583 message.
program_id  Mandatory  String Program ID to which the enrollment belongs
network Mandatory String Name of card network.
Local_amount  Mandatory  String Transaction local amount in local currency.
Local_currency  Mandatory String  Transaction local currency code based on ISO 4217 numeric code.
Settlement_amount  Optional  String  Transaction settlement amount in settlement currency.
Settlement_currency  Optional String Transaction settlement currency code based on ISO 4217 numeric code. 
token  Optional String Token, if the transaction is related to a token.
Transaction_type_code  Mandatory  String Transaction type code based on ISO8583.
Wallet_data  Mandatory Object  Wallet related information
Account_id  Mandatory String Wallet Account identifier
Customer_id  Mandatory String Customer identifier
Email_id  Mandatory  String  Email address for customer
Phone  Mandatory  Object  
Phone number    String 
  
Country Code    String 
  
Full_name  Mandatory  String 
  
User_name    String 
  
Document number    String 
  
Raw_data  Mandatory  Object Raw data from ISO 8583 message

Overview of API Output: The Simulate endpoint will respond with success if it can reach the configured auth endpoint.