The Funds Transfer API contains six operations that all have a similar structure: pull funds from a single Visa account, pull funds from multiple Visa accounts, push funds to a single Visa account, push funds to multiple Visa accounts, return funds to a single Visa account, and return funds to multiple Visa accounts. You can find the technical specifications for each operation on the API Reference tab.
A basic person-to-person funds transfer service using Visa Direct includes a “Pull” and “Push” operation using the Funds Transfer API.
The first step is to collect funds from the sender. As an Originator, you can obtain funds from the sender using any means available to you, such as by withdrawing funds from the sender’s bank account or by pulling funds from the sender’s Visa card. If the source of funds is a Visa card, you can use the Funds Transfer API to obtain them. The Funds Transfer API does this by submitting an Account Funding Transaction (AFT) into the Visa network.
Once you have obtained funds from the sender using the Funds Transfer API or through other means, the next step is to push those funds to the recipient’s Visa account. There are two operations on the Funds Transfer API that you can use to push them. The Funds Transfer API includes an operation for pushing funds to a single Visa account (PushFunds) and an operation for pushing funds to multiple Visa accounts simultaneously (MultiPushFunds). These operations on the Funds Transfer API do this by submitting Original Credit Transactions (OCT) into the Visa network.
If the push payment is part of a Funds Disbursement service, only the push part of the funds transfer transaction is needed. The money to fund the disbursement is usually pulled from the sender’s bank account and settled outside of the Visa network.
Sometimes a push payment fails, usually because the push payment was declined by the receiving issuer. In that case, if the source of funds was a pull from a Visa card using the Funds Transfer API, then you must return the funds to the sender’s account the same way. If the sender’s funds were obtained from another source, you are responsible for returning them to the sender using other means.
The request payloads of the six operations differ somewhat due to the different functionality they deliver, but all of them generally require this type of information in the POST request:
You can find the technical specifications of each operation on the API Reference link. All of these operations generally return these same fields in the response:
The Funds Transfer API also supports the Visa Push Payments Gateway Service (PPGS) which allows originators to send PullFundsTransactions (AFTs) and PushFundsTransactions (OCTs) to multiple U.S. debit networks. Visa PPGS offers clients the following benefits:
The following fields, in addition to the ones supported for Visa Direct transactions destined to Visa accounts, are required to send PullFundsTransactions (AFTs) and Push FundsTransactions (OCTs) to the debit networks:
For additional information, contact your Visa account representative.
The Funds Transfer API enables Originators to use an API to withdraw (debit) funds from an eligible Visa card by directly submitting an Account Funding Transaction (AFT) into the Visa network. The AFT is used to pull funds from Visa accounts for the purposes of funding other non-merchant accounts, such as loading or topping up prepaid card accounts, moving funds into another financial account such as a Certificate of Deposit or Individual Retirement Account, acting as the funding source of person-to-person payments, or to load a third-party digital wallet.
Once you have collected the necessary information from the sender, you can submit a pull funds transaction to Visa using either the PullFunds operation (for a single account) or the MultiPullFunds operation (for multiple accounts simultaneously). In a PullFunds operation, the request message includes the sender account, amount, and applicable point of service data elements for a single account. The PullFunds operation submits a single AFT transaction into Visa for the account specified in the request and returns the response variables for that account. A successful response message will include status information, a Visa-assigned transaction ID, and various approval codes.
In the MultiPullFunds operation, the sender account, amount, and point of service data elements are repeated in the request message for each account from which funds are to be pulled. The MultiPullFunds operation is most typically used when you have accumulated a “batch” of pull funds transactions and it is more convenient to submit them all in a single API call. A maximum of 499 sender accounts can be included in a single MultiPullFunds request. The MultiPullFunds operation will submit an individual AFT transaction into Visa for each account specified in the request and return a separate response for each one.
Because it may take more time to process a pull request that contains many accounts, a successful MultiPullFunds POST request returns a unique Status Identifier instead of individual account details. To retrieve the status and details for the accounts in the original request, submit a MultiPullFunds GET request using the Status Identifier from the POST response in the link header, which will then return status and details for each account in the original request.
You can find the technical specifications for both the PullFunds and MultiPullFunds operations on the API Reference link. Any pull funds transaction generally requires the following types of information in the request message:
You should log or otherwise retain all of the information returned in the PullFunds or MultiPullFunds response. If you must return funds to the sender for any reason, you may need to include several of the response values in a ReverseFunds or MultiReverseFunds request.
The Funds Transfer API enables Originators to use an API to send (credit) funds to an eligible Visa card by directly submitting an Original Credit Transaction (OCT) into the Visa network. The OCT is used to push funds to Visa accounts to enable services such as person-to-person money transfers, funds disbursements, prepaid loads, and credit card bill payments.
Once you have collected funds from the sender, you can submit a push payment transaction to Visa using either the PushFunds operation (for a single account) or the MultiPushFunds operation (for multiple accounts simultaneously). In a PushFunds operation, the request message includes sender information, recipient information, and transaction amount data elements for a single account. The specific data elements required in the request may vary depending on the use case and local regulation. Refer to the technical specifications in the API Reference link and the local regulations that apply. The PushFunds operation submits a single OCT transaction into Visa for the recipient account specified in the request and returns the response variables for that account.
In the MultiPushFunds operation, the sender information, recipient information, and transaction amount data elements are repeated in the request message for each account to which funds are to be pushed. The MultiPushFunds operation is most typically used when you have accumulated a “batch” of push funds transactions and it is more convenient to submit them all in a single API call. A maximum of 499 recipient accounts can be included in a single MultiPushFunds request. The MultiPushFunds operation will submit an individual OCT transaction into Visa for each account specified in the request and return a separate response for each one.
Because it may take more time to process a push request that contains many accounts, a successful MultiPushFunds POST request returns a unique Status Identifier instead of account details. To retrieve the status and details for the accounts in the original request, submit a MultiPushFunds GET request using the Status Identifier from the POST response in the link header, which will then return status and details for each account in the original request.
You can find the technical specifications for both the PushFunds and MultiPushFunds operations on the API Reference link. Any push payment request generally requires the following types of information in the request message:
As part of a push payment service, you may want to inform the sender or the recipient about when to expect the funds to become available. For a conventional push payment, the recipient issuer must make the funds available in the recipient account as soon as possible but no later than two business days. Many issuers now participate, or are mandated to participate, in Fast Funds, which means that they agree to make funds available in the recipient account within 30 minutes of approving the push payment authorization. You can use the Funds Transfer Attributes Inquiry API to determine if the recipient issuer participates in Fast Funds.
A common requirement of person-to-person payments and other push payment use cases is the need to restrict transfers to a limited number of geographies, either due to business considerations or to local law and compliance requirements. For a domestic funds transfer program, this could mean restricting push payments to intra-country recipients. For a cross-border remittance program, this could mean restricting push payments to a selected group of destination countries.
Traditionally, Originators had to implement the functionality within their own systems to maintain a list of prohibited or permitted countries, pre-validate the country of the recipient account, and then submit or block the transaction as needed.
Visa has optional functionality in the Funds Transfer API that allows Originators to configure geographic restrictions within Visa Direct during production onboarding so that they can be automatically enforced by Visa. If you choose this option, Visa will automatically apply your pre-configured geographic rules to every Funds Transfer API request and will block any push funds transaction to a card issued in a country that is restricted based on your configuration rules. Contact email@example.com for more information.
Foreign Exchange (FX) Markup
Many Originators want to incorporate a foreign exchange markup on cross-border money transfers as an additional source of revenue. Traditionally, Originators had to maintain their own lists of reference rates, look up the currency of the recipient account and applicable reference rates for each transaction, and apply the markup on top of the reference rate in order to determine what rate to use for each individual transaction. For Originators who operate in many markets, this can be a complex and costly process.
Visa has optional functionality that allows Originators to configure either a single standard FX markup rate to be applied to all transactions or separate FX markup rates for specific currency pairs. If you choose this option during production onboarding, when you use the Foreign Exchange Rates API to determine the transaction amount in recipient currency, Visa will automatically apply your preconfigured markup rate for the currency pair when converting the source amount into destination currency. The Foreign Exchange Rates API will return Visa's daily base rate, the actual conversion rate used (base rate plus markup), and the recipient transaction amount. Review the Foreign Exchange Rates API for more details or contact firstname.lastname@example.org for more information.
The Funds Transfer API enables Originators to use an API to return (credit back) funds to a Visa card from which funds were withdrawn earlier using a Funds Transfer API pull funds operation. If a push payment fails to complete, you must reverse the original pull funds transaction by using either the ReverseFunds operation (for a single account) or the MultiReverseFunds operation (for multiple accounts simultaneously).
In a ReverseFunds operation, the request message includes the sender account, amount, and applicable point of service data elements for a single account to which funds are to be returned. The ReverseFunds operation submits a single AFT reversal transaction into Visa for the account specified in the request and returns the response variables for that account.
In the MultiReverseFunds operation, the sender account, amount, and point of service data elements are repeated in the request message for each account to which funds must be returned. The MultiReverseFunds operation is most typically used when you have accumulated a “batch” of reversal transactions and it is more convenient to submit them all in a single API call. The MultiReverseFunds operation will submit an individual AFT reversal transaction into Visa for each account specified in the request and return a separate response for each one.
Because it may take more time to process a reversal request that contains many accounts, a successful MultiReverseFunds POST request returns a unique Status Identifier instead of account details. To retrieve the status and details for the accounts in the original request, submit a MultiReverseFunds GET request using the Status Identifier from the POST response in the link header, which will return status and details for each account in the original request.
You can find the technical specifications for both the ReverseFunds and MultiReverseFunds operations on the API Reference link. Any reverse funds request generally requires the following type of information in the request message:
If a MultiPushFunds operation was used to push funds to a batch of Visa accounts, remember that the response message will contain a separate results status for each account number submitted. Since each account is processed individually by Visa, some push funds requests within a MultiPushFunds operation may have succeeded and others may have failed. Before submitting either a ReverseFunds or MultiReverseFunds operation request, you must individually assess the results status of each account and only send reversal requests for those accounts with failed push payment authorizations.
Mobile Push Payment is a simple, secure, and fast way to pay and be paid using mobile phones (both smart phones and feature phones) that rides the rails of the Visa Direct APIs. Mobile Push Payment opens a new channel to access the Visa network by combining the power of ubiquitous mobile connected devices with lower risk push payments as the underlying transaction. Mobile Push Payment is delivered by a unique packaging of the Funds Transfer API that has been optimized to serve markets where traditional merchant acceptance is poor and a low cost, lower risk payment acceptance capability is needed.
How QR Works
The consumer initiates a payment by scanning a QR code at the merchant site, tapping an NFC device, or key entering the merchant and transaction details into their Mobile Push Payment-enabled feature phone or Mobile Push Payment smart phone application. The consumer's issuer then uses the Mobile Push Payment API to submit a push payment transaction into Visa that will transfer the payment amount from the consumer's Visa card to the merchant's Visa card. When the push payment is received by the merchant's issuer (acquirer), the merchant is notified that the amount of the payment has been deposited into their Visa account. When the merchant issuer sends the approved authorization for the push payment back to Visa, the consumer's issuer notifies them via the Mobile Push Payment application that the transaction is complete.
The Mobile Push Payment API includes several additional fields that are not used for Funds Transfer API and (depending on the use case) excludes some fields that are normally present in a Funds Transfer API. You can find the technical specifications for the Mobile Push Payment API on the API Reference link.
Mobile Push Payment applications typically support one or more of four basic use cases: person-to-person transfers, payments to merchants, cash in (deposit to a Visa card via an agent), and cash out (withdrawal from a Visa card via an agent). For person-to-person transfers, you should use the standard Funds Transfer API push payment operations. For merchant payments, cash in, and cash out, you should use the Mobile Push Payment API.
The Mobile Push Payment SDKs provide the software library that you can embed within your mobile app to pay and be paid using mobile phones. The mobile SDK contains a unified overall Mobile Push Payment experience (with limited customization) that enables Mobile Push Payment transactions, such as peer-to-peer money transfer, cash withdrawal and merchant payments. Each library launches a specific sequence of user interface and interaction required to complete the Mobile Push Payment transaction.
The Mobile Push Payment SDKs are available for use by Issuers and Acquirers.
You can view and download all Visa Direct assets, such as SDKs from the Visa Developer Project Dashboard. Please refer to Access Assets for more details.
Alias is typcially a known identifier such as mobile number and email address, or a user-defined identifier like nickname created by a consumer to receive payment. Using Alias for payment is intuitive, easy and avoiding sharing senstive information such as PAN when initiating a payment. Two types of Alias-to-PAN mapping are currently supported:
Visa currenlty provides the following two key capabilities to support alias:
Creating and maintaining the mapping of an alias to a PAN. Issuers create and maintain consumer Alias-to-PAN mapping while Acquirers create and maintain merchant Alias-to-PAN mapping. Two sets of lifecycle mangaement APIs, one supports consumer aliases and the other supports merchant aliases, allow clients connect to the Alias Directory in real time to create, update, delete or get data of an Alias-to-PAN mapping via API. Alternatively, clients can opt to use batch file processing via Visa Online (VOL). To ensure security of uploading batch file with aliases via VOL, Visa provides a unique shared secret key (256-bit key length) to clients during onboarding. Clients are required to encrypt the batch file using AES-CBC Cipher Algorithm with the 256-bit shared secret key and an initializaiton vector (IV) that can be either from Visa via VOL or own generation. The IV is a 32-byte hexadecimal string (i.e. characters 0-9, a-f, A-F) .
Resolving an alias to the mapped PAN. Clients connect to the directory in real time to resolve the alias to obtain the mapped PAN in the directory for payment.
Note: This service is available only in selected countries, please contact your Visa Representative for more information.
The Watch List Screening API accepts the name, city, and country of a person and returns a score that indicates how closely that person's information matches to any entries on the regulatory watch lists supported by the API. Currently, the API only screens against the United States Office of Foreign Assets Control (OFAC) Specially-Designated Nationals (SDN) sanctions list.
For cross-border person-to-person money transfers, you may or, in some cases, must screen sender information against national or international watch (or sanctions) lists before allowing your customer to send money to another Visa cardholder. Depending on the nature of the services your project provides, there may be other situations in which it may be prudent to prescreen customer information before delivering services.
To use the Watch List Screening API, you must provide the following information in the request about the person being screened:
The API uses a “Fuzzy Match” algorithm to assess how closely the person’s information matches entries in the regulatory watch list. The algorithm produces a match score between 000 (low likelihood of a match) and 100 (high likelihood of a match). The response message includes both the match score and a Status field. The value “Not Approved” in the Status field indicates that Visa would likely decline a push payment transaction involving the person whose name was provided in the request.
For tracking purposes, if you will be using the Watch List Screening API in conjunction with calls to the Funds Transfer API, please populate the following optional fields in the request message (Acquiring BIN and Acquirer Country Code) with the corresponding values that you plan to use in the Funds Transfer calls. Otherwise, you may exclude all of those fields from the request.
Note that Visa also automatically watch list screens all cross-border person-to-person money transfer OCTs intended for delivery to a recipient Visa account in all countries where screening of inbound transactions is required. In that case, Visa provides the watch list match score to the recipient issuer in the OCT transaction.
The Watch List Screening API is provided as a service to developers and is available to all developers in both sandbox and production. Using it does not relieve you of any obligations you may have to comply with applicable law and regulations. Visa makes no representations or warranties with respect to the Watch List Screening API or its results nor shall Visa have any liability whatsoever for the scoring results or the Watch List Screening API. Visa retains the right to review your project's implementation of this API prior to production onboarding to ensure appropriate use of its features.
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.
The Payment Account Validation API provides several means for you to determine if a particular Visa account is valid and in good standing. Visa recommends that you use this API to validate the sender's account information before invoking a PullFunds or MultiPullFunds API call.
The Payment Account Attributes Inquiry service includes two APIs (the General Attributes Inquiry and the Funds Transfer Attributes Inquiry) that enable you to look up important attributes of a Visa account that you may need in order to successfully implement a funds transfer project. In particular, you may need to know the type of account, what the billing currency is, who the issuer is and in what country, whether the recipient issuer is able to receive push payments or participates in Fast Funds, or whether the account is blocked from receiving certain types of push payments.
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.
Customer Disclosure Requirements. Originators must provide the Terms and Conditions for their program to the customer and the customer must accept them before using any Visa Direct-based service. You are responsible for updating your Terms and Conditions to include the required disclosures and as required by law and industry practices. Visa strongly recommends that you prompt the sender to agree to the Terms and Conditions prior to initiating any API calls and retain evidence of the customer’s agreement. Visa retains the right to request that you provide copies of your updated Terms and Conditions to confirm that you are complying with these requirements.
Visa also requires you to provide senders with information related to fees and other material terms in connection with their push payments service. A clear itemized description of all Originator-assessed fees, including foreign exchange fees, if applicable, associated with the transaction must be communicated to senders subject to and in accordance with applicable laws and regulations of the area of operation of the Originator. You must provide senders with the opportunity to agree to the fees and proceed with or cancel the transaction.
Visa also requires you to comply with the Visa Core Rules and Visa Product and Service Rules (formerly, the Visa International Operating Regulations) as well as local regulations and laws. You must comply with all applicable sanctions and “Know Your Customer”, anti-money laundering, and anti-terrorist financing laws. If you use a third party agent, the third party agent must follow all Visa Core Rules and Visa Product and Service Rules related to working with such agents.
You are expected to perform the required Know Your Customer (KYC), fraud, and eligibility checks on the sender and/or recipient at the time of transaction. Visa provides some resources to help with that, such as the Watch List Screening and Payment Account Validation APIs, but you should implement the appropriate functionality within your web, mobile, ATM, or branch application.
The Funds Transfer PullFunds operations should not be used to purchase goods and services from a merchant or to transfer funds to a merchant account except as part of an approved Visa Direct program (such as Mobile Push Payment) that permits them. Visa monitors to ensure that PullFunds operations are not used in the place of standard purchase transactions with merchants. As a result, Visa recommends that you capture information from sending cardholders about the purpose of the transaction in order to determine proper use of the Funds Transfer API.
Visa also recommends that you screen transactions for high risk and/or sanctioned transactions and set velocity limits. Although there are no specific limits for Originators, the Visa risk team reviews the limits defined by Originators during the production onboarding process and may ask you to make changes appropriately.
Originators must also ensure that their project handles sender and recipient personal data in compliance with the Payment Card Industry (PCI) Data Security Standards and applicable law. Sender and recipient information must be stored and transmitted securely, with regular reviews of data security policies to ensure that criminals, hackers, or other unauthorized people cannot break into data warehouses or intercept data during transmission.