How to Use Visa Direct Connect

Visa Direct Connect offers a suite of user-friendly APIs designed to facilitate the transfer of funds using networks 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:  

Get Account Balance API

  • Get Account Balance for Account: Available to Visa Direct for Account. Retrieves currency balances in available chosen settlement currency.
  • Get Account Balance for Wallet: Available to Visa Direct for Wallet. Retrieve currency balances in available chosen settlement currency.  
  • Get Account Balance for Visa B2B Connect: Applicable to Visa B2B Connect. Retrieve currency balances in available chosen settlement currency.  

Get Payout Metadata API

  • Get Payout Metadata for Account: 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.

Foreign Exchange API

  • Get Foreign Exchange: Rate Generate a quote detailing the source and target currencies, as well as the transfer amount.

Manage Liquidity API 

  • Create Quote: This API allows clients access to the Managed Liquidity service via APIs to request the FX quotes
  • Lock Quote: This API allows clients access to the Managed Liquidity service via APIs to lock in FX quotes

Validate API

  • Validate Payout to Account: Validate payload prior to submitting the actual payout request for processing through Visa Direct for Account and Visa B2B Connect
  • Validate Payout to Wallet: Validate payload prior to submitting the actual payout request for processing through Visa Direct for Wallet. 

Verify API

  • Verify API with Visa Direct for Card: allows an Acquirer, Merchant or Service Provider to validate the transaction, helping increase the probability of a successful payout and allowing for a more seamless transaction flow
  • Verify API with Visa Direct for Account lets clients confirm account recipient details before submitting a payout request.
  • Verify API with Visa Direct for Wallet lets clients confirm wallet recipient details before submitting a payout request.

Eligibility API

  • Eligibility checks with Visa Direct for Card enables validation of transactions by Originating Entities, Acquirers, Merchants, or Service Providers to help ensure successful payouts and smoother transactions.

Payout API

  • Payout to Visa Direct for Account initiates a payout request through Visa Direct for Account and Visa B2B Connect. 
  • Payout to Visa Direct for Wallet initiates a payout request through Visa Direct for Wallet. 
  • Payout to Visa Direct for Card initiates a payout request through Visa Direct for Card. 

Payin API

  • Payin API for Visa Direct for Card is used to pull funds from the sender's Visa account (in preparation for pushing funds to a recipient's account) in an Account Funding Transaction (AFT).

Transaction Management API

  • Query Payout to Visa Direct for Account provides originators with comprehensive details regarding transactions through Visa Direct for Account and Visa B2B Connect. 
  • Query Payout to Visa Direct for Wallet provides originators with comprehensive details regarding transactions through Visa Direct for Wallet. 
  • Query Payout to Card: Provide originators with comprehensive details regarding transactions through Visa Direct for Card. 

Exception Management API

  • Cancel payout to Visa Direct for Account allows Originators to cancel a payment if in a cancellable state
  • Cancel payout to Visa Direct for Wallet allows Originators to cancel a payment if in a cancellable state
  • Request Exception is used with Visa Direct for Card and Visa B2B Connect to reverse a card transaction and manage a Visa B2B Connect transaction by executing actions such as recall, responding to recall requests, rejections, and credit confirmations.
  • AFT Adjustment: The AFT Adjustment API allows the sender to correct the amount of a previously completed Account Funding Transaction (AFT).

Notifications API

  • Payout Status Notification: Available for Visa Direct for Account, Visa Direct for Wallet and Visa B2B Connect. This API enables Visa to provide payout status updates.
  • Payout Return Notification API: Available for Visa Direct for Account, Visa Direct for Wallet and Visa B2B Connect. This allows originators to receive notifications about returns associated with their payouts.
  • Ledger Notification API: Available for Visa Direct for Account, Visa Direct for Wallet and Visa B2B Connect. This API allows originators to receive notifications about funding, journal, and repatriations.
  • Balance Notification API: Available for Visa Direct for Account and Visa Direct for Wallet. This API allows Originating Entities to view the balance of each currency for their Virtual Account(s).

Get Account Balance API

Available for: Visa Direct for Account, Visa Direct for Wallet and Visa B2B Connect

The Get Account Balance API is an optional API specifically designed to enable clients and sending participants to check their current balance in an available chosen settlement currency.

 

A diagram of a visa direct

AI-generated content may be incorrect., Picture

A diagram of a wallet

AI-generated content may be incorrect., Picture

 A diagram of a company's account

AI-generated content may be incorrect., Picture

The Balance Response provides clients and sending participants with a list of balances for all the currencies they may have or has transacted with: 

  • Payout method e.g., ‘B' for Visa Direct for Account, 'W' for Visa Direct for Wallet, or 'E' for Visa B2B Connect
  • Account Id, a Visa-assigned identifier for the ledger account
  • Balance date/time stamp 
  • Available balance amount
  • All by currency code

Get Payout Metadata API

Available for: Visa Direct for Account

Enables clients to automate manual processes related to route requirements. The API will return all the required, conditional, and recommended fields to send payment. For more information regarding the Get Payout Metadata API, click here.

The API communicates using files written in JSON format. This requires the client to have the ability to open and read JSON files to extract the critical information such as rules, conditions and schemas. Clients store the data required to send a payment to a specific country in a local repository, which powers the client-facing user interface.

  • Client initiates a Get Payout Metadata API request when a new route is accessed or when they are notified about an update to an existing route 
  • Visa responds back with the Get Payout Metadata API response
  • Client stores Get Payout Metadata API response in a local repository
  • Client builds UI based on data stored in the local repository

Foreign Exchange Rates API

Available for: Visa Direct for Account, Visa Direct for Card, Visa Direct for Wallet and Visa B2B Connect

Visa provides daily foreign exchange (FX) rates for global currencies to authorize and settle transactions. 

The Foreign Exchange Rates API and Get the Effective Conversion Rate API provide 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. This 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 foreign exchange rates, see: Foreign Exchange Overview (visa.com)  and Get the Effective Conversion Rate.

 

Validate Payout API

Available for Visa Direct for Account, Visa Direct for Wallet, Visa B2B Connect

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 step can improve the chances of a successful transaction by identifying and resolving potential issues early in the process. Consequently, this can provide a smooth and efficient transaction flow, benefiting both the originator and the end recipient.  

 

 

A diagram of a visa direct

AI-generated content may be incorrect., Picture

A close-up of a visa direct application

AI-generated content may be incorrect., Picture

 A diagram of a visa direct application

AI-generated content may be incorrect., Picture

 

The Validation Response indicates if the payout request is:

  • Valid or Invalid
  • 'In-Network' or 'Out-of-Network' (only applicable for Visa B2B Connect)
  • Contains errors,  including, error code, error description and location 

Send Payout API

Available for all products

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, digital wallets and B2B connect.  

Originating entities can assign their own unique identifiers, such as a Client Reference ID and end-to-end IDs, to help streamline the process. 

A diagram of a visa direct payment

AI-generated content may be incorrect., Picture

A diagram of a visa direct

AI-generated content may be incorrect., Picture

A close-up of a visa direct application

AI-generated content may be incorrect., Picture

 A diagram of a visa direct

AI-generated content may be incorrect., Picture

 

Response data includes: 

  • Visa’s generated Payout Id
  • Transaction amount and currency
  • Settlement amount and currency
  • Destination amount and currency
  • Status
  • FX conversion rate
  • Expected posting date

Payin API

Available for Visa Direct for Card only

This API can pull funds from the sender's Visa account (in preparation for pushing funds to a recipient's account) in an Account Funding Transaction (AFT).

Eligibility API

Available for Visa Direct for Card

Allows an Originating Entity, Acquirer, Merchant or Service Provider to validate the transaction, helping increase the probability of a successful payout and allowing for a more seamless transaction flow.

Allows an Acquirer, Merchant or Service Provider to verification for the following Card use cases:

  • Eligibility data (Ex: Fast Funds, Cross Border OCT, Billing currency etc.)

Query Payout API

Available for all products

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. 

 

 

A diagram of a visa direct

AI-generated content may be incorrect., Picture

A screen shot of a computer

AI-generated content may be incorrect., Picture

A diagram of a visa direct

AI-generated content may be incorrect., Picture

 A diagram of a visa direct

AI-generated content may be incorrect., Picture

  • Search for payments by payout method and Visa-provided payout ID or client reference ID 
  • Used by certain originators to check payment status
  • Alternative to Payment Status Callback API 
  • Response data includes the full transaction details with status

 

Cancel Payout API

Available for Visa Direct for Account and Visa Direct for Wallet only

This functionality enables an originating entity to cancel a transaction in scenarios such as the sender requested payment to the wrong recipient, sent an incorrect 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 the network partner or wallet aggregator. If Visa has accepted the cancel request, then it will initiate a Return Notification transaction to the originating entity. 

Cancellation is only enabled when the transaction is at a specific phase. See the Visa Direct Account and Wallet Program Guide for more information.  

A diagram of a visa direct

AI-generated content may be incorrect., Picture

A diagram of a visa direct

AI-generated content may be incorrect., Picture

 

Response data includes:

  • PENDING_CANCELLATION: Cancel payout request is pending before cancellation.
  • CANCELLED: A transaction has been successfully cancelled in PAYOUT_RECEIVED or PENDING status.

Request Exception API

Available for Visa B2B Connect only

This functionality enables an originating entity to cancel a transaction in scenarios such as the sender requested payment to the wrong recipient, sent an incorrect 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 the network partner or wallet aggregator. If Visa has accepted the cancel request, then it will initiate a Return Notification transaction to the originating entity. 

Cancellation is only enabled when the transaction is at a specific phase. See the Visa Direct Account and Wallet Program Guide for more information.  

 

 

AFT Reversal API

Available for Visa Direct for Card only

The AFT Reversal API is designed to reverse an Account Funding Transaction (AFT) that pulled funds from an eligible Visa card. The AFT is a pull transaction which may need to be reversed at times. This could be because the originator has made an error or user cancellation.

AFT Adjustment API

Available for Visa Direct for Card only

The AFT Adjustment API allows the sender to correct the amount of a previously completed Account Funding Transaction (AFT). For example, the sender can increase or decrease the amount after it has been processed. This is different from AFT Reversal. The AFT Adjustment API changes the transaction value, typically due to sender errors, disputes, or post-settlement corrections.

Payout Status Notification API

Available for Visa Direct for Account, Visa Direct for Wallet and Visa B2B Connect

The Payout Return Notification feature is designed to empower originators by providing them with the capability to receive timely updates regarding any returns or rejections related to their payout transactions.  

This API ensures that an originator stays informed about the status of their payouts, enhancing their ability to manage and reconcile financial transactions efficiently. 

For Visa Direct for Account and Wallet, payouts sent to a bank account or wallet may get returned for various reasons. This includes:

  • If the bank account or wallet details provided are not accurate
  • The account or wallet is not active
  • The payout was cancelled by the originating entity

The originating entity will receive notifications from Visa with details of the payout. 

For Visa B2B Connect, payments may be rejected by the receiving financial institution/receiving participant. Additionally, a recall may be accepted by the recipient financial institution.

A diagram of a visa direct application

AI-generated content may be incorrect., Picture

A diagram of a visa direct

AI-generated content may be incorrect., Picture

 A diagram of a visa direct

AI-generated content may be incorrect., Picture

Payout Return Notification API

Available for Visa Direct for Account, Visa Direct for Wallet and Visa B2B Connect

The Payout Return Notification feature is designed to empower originators by providing them with the capability to receive timely updates regarding any returns or rejections related to their payout transactions.  

This API ensures that an originator stays informed about the status of their payouts, enhancing their ability to manage and reconcile financial transactions efficiently. 

For Visa Direct for Account and Wallet, payouts sent to a bank account or wallet may get returned for various reasons. This includes:

  • If the bank account or wallet details provided are not accurate
  • The account or wallet is not active
  • The payout was cancelled by the originating entity

The originating entity will receive notifications from Visa with details of the payout. 

For Visa B2B Connect, payments may be rejected by the receiving financial institution/receiving participant. Additionally, a recall may be accepted by the recipient financial institution.

 

A close-up of a visa direct application

AI-generated content may be incorrect., Picture

A diagram of a visa direct

AI-generated content may be incorrect., Picture

 A screen shot of a computer

AI-generated content may be incorrect., Picture
Description:

1. When Visa Direct receives a returned payout from its network partner or wallet aggregator/originator, it will initiate a return through an API, with the transaction identifiers of the original payout and the reason for the return.  

2. Visa Direct notifies the originating entity/sending participant through the Return Notification API, providing all the details of the returned payout. 

3. The originating entity/sending participant 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 partner or wallet partner rejects a payment or if the payment is returned by the recipient’s/beneficiary's bank or wallet provider:

  • Return Payout ID 
  • Initiating Party ID
  • Original Payout ID 
  • Client Reference ID
  • End To End ID 
  • Return Source Amount
  • Return Source Currency Code 
  • Return Amount
  • Return Currency Code 
  • Return Conversion Rate
  • Return Date Time 
  • Return Reason Details
  • status: "REJECTED” or “RETURNED” 

Account Balance Notification API

Avialible for Visa Direct for Account and Visa Direct for Wallet

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.

A close-up of a screen

AI-generated content may be incorrect., Picture

A close-up of a visa direct application

AI-generated content may be incorrect., Picture 

Events that trigger the notification are:

  • When account balance in a particular currency falls below a configured threshold
  • When account balance falls below zero, leading to transactions being held due to a lack of funds in the required currency
  • Periodic account balance updates which are configurable per VAN

List of fields in notification:

  • Account Id
  • Initiating Party Id
  • Event Type – THRESHOLD or LIQUIDITY_FAILURE or PERIODIC
  • Balance
  • Currency Code
  • Amount

Ledger Notification API

Available for Visa Direct for Account, Visa Direct for Wallet and Visa B2B Connect

For Visa Direct for Account and/or Wallet, 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. This ensures 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 originator'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:

  • Funding - Represents the deposit of the originator's funds into Visa's bank account, which credits the originator's account.
  • Repatriation - The transfer of funds by Visa from the originator's account to their bank account, based on predetermined Standing Settlement Instructions (SSIs). 
  • Journal - An adjustment entry for a debit or credit to the originator's account made by Visa, necessary for correcting balances.

For Visa B2B Connect, the Ledger Notification API is designed to provide real-time notifications and confirmations related to credits made to a network balance. This API helps participants manage and track the status of participant funding that is posted to a balance. This API integrates seamlessly with the Visa B2B Connect platform, using existing infrastructure and capabilities to ensure secure and efficient transaction processing.  

When a credit is initiated, the API sends a notification to the relevant participants, which includes transaction details such as the amount, the involved parties, and the status of the transaction.

 

 

A close-up of a visa direct

AI-generated content may be incorrect., Picture

A diagram of a visa direct

AI-generated content may be incorrect., Picture 

 A close-up of a visa direct application

AI-generated content may be incorrect., Picture

 

Receive Payout Notification API

Available for: Visa B2B Connect

The Receive Payout Notification API enables receiving financial institution/receiving participant to receives a notification indicating that a payment is being routed to them. The receiving financial institution/receiving participant reviews the payout details. If there are any issues, such as the beneficiary’s account being closed, they can reject the payout request. When rejecting a request, an action reason code and additional details explaining the reason for rejection must be provided. If the receiving financial institution/receiving participant accepts the payout notification, the transaction proceeds, and the funds are credited to the beneficiary’s account. The receiving financial institution/receiving participant can send a confirmation via the API to notify that the funds have been successfully credited to the   beneficiary’s account.

 

 

A close-up of a visa direct

AI-generated content may be incorrect., Picture

A close-up of a visa direct

AI-generated content may be incorrect., Picture

 

Verify API

Available for Visa Direct for Card only

Verify API allows an Acquirer, Merchant or Service Provider to validate the transaction, increasing the probability of a successful payout and ensuring a seamless transaction flow.

For Visa Direct for Card, it allows an Acquirer, Merchant or Service Provider to verification for following Card use cases

  • Account Verification
  • Address Verification 
  • Account Name Inquiry
  • CVV2 check

A diagram of a visa direct

AI-generated content may be incorrect., Picture

 

 

A diagram of a visa direct

AI-generated content may be incorrect., Picture

 

A diagram of a visa direct

AI-generated content may be incorrect., Picture

Additional APIs

FX API

The FX API provides Visa rates for global currencies.

For information about the FX API, see https://developer.visa.com/capabilities/foreign_exchange.

Client Profile Setup

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.

 

Accessing the API Spec

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/). 

 

Right not to process

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 Entity Identifiers

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. 

 

Sender and Recipient Data

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:

  • Visa Direct Connect API Specifications as set out on the Visa Developer Center, which has a comprehensive list of data elements and integration options.
  • Visa Direct Account Endpoint Guide and Visa Direct Wallet Endpoint Guide, which contain information about availability and requirements for each recipient market for account and wallet use cases.
  • Visa Direct Original Credit Transaction (OCT)—Global Implementation Guide and Visa Account Funding Transaction (AFT) Processing Guide which contain comprehensive list of field and data requirements for card use cases.

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

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.

 

Payment Account Validation - Visa Direct for Card

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

 

Eligibility Check - Visa Direct for Card

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.