Originating Entities can use the Visa Direct for 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’, 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 Originating Entities to send payouts to a bank account and a wallet. Visa will then route the payment request based via Visa Payments Limited (VPL). If the payment method is to a bank account, VPL will send the payment instruction to a Network Partner. The Network Partner will send the credit directly to the Recipient Financial Institution who will credit the Recipient’s account. If the payment method is to a wallet, VPL will send the payment to either Wallet Aggregator or Wallet Operator. The Wallet Aggregator or Wallet Operator will send the credit directly to the Recipient wallet.
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 Query Payout API allows Originating Entities to query in real-time the processing status of Visa Direct for Account and Wallet transactions. Query API checks the latest state of an account or wallet transactions and returns the results; transaction successfully or erroneously received and processed by Visa and/or the financial institutions. Query API can also be invoked when there is no response returned from Visa for the Send Payout API.
Retention Period - 180 days. A transaction can be queried within 180 days from the date it was originated. After this period, the transaction can no longer be queried through API.
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 and stop a payment in scenarios where the Sender sent to an incorrect recipient or the wrong amount in the payout instruction or sent a duplicate payout in error. Visa can accept the cancellation request if the payment has not been sent to Network Partner or Wallet Aggregator or Wallet Operator. If Visa has accepted the cancel request, then it will initiate a Notification/Return transaction to the Originating Entity.
Retention Period - 90 days. A transaction can be cancelled within 90 days from the date it was originated. After this period, the transaction can no longer be cancelled through API.
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 Validate Payout API allows Originating Entities to validate account and wallet transactions PRIOR to the payout being sent via the Send Payout API for clearing and settlement. The Validation API performs schema check (format, mandatory fields, etc.) and route specific check (based on Network Partner and Wallet Aggregator and Wallet Operator 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. |
The Originating Entity can check its Virtual Account balance for associated currency using Get Account Balance API.
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. Refer below for the end-to-end flow of each operation.
Payouts sent to a bank account or wallet may get returned back for multiple reasons, for example, if the bank account or wallet details provided are not accurate, or the account or wallet details are accurate but the account or wallet is not active or the Originating Entity has requested to cancel the payout if it is funded. In such cases, Visa will send the payout return notification request to the Originating Entity.
Retention Period - 180 days. The information provided in the Payout Return Notification API is available to be queried for 180 days.
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 the initial transaction status of an account or wallet payout transaction as well as of any status changes at each key step, along with the updated expected posting date.
Retention Period - 180 days. The information provided in the Payout Status Notification API is available to be queried for 180 days.
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. |
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 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.
Get Payout Metadata API is an optional API that enables clients to automate manual processes related to route requirements. The API will return all the required, conditional, and recommended fields to send a payment.
Start a Project
API Overview
API Reference