Visa Direct Connect offers a suite of user-friendly APIs designed to facilitate the transfer of funds between a wide array of payment products supported by Visa Direct. These APIs simplify the process of moving money, facilitating a streamlined integration experience for developers.
This section delves into the specific APIs provided by Visa Direct Connect, detailing their functionalities and how they cater to various use cases. Whether you're looking to enable peer-to-peer transfers, business disbursements, or other forms of payment transactions, Visa Direct Connect APIs offer the tools you need to build efficient and secure payment solutions.
The process to send money includes the following steps:
Pre-Transactional
Transactional
Post-Transactional
The Get Balance API is specifically designed to enable Originating Entities to check their current balance in any chosen settlement currency. This functionality is exclusively applicable to entities categorized under 'Account' and 'Wallet'.
This API is essential for Originating Entities, enabling them to effectively track and manage their finances in real-time across various currencies.
The Balance Response provides Originating Entities with a list of balances for all the currencies they may have or has transacted with:
The Get Posting Calendar is designed to obtain the settlement calendar specific to a currency and country pairing, considering the banking holidays observed in the recipient's country, for a defined range of dates. This functionality is exclusively applicable to entities categorized under 'Account' and 'Wallet'.
This ensures that any financial transactions are accurately scheduled according to both the currency involved and the banking practices of the country in question.
The Notification Response provides an array of Posting Date objects. Each Posting Date represents the expected posting date along with that date's cut-off time:
Visa provides daily foreign exchange (FX) rates for the 180+ global currencies that are used within VisaNet to authorize and settle transactions. This API provides easy access to the Visa daily currency exchange rate for a given currency pair. With Foreign Exchange Rates, originators can provide a better user experience for cross-border and/or multicurrency transactions. The Foreign Exchange Rates API allows originators 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.
This functionality is designed to facilitate easy and efficient currency conversions, providing essential data for financial transactions.
For more information about Visa Direct for Foreign Exchange Rates, see: Foreign Exchange Overview (visa.com)
Flow diagram:
For fixed rates, use currency pair with “quote Id Required=true” in the FX Request. It provides a quote ID for the same pair transactions, which is valid until the quote expires.
For indicative rates, provide the currency pair and source amount. The response provides rate and destination amount, which are not guaranteed at payout.
Similar process with destination amount provides indicative rate and source amount, which are not guaranteed at payout.
Response
Start a Project
API Overview
API Reference
{
"rateProductCode": "string",
"destinationCurrencyCode": "string",
"quoteIdExpiryDateTime": "string",
"sourceCurrencyCode": "string",
"conversionRate": "string",
"quoteId": "string"
}
The Validate Payout API is designed to enable an originator to conduct a preliminary verification of the payload prior to submitting the actual payout request for processing. This functionality is exclusively applicable to entities categorized under 'Account' and 'Wallet' and ‘Card’.
This step significantly enhances the likelihood of a successful transaction by identifying and addressing potential issues early in the process. As a result, it facilitates a smoother and more efficient transaction flow, ultimately benefiting both the originator and the end recipient.
Best Practice: Recommended to minimize potential for negative payment experience
Flow diagram:
The Validation Response indicates if the Payout request is valid and can be processed if sent as a payout transaction:
This functionality allows originators to initiate a payout request through Visa, enabling the movement of funds to a variety of payment methods, including cards, bank accounts, or digital wallets.
It also offers the originators the ability to conduct transactions that simultaneously withdraw funds from a Sender's payment card and deposit them into a Recipient's card. This dual-action capability streamlines the process of transferring funds, making it more efficient for all parties involved.
1. Supports payments via ‘Card’, ‘Account’, and ‘Wallet’
2. Routing decision is client driven e.g., the client has the option to choose either Visa Direct for Account, Visa Direct for Wallet or Visa Direct for Card as the routing method
3. Clients can assign their own unique identifiers, such as a Client Reference ID and end-to-end IDs, to help streamline the process
4. Support for FX ID generated by Visa for a payout currency pair for Visa Direct for Account and Visa Direct for Wallet only.
5. Response data includes:
This functionality permits a client or sender to execute several actions, including the cancellation of Account or Wallet transactions, OCT adjustments, AFT reversals, and AFT adjustments. It's important to note that Account and Wallet transactions are eligible for cancellation only when they are in a state that allows for such action.
For Account and Wallet transactions, an Originating Entity may request to cancel a transaction in scenarios where the Sender sent to an incorrect Recipient or sent the wrong amount in the payout instructions or sent a duplicate payout in error. The request to cancel a transaction is 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.
Flow diagram:
Visa Direct for Account and Wallet:
Cancel payout by providing payout method and Visa-provided payout ID or client reference ID
Response data includes
Card:
Reverse an AFT by providing payout method and Visa-provided payout ID or client reference ID
Response data includes:
The Query Payout API is designed to provide originators with comprehensive details regarding transactions. By utilizing a unique identifier, users can efficiently search for specific payments, access payment data, and receive updates on payment status.
This functionality ensures that originators have all the necessary information at their fingertips to manage and track transactions effectively. The Query Payout API is especially beneficial during timeout situations or in instances where transaction notifications fail to come through.
Flow diagram:
The Payout Status Notification API is designed with the specific purpose of enabling Visa to communicate updates regarding the status of payout transactions to either the Sender’s financial institution or the Recipient’s financial institution.
This means that whenever there is a change in the status of a payout transaction, a notification is sent to keep the relevant parties informed about the current state of the transaction.
The originator will be notified of status changes of a payout transaction along with the updated expected posting date. The originator should implement to accept this call back request when the status is changed.
Flow diagram:
Visa Direct for Account and Visa Direct for Wallet only
The Payout Return Notification feature is designed to empower the Originating Entity by providing them with the capability to receive timely updates regarding any returns related to their payout transactions.
This API ensures that the Originating Entity stays informed about the status of their payouts, enhancing their ability to manage and reconcile financial transactions efficiently.
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.
Flow diagram:
Step Description:
1. When Visa receives a returned payout from its Network Partner or Wallet Aggregator, it 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.
Below is a listing of fields included in notifications when Visa or a Network / Wallet partner rejects a payment or if the payment is returned by the Recipient’s bank or wallet provider:
The Ledger Notification API is designed to provide detailed information regarding various ledger entries. These entries are specifically related to movements of funds in a Virtual Account (VAN) that occur outside of standard transactions.
The primary function of this API is to ensure that users are informed about any financial activity, such as deposits or withdrawals, that affects their Virtual Account, even when these movements are not linked to a direct transaction.
This API provides information on all debits and credits recorded in an Originating Entity's settlement account with Visa for a specific processing day. It includes notifications for credit and debit changes related to the following types of transactions:
Flow diagram:
Scenarios that trigger the notification:
Visa Direct for Account and Visa Direct for Wallet only
The Account Balance Notification API is designed to provide data on the balance of Virtual Accounts (VANs). This data is generated based on the specific configurations and usage patterns set by the client, ensuring that the information is tailored to their unique requirements.
Flow diagram:
Events that trigger the notification are:
List of fields in notification:
The FX API provides Visa rates for global currencies.
For information about the FX API, see https://developer.visa.com/capabilities/foreign_exchange.
Visa Direct Connect requires the Visa Direct Client’s profile to be setup before accessing the APIs. Clients should provide the information for the profile setup to their implementation manager.
The requirements may vary by origination or recipient markets. Contact your Visa representative to decide on the best Visa Direct Connect profile setup.
Clients who want to review the Visa Direct Connect API specifications to help with solution design can use the Swagger file. Contact your Visa representative for the Swagger file. The spec is Open API 3.0 compliant. It can be opened in any of the widely used Open API editors (for example: https://editor.swagger.io/).
Visa Direct reserves the right not to process a Payout Request or act on any instruction of the client at its discretion for whatever reason, including, without limitation, if the Payout Request does not comply with Visa’s policies or risk appetite, applicable laws, for operational reasons, or where a Downstream Actor will not process it.
Originating Entities must use a Visa-generated identifier (InitiatingPartyID) in the Visa Direct Connect Payout Request. The InitiatingPartyID is used to identify the entity who initially requested to move the funds. The InitiatingPartyID from the original Payout Request message must be included in any subsequent messages, including reversals, exception process requests and responses.
For Visa Direct for Account or Visa Direct for Wallet implementation with Visa Direct Connect, clients will get one Initiating Party ID unique to each program.
Originating Entities, Acquirers, Merchants and Service Providers must collect and send specific information about the Sender and the Recipient in the Payouts Requests. The Visa Direct Connect message requirements for Sender and Recipient data can change depending on:
1. Reach (Domestic or Cross-border)
2. Sender and Recipient market
3. Business Application Identifier
4. Transaction type (Payouts or Funding transactions)
5. Recipient payment instrument (eligible account, wallet or card)
Once the transaction is routed by Visa Direct Connect to the Visa Direct for Account, Visa Direct for Wallet or Visa Direct for Card processing systems, there is no change to how transactions are processed.
Originating Entities, Acquirers, Merchants and Service Providers must comply with the following:
These requirements are periodically reviewed, and Visa reserves the right to make changes to the required data elements to meet local requirements in destination countries.
Currency conversion is required when a client submits a Payout Request in a currency that is different from the Recipient’s currency.
Clients need to use Foreign Exchange Rate API to take advantage of the FX services offered by Visa Direct. To find out more about the API, see the API spec on the Visa Developer Center.
Clients need to know if the Visa card account provided by the cardholder is valid before making services available to that cardholder. Examples include validating a Sender and/or Recipient card credential before initiating a money transfer between them or validating the card credential before using it to top up a digial wallet or saving the card on file.
The ability to validate an account increases the probability of a sucessful, seamless transaction flow. Clients can use the Visa Direct Connect Validate API for Card validation use cases.
Clients can access general and specific attributes of a Visa card account that is required from a payment account, as part of a funds transfer via the Visa Direct Connect Validate Payout API.