VISA SERVICES
  • NEWS & EVENTS

    The Visa Developer Program's blog, tweets and upcoming events.

JSON
NVP
XML

Visa Personal Payments API

Visa Personal Payments API Overview

The Visa Personal Payments APIs provide financial institutions and eligible third parties a way to originate Visa Personal Payments from their applications, combining the flexibility of web services enabled by Visa processing on the back end. Visa Personal Payments (VPP) is a payment service that lets people “push” money to over 1 billion Visa accounts through the Original Credit Transaction (OCT). VPP consumer and business applications include:

  • VPP Money Transfer: Consumers can send funds to their Visa account or to another person’s Visa account.

  • VPP Prepaid Load: Consumers can load/reload funds to a eligible Visa reloadable prepaid card.

  • VPP Credit Card Bill Pay: Consumers can pay a Visa credit card bill.

  • VPP Funds Disbursements: Merchants, government entities, or corporations can send funds to a consumer’s Visa account.

The following table outlines examples of services that use the OCT and highlights the accounts that can receive that type of OCT and whether or not the service is domestic only or domestic and cross-border.

Oct Services

Destination Visa Account Types

Geographic Scope

Visa Credit

Visa Debt

Visa Prepaid

Domestic

Cross-Border

Money Transfer

X

X

X

X

X

Funds Disbursements

X

X

X

X

X

Prepaid Load

X

X

Credit Card Bill Payment

X

X

How the VPP APIs Work

The VPP APIs are grouped into two distinct categories: Value Added and Financial APIs. Value Added APIs are used to validate information related to the funding and credit transactions, whereas Financial APIs are used to facilitate the movement of funds between Visa accounts.

Value Add APIs

Financial APIs

Account Look Up (ACNL)

Account Verification (ACNV)

Watchlist Management (WLM)

FX Look Up (FX)

Account Funding Transaction (AFT)

Account Funding Transaction Reversal (AFT-R)

Original Credit Transaction (OCT)

Multi Transaction Account Funding Transaction (MULTIAFT)

Multi Transaction Account Funding Transaction Reversal (MULTIAFTR)

Multi Transaction Original Credit Transaction (MULTIOCT)

Recommended Transaction Flow for Domestic Payments

Visa

VPP API’s Used:

  • ACNV (optional)

  • AFT (optional)

  • AFT-R (optional)

  • ACNL (optional)

  • OCT (required)

  1. Collect payment and source of funds detail from customer.
    Determine the customer’s source of funds for the OCT transaction. Collect sender information and amount of OCT transaction. Perform KYC, fraud and eligibility checks on sender and/or recipient if required.

  2. Determine recipient card OCT and Fast Funds eligibility using recipient card number.
    Call ACNL API to determine: OCT acceptance eligibility, Fast Funds eligibility, Visa card type (if relevant), country and currency of Visa card (if relevant). Perform proprietary fraud and eligibility checks on recipient card. Determine fees and quote transaction total (including fees) to sender.

  3. Confirm funds availability from customer’s source of funds.
    [OPTIONAL] If source of funds provided is a Visa Credit, Debit or Prepaid card, call ACNV API to validate Visa cardholder details (AVS/CVV2 information) prior to calling AFT API. If the AFT transaction is successful, proceed to originate the OCT transaction. If AFT transaction is not successful, request another card or Source of Funds from customer, or end transaction flow.

  4. Originate an OCT.
    Call OCT API to originate OCT transaction. If OCT is successful, confirm that the payment has been sent to the customer. If OCT is not successful, error to the customer. If an AFT was used to fund the OCT, call AFT-R API to reverse the corresponding AFT transaction.

  5. Confirm transaction status to customer via GUI, email or other communication.

Recommended Transaction Flow for Cross-Border Payments

Visa

VPP APIs Used:

  • ACNL (optional)

  • FX (optional)

  • ACNV (optional)

  • AFT (optional)

  • AFT-R (optional)

  • OCT (required)

  1. Collect payment and source of funds detail from customer.
    Determine customer’s source of funds for the OCT transaction. Collect sender information amount of OCT transaction. Perform KYC, fraud and eligibility checks on sender and/or recipient if required.

  2. Determine recipient card OCT and Fast Funds eligibility using recipient card number.
    Call ACNL API to determine: OCT acceptance eligibility, Fast Funds eligibility, Visa card type (if relevant), country and currency of Visa card (if relevant). Perform proprietary fraud and eligibility checks on recipient card. Call FX API to determine transaction amount and FX rate if required. Determine fees and quote transaction total (including fees) to sender.

  3. Confirm funds availability from customer’s source of funds.
    [OPTIONAL] If source of funds provided is a Visa Credit, Debit or Prepaid card, call ACNV API to validate Visa cardholder details (AVS/CVV2 information) prior to calling AFT API. If the AFT transaction is successful, proceed to originate the OCT transaction. If the AFT transaction is not successful, request another card or Source of Funds from customer, or end transaction flow.

  4. Originate an OCT.
    Call OCT API to originate OCT transaction. If OCT is successful, confirm that the payment has been sent to the customer. If OCT is not successful, error to the customer. If an AFT was used to fund the OCT, call AFT-R API to reverse the corresponding AFT transaction.

  5. Confirm transaction status to customer via GUI, email or other communication.

Getting Started

This section describes how to Get Started using Visa Personal Payments APIs, including:

  • Reference to the Visa Personal Payment Methods. A listing and description of all the methods are in one location, with links to reference documentation for each.

  • Invoking a Visa Personal Payments API Method. Description of the interaction of an invoked method within the Visa Personal Payments environment, either synchronously or asynchronously with timeout behavior, according to developer preference. This section includes step-by-step instruction on how to:

    1. Install the VPP Client Security certificate to Keystore.

    2. Install the VPP Server Security certificate to Truststore.

    3. Set up HTTP header variables

    4. Populate the body of the request template

    5. Post the request

    6. Handle status conditions and request a status check

    7. Consume the response

Invoking a Visa Personal Payments API Method

To invoke the methods, developers pass REST requests to the Visa Personal Payments API, which accepts requests in REST protocol, using XML, JSON or NVP format. The developer specifies response format in the request header.

Each request contains a single method. The Visa Personal Payments API handles each separately from all others. Even when contiguous and pertaining to the same financial transaction, no subsequent request can access any Visa Personal Payments API memory of a previous request. For example, although all requests use the X-Client-Transaction-ID property, a particular value for that property is valid only for passing the current method and may not be used to pass a subsequent method for the same financial transaction.

Authentication Overview

Client/Server authentication involves the below three aspects:

  • API credentials: HTTP Basic authentication scheme is used to validate the API username and password

  • SSL client certificate: SSL client certificate validation is performed to ensure that the request is sent from a trusted API client

  • SSL server certificate: API clients need to add the VPP SSL server certificate to its Trust Store for the SSL Handshake to happen successfully

IMPORTANT: For both sandbox and production servers, each call must be a certificate-based invocation. In order to successful connect to the Visa Personal Payments API, you must have a username, password and X509 security certificate.

  • A Sandbox security certificate and credentials are furnished with your Visa Personal Payments developer account upon registration.

  • To obtain a Production security certificate and credentials, please contact your Visa representative.

To pass a request to the Visa Personal Payments API:

  1. Install the VPP Client Security certificate to Keystore.

    Complete the following prerequisites:

    • Install JDK. Install the Java Development Kit that came with Keystore.

    • Verify and Launch Keystore. Verify the presence of keystore in your system; then from a command line:

       keytool

    • Verify and Launch SSL. Verify the presence of SSL in your system; then, from a command line

       openssl

    To convert PEM to PKCS12, invoke ssl using the following syntax:

       openssl pkcs12 -export -in <MYPEM> -name <CHOOSE_AN_ENTRY_NAME> 
           -passout pass:<CHOOSE_A_PASSWORD> -out <MY_P12>

    The variables refer (for example) to:

    Variable

    Example value

    <MYPEM>

    Jinal1.pem

    <CHOOSE_AN_ENTRY_NAME>

    Test

    <CHOOSE_A_PASSWORD>

    Test123

    <MY_P12>

    foo.p12

    For Java-based systems (PKCS12 to JKS), follow the above steps for PEM to PKCS12, then invoke the Key tool using the following syntax:

       keytool -importkeystore -srckeystore <MY_P12> -srcstoretype pkcs12 
           -destkeystore <MY_JKS> -deststoretype jks

    The variables refer (for example) to:

    Variable

    Example Value

    <MY_P12>

    mycert.p12

    <MY_JKS>

    mystore.jks

  2. Install the VPP Server Security Certificate to Truststore

    The SSL server certificate installed on the sandbox.visa.com servers is a Visa-issued, self-signed certificate. Client applications need to add the sandbox.visa.com SSL certificate to their local trust store to prevent SSL handshake errors from occurring at runtime.

  3. Set up HTTP header variables

    Variable Name

    Value

    X-Client-Transaction-ID

    Optional.

    A unique value for this transaction (unique at the level of the individual service invoker and can be recycled every 24 hours). This identifies the transaction uniquely and can help reference the results of the original transaction.

    This behavior is only applied to Asynchronous APIs (refer to Visa Personal Payment Methods), and Synchronous APIs will respond only upon successful completion or failure.

    Content-Type

    Optional.

    Specify request format:

    • XML. Use text/xml.

    • JSON. Use application/json.

    • NVP (name-value pairs). Use text/plain.

    If not specified, expects JSON.

    X-Transaction-Timeout-MS

    Optional.

    Elapsed time (in ms) in which an API will respond back. If no value is specified then it defaults to 30000 ms, which is a maximum value allowed. If the set value is greater than the max 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 with in the designated timeout period, then the API will return HTTP 200 OK and the XML-, JSON- or NVP- formatted response, based on the Content-Type value.

    The AFT, AFTR, and OCT APIs have the potential to return 202 HTTP status code if a value is provided and a timeout has been reached during the request. The recommended value for this header field is anything between 0-50 ms. If the value is higher than this, the application may not provide a 202 HTTP status code consistently.

    This behavior is only applied to Asynchronous APIs (refer to API Methods Reference page), and Synchronous APIs will respond only upon successful completion or failure.

    Accept

    Optional.

    Specify request format:

    • XML. Use text/xml.

    • JSON. Use application/json.

    • NVP (name-value pairs). Use text/plain.

    If not specified, defaults to request format.

    Authorization

    Mandatory.

    API username and password formatted using HTTP Basic authentication scheme

  4. Populate the body of the request template

    For each method, the Visa Personal Payments API reference provides a request template, in XML, JSON and NVP formats, as well as documentation of property values. The templates contain sample entries and criteria for each property, with the intention that your information will overwrite it.

  5. Post the request

    NOTE: The distinction between submitting to sandbox and to production lies entirely in the choice of URI.

    Post the request to its host- and method-specific URI:

    https://sandbox.visa.com/rsrv_vpp/v1/<method>

    where <method> represents the lower-case abbreviation for the invoked method, from the following list:

    • acnl (Account Lookup),

    • acnv (Account Verification),

    • wlm (Watchlist Management),

    • fx (FX Lookup),

    • aft (Account Funding Transaction),

    • oct (Original Credit Transfer), or

    • aftr (Account Funding Transaction Reversal).

  6. Handle status conditions and request a status check

    At either a specified interval (asynchronous) or upon completion of processing (synchronous), the Visa Personal Payments API returns header values that include (among other values) ###status### and Location:

       ###status###     HTTP/1.1 <status code>
        Location         http://localhost:8080/vpp/v1/fx/<locationId>
    

    where <status code> and <location> refer to:

    Status Code

    Meaning (and function of) Location value

    200

    OK.

    Transaction completed successfully.

    The HTTP header variable location specifies the URI of the response.

    400

    Bad request.

    Transaction not started due to malformed request body.

    Resubmit corrected request with the same X-Client-Transaction-ID.

    500

    Internal Server Error.

    Server unable to process at this time, unrelated to client request.

    Resubmit request at a later time

    202

    202 Accepted.

    Transaction started but not completed before specified timeout.

    Make a GET request to location URI specified in the response header to get the status of the previously started transaction.

    303

    See Other.

    When a transaction is submitted twice with the same X-Client-Transaction-ID then it will result in a 303 status code. Make a GET request to location URI specified in the response header to get the status of the original transaction.

    Error Codes may also be returned, in which case:

    The response header X-Application-Error-Code will be set to 1xxx, 2xxx, or 3xxx with the following meanings:

    • 1xxx or 2xxx. Contact or your Visa representative.

    • 3xxx. Provides feedback usable by the developer in troubleshooting. Any additional information about such errors will appear in the response header X-Error-Additional-Info, which will contain a brief textual description of the error (not present for all error conditions).

  7. Consume the response

    Upon successful processing of a request, the Visa Personal Payments API returns an XML-, JSON-, or NVP-formatted response. The Visa Personal Payments API reference provides a sample Response Message in each format, as well as documentation of property values.

Checklist for Sandbox

This section summarizes the steps to be followed for integrating with Visa Personal Payments APIs in the Sandbox environment.

  1. Enrollment

    • Sign up for the Visa Developer Program.

    • Enroll in the Visa Personal Payments Service.

  2. API Credentials

    • Ensure that the API username password listed under the VPP console are sent in the API requests using the HTTP Basic authentication scheme.

  3. SSL Client Authentication

    • The PEM certificate available at VPP Console is an SSL client certificate. This needs to be converted to PKCS12 type and used as KeyStore for connecting to VPP Sandbox API URL.

    • Verify that your PKC12 keystore has both the PrivateKey and the certificate bundled into it.

    • Ensure that your application that connects to the VPP API is configured (or built) to use the PKCS12 file as a keystore and not as a trust store.

    • Verify that the application is configured to use the right password associated with the PKCS12 file.

  4. SSL Server Authentication

    • The SSL server certificate installed on sandbox.visa.com servers is a Visa issued self-signed certificate. Client applications need to add the sandbox.visa.com SSL certificate to their local trust store to prevent SSL Handshake errors at runtime.

    • Ensure that your application that connects to the VPP API is configured (or built) to use the trusted certificate store as a trust store, and not a key store.

    • Verify that the application is configured to use the right password associated with the trust store file.

  5. HTTP Headers

    • All the VPP API requests should include the mandatory Content-Type, Accept and Authorization HTTP header parameters.

Visa Personal Payment Methods

The Visa Personal Payments API makes available aspects of Visa back-end processing for integration into your institution’s custom applications. When using some or all of the provided methods, you may wish to consider the sequence suggested by the flowchart in Visa Personal Payments API Overview, bearing in mind the following caveats:

  • No Required Methods. Visa Personal Payments applications do not require any particular methods, but Visa recommends beginning transactions with Account Verification (ACNV) and/or Account Lookup (ACNL).

  • No Required Sequence. Such applications do not require invoking methods in a particular sequence; however, you may wish to consider the sequence indicated in the flowchart provided in the Visa Personal Payments API Overview.

  • Synchronous and Asynchronous classifications.

    • Synchronous methods: ACNL and FX APIs are considered synchronous. These methods do not timeout based on X-Transaction-Timeout-MS value, but will respond only after completing the processing with a success or failure message. ACNL and FX methods do not act based on X-Client-Transaction-ID and will process the request even if a duplicate request is received.

    • Asynchronous methods: AFT, AFTR, OCT, WLM, ACNV are considered asynchronous. These methods will accept the value passed for X-Transaction-Timeout-MS and will respond with the time elapsed in the request with a HTTP 202 or HTTP 200, or a failure based on completion of processing the request. AFT, AFTR, OCT, WLM, ACNV also accept the value passed for X-Client-Transaction-ID and will not re-process the transaction if it finds it as a duplicate request. Instead, an HTTP 303 is generated along with the location URI, in order to provide a means to re-request the response.