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.

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:

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.

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

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

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

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

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

Sample Response Schema

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

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.

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)

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.

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

Overview of API Output Fields:

1. Enrollments: Array of EnrollmentSearchResult object.

2. Page Info: Pagination Metadata Object

enrollments - array of EnrollmentSearchResult

Sample Response Schema:

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.

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

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.

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.

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

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

Sample Response:

Available response codes for Visa Pay clients:

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.

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:

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

Overview of API Output Fields:

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

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.

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):

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.

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:

Overview of API Output Fields:

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

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:

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

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:

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

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 Confirm Token Provision endpoint has the following required input parameters

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