Originating Entities can use the Visa Direct Account and Wallet Send API bundle for processing a payout. This API bundle supports operations such as ‘Send Payout’, ‘Query’, 'Validate', 'Get Account Balance' and ‘Cancel’, please refer below for the end-to-end flow of each operation. Note, in each of these operations the Originating Entity is the initiator of the API request while Visa is the recipient.
The Send Payout API allows an Originating Entity to send payouts to bank accounts or to wallets. This is an illustration of the end-to-end payout processing flow. Availability of Payouts varies by region, contact your Visa representative for more information.
Step |
Description |
|---|---|
1 |
Originating Entity initiates a payout request, with Sender and Recipient details, including Recipient’s account (wallet or bank account). |
| 2 & 3 | Visa routes the payout request to Visa Payments Limited. If the payout is to a bank account, Visa Payments Limited performs all the data validation to ensure that the payout can be supported by one of its Network Partners and acknowledges the request back to Visa with an estimated posting date (i.e., date when the recipient will receive the deposit in their bank account) If the payout is to a wallet, Visa Payments Limited performs all the data validation to ensure that the payout can be supported by one of the Wallet Aggregator and acknowledges the request back to Visa with an estimated posting date (i.e., date when the recipient will receive the deposit in their wallet) |
4 |
Visa responds back to the Originating Entity with the result of the payout, and the estimated posting date. The Originating Entity should assume that the payout will be deposited successfully to the recipient’s account or wallet on the estimated date and communicate the status to the relevant end customers. Note: In case the payout request fails any validation, the Originating Entity will get an error response with detailed error codes identifying the reason for the failure. |
The Originating Entity can request for the latest status of the payout transaction using the Query API. The Originating Entity can send the query request by either including the Payout ID or Client Refrerence ID in parameters.
Step |
Description |
|---|---|
1 |
The Originating Entity can send the Query API request to get the latest status from Visa by including the Payout ID or Client Refrence ID |
2 |
Visa responds back to the Originating Entity with the latest Transaction Status |
Status Updates: When Visa has a status update to the transaction it will initiate a status update to Originating Entity through an API. These are asynchronous calls between the Visa and Originator.
Originating Entity may request to cancel a transaction in scenarios where the Sender sent to an incorrect Recipient or the wrong amount in the payout instructions, or sent a duplicate payout in error to stop a payment submitted to Visa for processing. Visa can accept the cancellation request if the payment has not been sent to Network Partner or Wallet Aggregator. If Visa has accepted the cancel request, then it will initiate a Return Notification transaction to the Originating Entity.
Step |
Description |
|---|---|
1 |
Originating Entity initiates a cancellation request using the Cancel API, and includes the Payout ID or Client Reference ID and Initiating Party id for requesting this cancellation |
2 |
Visa routes the payout request to the Visa Payments Limited. Visa Payments Limited accepts the cancellation request if the transaction has not been sent to the Network Partner or Wallet Aggregator. |
3 |
Visa Payments Limited acknowledges the request back to Visa including the status of the cancel request. |
4 |
Visa responds back to the Originating Entity with the status of the cancel request. In case the cancel request fails any validation, or Visa Payments Limited cannot cancel the transaction, the Originating Entity will receive an error response. |
5 |
If Visa Payments Limited has accepted the cancel request, then it will initiate a return through the Return Payout API, with the transaction identifiers of the original payout getting returned and the reason for the return. |
6 |
Visa notifies the Originating Entity through the Return Payout API, providing all the details of the returned payout. The Originating Entity responds back with a simple response acknowledging that the notification was received. |
Designed to reduce payout errors, the Validation API allows Originating Entities to validate account and wallet transactions before the payout is sent via the Send Payout API for clearing and settlement. The Validation API performs schema checks(format, mandatory fields, etc.) and route specific checks(based on Network Partner or Wallet Aggregator requirements) and exposes validation errors identifying where the Originating Entity should make corrections prior to payout.
STEP |
DESCRIPTION |
1 |
Originating Entity initiates a payout validation request, with Sender and Recipient details, including Recipient’s bank account or wallet details. |
2&3 |
Visa routes the payout request to Visa Payments Limited that can support that payout. Visa Payments Limited performs the following validations and acknowledges the request back to Visa. · Schema (format, mandatory fields, etc.) · Route Specific Validations (based on Network Partner requirements or Wallet Aggregator requirements) · Subset of AML Validations (full validations are done at Payout) · Validation with Wallet Aggregator/Wallet Operator (valid only for wallet use-case) |
4 |
Visa responds back to the Originating Entity with the result of the validation. If the payout request fails any validation, the Originating Entity will receive an error response with detailed error codes identifying the reason for the failure. |
Get Payout Metadata API provides all the field requirements of a destination route (country or country cluster and currency combination) to an Originating Entity. An Originating Entity can use this API before actual Send Payout and Validation API request to know what are required fields in Send Payout request for a specific destination route. For more information regarding the Get Payout Metadata API, click here.
STEP |
DESCRIPTION |
1 |
Originating Entity initiates a Get Payout Metadata request, with sendertype, recipient details, Initiating Party Id and payout method. |
2 |
Visa responds back to the Originating Entity with the result of the Get Payout Metadata API. If the Get Payout Metadata request fails any validation, the Originating Entity will receive an error response with detailed error codes identifying the reason for the failure. |
An Originating Entity can get the balance for their Virtual Account Number (VAN) for associated currency by using Get Account Balance API. An Originating Entity must send the respective Initiating Party ID and three character currency code in API request parameters.
Note: The Virtual Account Number (VAN) is given to an Originating Entity during client onboarding.
Step |
Description |
|---|---|
1 |
Originating Entity sends the Get Account Balance API request to Visa to get the balance for a given VAN.
|
2 & 3 |
Visa sends the transaction to Visa Payments Limited to process. Visa Payments Limited gets the balance of the VAN associated with the Initiating Party Id and currency code given in the request and sends response back to Visa. |
4 |
Visa responds back to the Originating Entity with the result of the Get Balance API. In case of invalid Initiating Party Id or currency code, the Originating Entity will receive an error response with detailed error codes identifying the reason for the failure. |
Originating Entities must be able to receive the following APIs from Visa for processing their account or wallet payout. In this case Visa is the initiator of the API request while Originating Entity is the recipient
The payouts sent to a bank account or wallet may get returned for multiple reasons, for e.g. if the bank account or wallet details provided are not accurate or the account or wallet is not active or the payout was cancelled by the Originating Entity etc., The Originating Entity will receive notifications from Visa with details of such returned payouts.
Step |
Description |
|---|---|
1 |
When Visa Payments Limited receives a returned payout from its Network Partner or Wallet Aggregator, Visa Payments Limited will initiate a return through an API, with the transaction identifiers of the original payout and the reason for the return. |
2 |
Visa notifies the Originating Entity through the Return Notification API, providing all the details of the returned payout. |
3 |
The Originating Entity responds back with a simple response acknowledging that the notification was received. |
4 |
Visa responds back to Visa Payments Limited acknowledging that the payout return has been accepted. |
The Originating Entity will be notified of status changes of a payout transaction along with the updated expected posting date. The Originating Entity should implement to accept this call back request when the status is changed.
Step |
Description |
|---|---|
1 |
When Visa Payments Limited has a status update for a transaction, it will send a notification through an API. |
2 |
Visa will update the status of the payout transaction in the system and send back an acknowledgement to Visa Payments Limited in the response. |
3 |
Visa will send a Status Notification request to the Originating Entity including the updated transaction status and the updated expected posting date. |
4 |
The Originating Entity responds back via an acknowledgement to Visa. |
This API will convey details of all debits/credits posted to an Originating Entity’s settlement account with Visa for a given processing day. Ledger notification supports credit/debit change with respect to the following transaction types:
Step |
Description |
|---|---|
1 |
Visa Payments Limited send the API request to Visa about any credit/debit update on Originating Entity's account associated with Visa. |
2 |
Visa will update details in the system and send back an acknowledgement to Visa Payments Limited in the response. |
3 |
Visa will send a Ledger Notification request to the Originating Entity including the updated credit/debit change in Originating Entity's account associated with Visa. |
4 |
The Originating Entity responds back via an acknowledgement to Visa. |
This API provides easy access to the Visa daily currency exchange rate for a given currency pair. With Foreign Exchange Rates, Originating Entities can provide a better user experience for cross -border and/or multicurrency transactions. The Foreign Exchange Rates API allows Originating Entities to provide a source amount with a source and destination currency pair to get back the source amount converted into the destination currency using Visa's daily foreign exchange rates. This API can be used for multi-currency or cross-border payouts, such as cross-border remittances or person-to-person money transfers.
For further details on the FX API please refer to Visa Developer Platform
Step |
Description |
|---|---|
1 |
The Originating Entity initiates a foreign exchange rate request using the FX API, and includes the Source Currency, Destination Currency and Source Amount. An Originating Entity should use rateProductCode value 'BANK' to get the currency rate for an account bound transaction. An Originating Entity should use rateProductCode value 'WALLET' to get the currency rate for a wallet bound transaction. |
2 |
Visa responds back to the Originating Entity with the Destination Amount and the Conversion Rate. The Originating Entity can display the destination amount to the Sender. This is the amount that will be send to the Recipient account. |
3 |
The Originating Entity initiates a payout request, with transaction amount as source amount as submitted in the FX API, so that destination amount as calculated by FX API will be delivered to the recipient account/card. |
4 & 5 |
If the payout is to a bank account, Visa routes the payout request to Visa Payments Limited with the same destination amount as was returned by the FX API. If the payout is to a wallet, Visa routes the payout request to Visa Payments Limited with the same destination amount as was returned by the FX API. Note: The FX rate is only valid for a 24 hour period with a specific daily cut off time |
6 |
Visa responds back to the Originating Entity with the result of the payout, and the estimated posting date with the destination amount. |
Visa Direct Account transaction goes through different states while processing. Each state has a status of transaction. Complete lifecycle of a transaction can be found below.
Visa Direct Wallet transaction goes through different states while processing. Each state has a status of transaction. Complete lifecycle of a transaction can be found below.
As you build your new money transfer, prepaid load, credit card bill pay, or funds disbursement solutions using the Funds Transfer or Mobile Push Payment APIs, there are three other APIs available from Visa that may be useful in your project.
If your project supports cross-border transfers, you must notify the sender of the amount in the sender’s currency that will be withdrawn from the sender’s account. You may also want to notify the sender, the recipient, or both of the amount in the recipient’s currency of the push payment. The Foreign Exchange Rates API enables you to input a source amount and a source and destination currency pair and receive back the current day Visa exchange rate and the converted amount in the destination currency. For example, if the sender wants to withdraw a specific amount, this API will enable you to determine how much the recipient will then receive in their local currency. Similarly, if the sender wants the recipient to receive a specific amount in their local currency, this API will enable you to determine how much must be from the sender’s account to do so.
¹Actual fund availability varies by receiving financial institution, receiving account type, region, and whether transaction is domestic or cross-border.
2Availability varies by market. Please refer to your Visa representative for more information on availability.
3Use cases are for illustrative purposes only. Program providers are responsible for their programs and compliance with any applicable laws and regulations.
Start a Project
API Overview
API Reference