Docs play_arrow Visa Direct

Visa Direct Documentation

Ready to start coding?

All Visa Direct programs require the originator to be a licensed Visa acquirer or be sponsored by a licensed Visa acquirer who is ready and able to sponsor Visa Direct programs. Please reach out to your Visa account representative to get more information about Visa licensing requirements.

It should also be noted that a Visa Direct program requires the originator to ensure that all stages of transaction processing including transaction submission, financial settlement, dispute management, reporting are in place and effectively managed before launching a Visa Direct program using the APIs. The APIs available on the Visa Developer platform help to manage certain stages of the transaction specifically those related to financial transaction submission. The originator needs to be aware and ensure that the necessary capabilities are in place to support the complete transaction cycle. Only originators who can account for every aspect of the payment stack will be allowed to move their projects into production.

Completion of a Visa Direct Program Implementation Questionnaire has been provided and is meant to aide originators in determining if they are prepared with the necessary elements to offer a full service Visa Direct program and move their project into production. Based on responses to the questionnaire, Visa may be able to provide insight or guidance to finding enabled acquirers and partners that may be able to help move projects and programs into production.

Things To Know

The Visa Direct APIs can be used in the sandbox by any developer. In order to enable transaction processing and settlement through Visa between the sending and receiving financial institutions, all pull and push payments must include an Acquiring BIN. Test Acquiring BINs are provided as part of the sandbox test data. However, in order to use the Visa Direct APIs in production, the Originator must either be a licensed Visa acquirer, or a third party Originator that is being sponsored by a licensed Visa acquirer for a Visa Direct program.

As noted above, there is more to offering a push payment service on the Visa Direct platform than just establishing a relationship with an acquirer. Prior to receiving an approval from Visa to move a project into production, developers will be required to validate their ability to meet all of the requirements of a full push payments processing service – not just be able to successfully process the Visa Direct Funds Transfer API.  

The following table outlines examples of consumer and business services that can be built using the PushFunds operations of the Visa Direct APIs and highlights the accounts that can receive push payments. Coming soon in the U.S., Originators will also be able to use the Funds Transfer API to push funds to select other network-branded cards. Please contact developer@visa.com for further information or to request that Visa review and approve other use cases you may envision for push payments.

  Destination Visa Account Types Geographic Scope
Push Payment Services Visa Credit Visa Debit Visa Prepaid Domestic Cross-Border
P2P Money Transfer
Funds Disbursements
Prepaid Load      
Credit Card Bill Payment      

The Funds Transfer API enables pull and push payments from and to most Visa cards; however, there may be geographical or use case-based restrictions in some countries. For example:

  • The only prepaid card accounts that are permitted to receive funds are reloadable prepaid accounts for which the recipient issuer has “Know Your Customer” or “Customer Identifiable” information on file for the cardholder.
  • Push payments are generally not used for prepaid loads in the U.S. because the U.S. market currently has a separate prepaid load service called Visa ReadyLink.
  • In the U.S., Visa cards can accept all domestic funds transfers, but cannot accept push payments from senders outside the U.S.
  • Because the Account Funding Transaction (AFT) is not supported in many parts of the world, the PullFunds operations and the ReverseFunds operations on the Funds Transfer API may not be valid in certain regions.

Please contact developer@visa.com or your Visa account representative to check on the availability of push payments in specific geographies.

The sandbox currently does not have Visa network connectivity, so validating the receipt of a pull funds, push funds, or reverse funds transfer by an issuer cannot occur in the sandbox.

All Visa Direct projects will go through a review and approval process at Visa. As noted above, the ability to provide all components of a comprehensive push payment service, not just successful testing of the Funds Transfer API, will be assessed to determine approval to move a project into production. Please reach out to your Visa account representative, or complete the Visa Direct Program Implementation Questionnaire early in the process to ensure that your project meets the criteria permitted for a Visa Direct program.

Contact your Visa licensed acquirer or Visa representative if you would like to obtain a copy of the Visa Direct Original Credit Transaction (OCT) - Global Implementation Guide.

Availability

The following table lists the regional availability for Visa Direct. To view availability of all products, refer to the Availability Matrix.

Available in entire region

Limited availability in region

Not available

Product Name Availability Notes
Visa Direct
Product Name Availability Notes
Visa Direct
Product Name Availability Notes
Visa Direct
Product Name Availability Notes
Visa Direct
Product Name Availability Notes
Visa Direct

Getting Started

Visa Direct offers real-time push payment capabilities that utilize Visa’s global payment system, one of the world’s largest electronic payments network. Through their participating financial institutions, businesses and consumers can use the Visa network to send money to over one billion eligible Visa card accounts.

Visa Direct also offers the capability to push payments to other U.S. debit networks using the Visa Push Payments Gateway Service (PPGS) and the Funds Transfer APIs. PPGS allows originators to send their PushFundsTransactions (OCTs) and PullFundsTransactions (AFTs) to Visa for routing to multiple U.S. debit networks. The service provides authorization, clearing, settlement, reporting and exception processing support for debit networks. Visa translates and reformats the message into the correct network format, rather than an originator having to develop and maintain transaction formats for each debit network.

Note: Real-time payment - Actual funds availability varies by financial institution. Visa requires some issuers in some countries to make funds available to its cardholders within a maximum of 30 minutes of approving the transaction. For country level information, please contact your Visa representative. 

Visa Direct provides Originators (financial institutions and eligible third parties such as person-to-person payment service providers, merchants, corporations, and other payment service providers) with a way to connect to Visa, get access to information, and push payments directly onto Visa cards. A push payment is a financial transaction that adds funds to (in the form of a credit) a designated Visa account. As an Originator, the Visa Direct APIs provide you with a means to initiate a push payment from within your own web, mobile, ATM, corporate systems, or branch platforms. Push payments enable many consumer- and business-facing applications, including person-to-person money transfers as well as corporate, government and merchant disbursements. The best way to get started with Visa Direct is to understand how it works and the role that the Visa Direct APIs play in enabling Originators to move funds between Visa accounts.

Visa Direct: How it Works

Visa Direct contains three distinct APIs that you can use to create services that incorporate push payments. Each of these APIs is described in more detail in the following sections.

  1. The Funds Transfer API includes operations to pull funds from a Visa Card, push funds to a Visa card, and return funds to a Visa card in the event that a push funds transaction fails.
  2. The Mobile Push Payment API has been optimized for mobile-to-mobile card-less merchant payments.
  3. The Watch List Screening API provides Originators who are building cross-border services with a means to prescreen sender information against the United States Office of Foreign Assets Control (OFAC) Specially-Designated Nationals (SDN) sanctions list.

How Does it Work?

Visa Direct provides Originators (financial institutions and eligible third parties such as person-to-person payment service providers, merchants, corporations, financial technology companies and service providers, through their applicable financial institutions) with a mechanism to push payments directly into Visa card accounts. This push payment capability is delivered through the use of the Original Credit Transaction (OCT), a Visa network transaction that enables eligible Visa cards to receive push payment credits. Visa Direct Originators can submit OCTs either as ISO-formatted messages through a Visa network endpoint connection or directly into the Visa network as an API call using the Funds Transfer APIs. Originators can use this transaction and the underlying framework of rules and controls to create new consumer and business-facing services.

An OCT can be funded through a variety of sources; for example, any network payment account or a bank account. In addition to the OCT, Visa Direct also supports the Account Funding Transaction (AFT), a Visa network transaction that enables funds to be pulled from an eligible Visa account. As with the OCT, Visa Direct Originators can submit AFT transactions as either an ISO message or directly through an API call to the Funds Transfer APIs.

Originators can use the Funds Transfer APIs (or the ISO transaction) to pull funds (the AFT) from a Visa card account and to push funds (the OCT) into a Visa card account. AFTs can only be used to fund other non-merchant accounts. Once an AFT or OCT transaction is submitted into Visa (via API or ISO message), it travels across the Visa network and uses existing clearing and settlement mechanisms to manage the movement of funds between the sending and receiving issuers.

Notes :

  1. Real-time payments - Actual funds availability varies by financial institution. Visa requires some issuers in some countries to make funds available to its cardholders within a maximum of 30 minutes of approving the transaction. For country level information, please contact your Visa representative.
  2. Originators - Originators must be a Visa licensed acquirer or be sponsored by a Visa licensed acquirer. Third party service providers who offer push payment services to others (consumers or businesses) can be sponsored by a Visa licensed acquirer to offer push payment capabilities to Visa card accounts.

Why Use It?

Visa Direct can help your business develop fast, convenient, innovative and secure payment experiences. Use Visa’s familiar and reliable global network and distribution systems to create an entirely new class of services using the Visa Direct push payment capability. Some of the opportunities include:

Person-to-person payments

Visa Direct’s real-time payment capabilities open up new, more convenient payment experiences for many different use cases, including:

  • Paying friends and family
  • Splitting bills
  • Sending remittances
  • Account transfer

 

Funds disbursements

Visa Direct offers fast and efficient funds disbursement options for a variety of different applications including:

  • Reimbursements
  • Refunds
  • Rebates
  • Payouts
  • Loan distributions
  • Government disbursements

Through the Mobile Push Payment API, Visa Direct also enables mobile-based merchant payments using the OCT. Mobile Push Payment is presently available only in selected markets. Contact your Visa representative for details.

Visa Direct offers:

  • Speed: Transactions are processed in real-time.
  • Simplicity: An opportunity to create improved customer experience to enable fast payments to all eligible debit or prepaid cards.
  • Scale: Visa’s trusted expertise and capabilities to help you as you launch, grow, or enhance the payment experience for your customers.
  • Reliability: The reliability of the Visa network and framework of rules and controls to handle exceptions, manage risk and fraud and provide value-added services.
  • Security: A safe way to pay your customers, backed by Visa’s leading payment security.

Notes : Real-time payments - Actual funds availability varies by financial institution. Visa requires some issuers in some countries to make funds available to its cardholders within a maximum of 30 minutes of approving the transaction. For country level information, please contact your Visa representative.

APIs Included

Funds Transfer

The Funds Transfer API pulls funds from a sender’s Visa account (usually to fund a push payment to a recipient’s account) by initiating an Account Funding Transaction. It can then be followed by a push payment to a recipient’s Visa account that initiates an Original Credit Transaction. Push payment is a standalone capability and can be used either in conjunction with a pull payment (if the source of funds is a Visa card) or independently (if the source of funds is not a Visa card). Should a push payment be declined, the Funds Transfer API can also be used to return the funds to the sender’s funding source.

Watch List Screening

The Watch List Screening API provides a score that evaluates how closely an individual's name, city, and country match to entries in the OFAC SDN watch list. It also provides a status value that indicates if Visa would likely decline a cross-border transaction involving this individual.

Mobile Push Payment API

The Mobile Push Payment API has been optimized to push payments for mobile-to-mobile card-less merchant payments as well as for cash in or cash out to a Visa card. This capability is currently available only in select markets. Please contact your Visa representative for more information.

Alias

The Alias APIs enable push payments using a commonly known identifier such as mobile number and email address instead of sensitive data of PAN to a Visa account. These allow client to resolve an alias to a PAN for push payment transaction, and support alias lifecycle management of consumers and merchants. This capability is currently available only in select markets. Please contact your Visa representative for more information.

Reports

The Reports API provides reporting capabilities such as transaction reconciliation data in the API response. The data needed for reconciliation includes both push (OCT) and pull (AFT) transaction details and any exceptions such as chargebacks and reversals. This data is provided to allow you to reconcile the transactions sent by your systems with what was processed through Visa and may be used solely for such purposes.

Query API

The Query API allows service providers to query in real-time the processing status of Visa Direct (Account Funding and Original Credit) transactions as well as other related transactions that are part of the Visa Direct suite of transactions (Reversals, Adjustments, Chargebacks and Re-presentments).

The Transaction Query feature checks the state of a PullFunds (Account Funding), PushFunds (Original Credit), ReverseFunds (Account Funding Reversal), and Mobile Push Payment (Original Credit) transactions and returns the results; transaction successfully or erroneously received and processed by Visa and/or the financial institutions. Service providers can invoke the Query API when there is no response returned from Visa or when response is returned with errors (e.g. 500, 400, 404, etc.). Addditionally, it allows service providers to query history of transactions and return the entire transaction set related to the original Visa Direct transaction. A transaction set will include approved and settled original Visa Direct transactions, reversals, chargebacks, adjustments, and re-presentments. 

Refund API

The Refund API can be used to process a merchandise return (refund) transaction to a Visa card. The refund transaction is typically associated with a previous merchant payment. The refund can be for the entire amount of a previous transaction or portions of it. The primary data required for processing of a refund transaction is consumer PAN, amount of refund and data associated with original payment transaction.

Visa also supports Merchandise Return Reversal APIwhich is used to reverse a refund that was processed previously. This API results in funds being returned to the merchant’s account. Return reversal API is only valid if the transaction is sent within the same day.

Receive Side API

To facilitate the implementation of mobile push payments, Visa provides push payment Receive Side API. Clients or their processors can use this API to receive merchant payment, cash-in and cash-out transactions. Clients or their processors have to implement a set of outbound RESTful APIs (Receive Side APIs) so that Visa can call these APIs to request clients to process the transactions over the Internet. Clients have the option of implementing these APIs with JSON to receive enhanced OCT messages through a secure internet connection.

Adjustment API

Adjustment API allows API originators to return (credit) funds to the sender’s account that are debited using an Account Funding Transaction (AFT). This change applies in scenarios where the recipient does not claim these funds as a result of which they expire.

 

Foreign Exchange Rates

Get Visa's latest Foreign Exchange rates instantly.

Payment Account Attributes Inquiry

Find key attributes of a specific payment account.

Payment Account Validation

Access multiple methods of ensuring that a payment account is valid.

Using the Funds Transfer API

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:

  • An Acquiring BIN and its Country Code. This is the Bank Identification Number (BIN) that is used to clear and settle the transaction within Visa and the country in which it is licensed for use. If you are a financial institution (or have a Visa acquirer POS license), you can decide which of your licensed BINs you will use for funds transfer activity. This should be a unique BIN that is not shared with any other Visa service. If you are a sponsored third-party Originator, your sponsoring financial institution will assign an Acquiring BIN to you when you establish your acquiring relationship with them. You can obtain a test Acquiring BIN on your Project Dashboard for use in sandbox testing, but you will need to register your actual Acquiring BIN(s) with Visa during production onboarding.
  • Business Application Identifier (BAI). This is a two-character code that identifies the intended use of a push payment. It determines the data carried in the message, the limits and economics that may apply to the transaction, and may be used by the sending and/or receiving issuer to make an authorization decision. You can find permissible values in the Request and Response Codes Reference.
  • Information about an Individual Sender or Sending Entity. These fields (referred to as the Merchant and Card Acceptor fields in the technical specification) identify the sender and sender transaction narrative as it will appear on the cardholder’s statement. The sender- related information would typically be collected from the sending customer and included in the appropriate fields in the 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:

  • Visa Transaction Identifier. This is a unique reference number for this transaction that is assigned by Visa. To tie a PushFunds operation together with a previous PullFunds operation, you must populate the Transaction Identifier from the PullFunds response into the subsequent PushFunds request.
  • Action Code. A two-character code that indicates the result of the request. You can find a complete list of Action Code values and API Error Code values on the Request and Response Codes Reference.
  • Approval Code. This is the six-digit authorization code provided by the sending or receiving issuer.

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:

  • Common access for authorizations. This enables the use of a single connection and message format to process debit transactions for multiple networks.
  • Management of routing priority. This allows acquirers to establish a routing priority list in Visa for the Debit Networks. Additionally, Originators can provide priority information in the message for the Debit Networks whose cards they accept. Visa recommends that clients understand rules related to routing before implementation.
  • Multiple routing lists. This allows client to create a set of rules for a push transaction that are different from those established for a pull transaction.

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:

  • Pseudo ABA Number. This is a number that uniquely identifies the originator when they sign up to send Push Payment transactions. On enrollment, an originator will get a single pseudo-value that is assigned by Visa. The other debit networks will assign their own unique values for the originator.
  • Sharing Group Code.  This field is optionally used by originators to specify the network access priority. Visa makes a routing selection based on the routing priorities specified by both the originator and issuer preference for routing over the network.
  • Network Id. This contains a code that specifies the network to be used for transmission of the message and determines the program rules that apply to the transaction.

For additional information, contact your Visa account representative.

Using the Funds Transfer API to Pull Funds

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:

  • Sender Account Information. These fields include the Primary Account Number (PAN) of the Visa account from which the funds will be pulled as well as the account expiration date and billing currency.
  • Transaction Amount and Fees (if applicable). This is the total amount to be pulled from the sender account, inclusive of any fees that are assessed for the transaction. If you are charging a service fee and/or a foreign exchange rate markup in addition to the pull amount, the applicable fees must be included in the Transaction Amount and itemized separately in the applicable fields in the request message.
  • Point of Service Information. The request requires several data fields that identify the nature of the point of service – whether card-present or card-not-present. If the sender data was collected through an online or mobile application, the point of service fields should be populated with values that are appropriate to a card-not-present or e-commerce transaction. Pull funds transactions originating in the U.S. are restricted to the e-commerce environment. Outside the U.S., if the sender account data was obtained with a card swipe at a physical point of service, the Track 1 and/or Track 2 and/or PIN data (as applicable) must be captured from the card reader/terminal device and include it in the applicable fields in pull funds 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.

Using the Funds Transfer API to Push Funds

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:

  • Recipient Information. These fields include the recipient’s primary account number, name, and billing currency of the Visa account. Recipient name and billing currency may be selectively required depending on the use case and processing methodology.
  • Transaction Amount. This is the amount to be delivered to the recipient (in the recipient currency). Note that Visa imposes both geographical and use case-based limits on the maximum amount that can be included in a single transaction. For example, domestic person-to-person transfers have a default limit of USD$2,500. There are exceptions, such as in the U.S., where a limit of USD$10,000 per transaction applies. Refer to the API Reference link for specific details.
  • Sender Information. These fields include information about the sender, such as a name and address, date of birth, and either the sender’s primary account number or a reference number that refers to the source of the funds being sent to the recipient. For the purposes of risk, sanctions enforcement, and anti-money laundering/anti-terrorist financing controls, and regardless of funding source or access channel, you are responsible for verifying the identity of the sender before submitting a push payment request.
  • Transaction Identifier. If a PushFunds operation follows a corresponding PullFunds operation, you are required to take the Visa Transaction Identifier received in the PullFunds response and populate it into the same field in the PushFunds request in order to link the two transactions together.

Fast Funds

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.

Geographic Restrictions

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 developer@visa.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 developer@visa.com for more information.

Using the Funds Transfer API to Return Funds

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:

  • Data Elements from the Original Pull Funds Request. The reversal request must include some of the fields that were part of the original pull funds request and its response, including the Systems Trace Audit Number, Retrieval Reference Number, Transaction Identifier, Approval Code, Date and Time of Transmission, and Acquiring BIN.
  • Sender Account Information. These fields include the primary account number of the Visa account to which the funds will be returned as well as the account expiration date and billing currency.
  • Transaction Amount and Fees (if applicable). This is the total amount to be returned to the sender, inclusive of any fees that you may have assessed on the original pull funds transaction. If you charged a service fee and/or a foreign exchange rate markup in addition to the pull amount, the applicable fees must be included in the Transaction Amount and itemized separately in the applicable fields in the request.
  • Point of Service Information. For a funds reversal request, you should populate the point of service fields with values that are appropriate to a card-not-present or e-commerce transaction.

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.

Using Mobile Push Payment API

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

Using Mobile Push Payment SDK

The Mobile Push Payment SDKs provide the source code format 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.

Mobile Push Payment SDK (Android)

Title Description Version Uploaded
Issuer SDK to enable consumer experience SDK for use by an Issuer for mobile app development. This version provides the user experience screens as well as QR string parsing code to parse the merchant information. 2.5.1 Dec, 2018
Acquirer SDK to enable merchant experience SDK for use by an Acquirer to enable merchant QR code generation. This version provides the user experience screens as well as method or function to generate QR code on mobile app. 2.2.0 April, 2018
Issuer SDK for QR parsing SDK for use by an Issuer for mobile app development. This version provides method or function to parse the merchant information as captured by the issuer mobile app. 2.5.1 Dec, 2018

 

Mobile Push Payment SDK (iOS)

SDK for use by an Acquirer to enable merchant QR code generation. This version provides the user experience screens as well as method or function to generate QR code on mobile app.

Title Description Version Uploaded
Issuer SDK to enable consumer experience SDK for use by an Issuer for mobile app development. This version provides the user experience screens as well as QR string parsing code to parse the merchant information. 2.6.0 for Swift 4.1

2.6.0 for Swift 4.0.3
December, 2018
Acquirer SDK to enable merchant experience SDK for use by an Acquirer to enable merchant QR code generation. This version provides the user experience screens as well as method or function to generate QR code on mobile app. 2.6.0 for Swift 4.1

2.6.0 for Swift 4.0.3

2.2.0 for Swift 4.0.2

2.2.0 for Swift 4.0
Decemberl, 2018
Issuer SDK for QR parsing SDK for use by an Issuer for mobile app development. This version provides method or function to parse the merchant information as captured by the issuer mobile app. 2.2.1 for Swift 4.1

2.2.0 for Swift 4.0.3

2.2.0 for Swift 4.0.2

2.2.0 for Swift 4.0
April, 2018

 

QR Utility SDK

Title Description Version Uploaded
Acquirer or Merchant SDK for QR generation Java library for use by an Acquirer or Merchant during development. This version provides method or function to generate the QR code for use during merchant onboarding, online QR display or within the merchant mobile app. 2.2.0 for Android

2.2.0 for Swift 4.1

2.2.0 for Swift 4.0.3

2.2.0 for Swift 4.0.2

2.2.0 for Swift 4.0
April, 2018

Using Alias

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:

  • Consumer Alias-to-PAN mapping.  This is a mapping of a PAN issued to a consumer with an alias belonging to the consumer, e.g., mobile number, email address.
  • Merchant Alias-to-PAN mapping.  This is a mapping of a merchant PAN to a merchant for push payment acceptance with an alias belonging to the merchant, e.g. till ID or merchant tag. 

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.

You can find the technical specification for each alias operation on the API reference tab, and download the latest batch file processing technical specification.

Note: This service is available only in selected countries, please contact your Visa Representative for more information. 

Using the Watch List Screening API

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:

  • Name. This is the name of the person to be screened. The name can be any alphanumeric value up to 30 characters in length (and in the Latin character set). The suggested format of the name field is Last Name/Family Surname + space + Additional Last Name/Family Surname (if applicable) + space + First Name + space + Middle Initial/Middle Name.
  • City and Country. These fields are the city name and the alphabetic or numeric ISO country code of the address of 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.

Payment Account Validation

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.

Payment Account Attributes Inquiry

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.

Foreign Exchange Rates

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.

Security and Authentication Requirements

All of the Visa Direct APIs use mutual SSL authentication and channel encryption, which requires you to provide a user name and password as well as install an X509 security certificate issued by Visa. Test credentials can be obtained online in your Project Dashboard for sandbox testing. Production credentials will be supplied to you as part of production on-boarding. Contact developer@visa.com for more information or to begin the production on-boarding process.

Service Activation Requirements

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.

Best Practices and Tips for Using Visa Direct

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.

Error Codes and Exception Handling

To determine the status of any Visa Direct API call, use the combination of the HTTP status code returned in the response, error code from Visa Direct or the platform, and other information included in the response message in order to apply the correct processing logic and communicate with customers. The following table provides additional guidance on how to interpret and act upon status responses.

HTTP Status Code Error Code Error Description Recommended Handling
200 None Transaction processed successfully. The Action Code returned in the response indicates the outcome of the transaction (e.g. Approved, Declined, etc.) Map the value in the Action Code field to an appropriate customer-facing message (e.g. "Transaction Completed Successfully" or "Transaction Declined by Recipient Issuer").
202 None The POST transaction timed out. If the API is not able to complete the transaction within 30 seconds (default) or within the timeout duration set in the HTTP header, it will respond with an 202 HTTP Status Code and a statusIdentifier value that can be used in the GET operation as the statusIdentifier in the URI. Wait an appropriate amount of time and then submit a GET transaction using the statusIdentifier received in the POST response in the URL. The GET URL is valid for 24 hours and can be resubmitted as many times as needed until a successful response is returned. Consider providing a "Please Wait" type response to the customer while waiting for the transaction to complete and remind the customer not to retry the transaction because the initial request is still being processed.
303 None The API detected a duplicate transaction. A duplicate transaction was detected when re-submitting a POST transaction with the same header (e.g. X-Client-Transaction-ID) and details while the original transaction is still being processed. Use the GET response URL to retrieve details of the original transaction that is still in process.
400 3001 The transaction was rejected by Visa due to a message validation error. The message contains invalid data. Investigate the source of the invalid data before resubmitting the transaction. Consider placing the transaction in an exception queue and providing a suitable "Try Again Later" message to the customer if the problem cannot be resolved immediately.
401 None / 9123 / 9124 This is returned if user credentials are wrong.
Resubmit with valid user credentials
401
9125 This is returned due to client certificate does not matched with the one issued by Visa. 
Use the valid client certificate
403
None / 9611 The URL access is not permitted. Revalidate the URL and the Resource before resubmitting the transaction.
404 None The URL is invalid or the Resource could not be found. Revalidate the URL and the Resource before resubmitting the transaction. Consider placing the transaction in an exception queue and providing a suitable "Try Again Later" message to the customer if the problem cannot be resolved immediately.
404 3001 The message contains an invalid Primary Account Number (PAN) Display an appropriate message to the customer and ask them to correct the sender or recipient PAN and resubmit the request.
500 1001
2001
These are returned when an internal server error occurs. Contact your Visa production support contact for investigation and assistance.
503   This may be due to network connectivity issue. Contact your Visa production support contact for investigation and assistance. Recommend not to re-post transaction and check settlement report.
504   Timeout which may be due to network connectivity issue. Contact your Visa production support contact for investigation and assistance. Recommend not to re-post transaction and check settlement report.

Additionally, there is a specific HTTP header variable for timeout exception handling which Originators may consider to use if it is applicable to their projects. The following table lists the header details.

HTTP header variable Description
X-Transaction-Timeout-MS This is an optional variable.

Elapsed time in milliseconds (ms) in which an API will respond back. If no value is specified then it defaults to 30000 ms (i.e. 30 seconds), which is the maximum value allowed. If the set value is greater than the maximum value then timeout will not occur. The API will respond with HTTP 202 ACCEPTED if the processing has not yet completed. If the processing completes within the designated timeout period, then the API will return HTTP 200 OK and the XML- or JSON-formatted response, based on the Content-Type value.

The following section illustrates flow diagram of error handling.

Timeout exception handling

Repost transaction with different Retrieval Reference Number (RRN)

  • Original transaction has been processed by Visa
  • Original transaction is being processed by Visa

GET request with different responses

  • Retry GET request if response is timeout
  • Incorrect URL or GET request has already been sent
  • Transaction status is not known