Visa Payments Processing Documentation

Ready to start coding?

Things To Know

The Visa Payments Processing (VPP) APIs are available on a trial basis to gather feedback and enable future development.

The Authorization API can be used by any developer in the Sandbox. To use a complete suite of the Visa Payments Processing APIs in the Sandbox, Certification or Production you must be pre-approved by your acquirer and Visa. The approval process is available as part of Production Onboarding. Use of the VPP APIs is subject to the use restrictions and other terms and conditions set forth in the applicable agreement. For further information, contact developer@visa.com.

What's New - Release Notes

August 2018

Visa Payment Processing APIs now offer support for the following services:

  • Real Time Visa Account Updater (Real Time VAU) – API request messages for recurring and credential-on-file transactions are enhanced with merchant requests for Real Time VAU account updates. The requests for payment processing and account updates are processed at the same time in VisaNet. API response messages are also enhanced with new VAU details including a replacement PAN and/or replacement expiration date, closed account or contact cardholder advice, or VAU non-eligibility reason code.
  • Payment Account Reference (PAR) – API response messages are enhanced with the PAR value.
  • Visa Transaction Advisor (VTA– Ecommerce) – API response messages are enhanced with Risk Condition Codes that provide acquirers and/or merchants with potential risk of account compromise.

For further information or service activation instructions, contact your regional client support representative.

Message Level Encryption

Message Level Encryption (MLE) is required for all Visa Payments Processing APIs implementations. MLE provides an enhanced security for message payload by using asymmetric encryption technique (public-key cryptography). You can generate the encryption/decryption key pairs in the Sandbox, Certification, or Production environments. For details, refer to the Message Level Encryption Documentation.

Availability

The following table lists the regional availability for Visa Payments Processing. 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 Payments Processing Available in United States
Product Name Availability Notes
Visa Payments Processing Available in China
Product Name Availability Notes
Visa Payments Processing
Product Name Availability Notes
Visa Payments Processing Available in Nigeria
Product Name Availability Notes
Visa Payments Processing

Getting Started

The Visa Payments Processing APIs enable Visa clients, such as acquirers, acquirer processors, approved merchants and payment facilitators to process card-not-present payments through a direct interface to Visa’s global payment system. The VPP APIs supports a simplified processing model with a lightweight interface and doesn’t require clients to submit clearing batches. The VPP APIs deliver all the information needed to authorize and clear transactions reducing the risk and uncertainty related to delays of batch clearing. The VPP APIs support processing of payment requests for Visa credit, debit and prepaid cards. The verification requests may be used to validate payment account information for Visa and supported non-Visa brands.

Visa Payments Processing APIs Benefits

  • Efficiency. Rapid prototyping, simplified integration, project development and production onboarding via the Visa Developer Platform
  • Access. Supports innovative payment solutions with a simple connection over the Internet to the VisaNet payment system eliminating the need for installing any hardware at client’s site
  • Security. Security of a trusted network; supports data encryption and mutual authentication
  • Value. Enables improved revenue and reduced costs for added bottom-line benefits

How Does It Work?

The VPP APIs enable approved Visa clients to process card or token-based payment requests for Card-Not-Present processing scenarios. Acquirers and other approved clients* connect to Visa over the public Internet.

The following infographic illustrates how the VPP APIs function.


Step 1: Cardholder places order.

Step 2: Merchant’s site or project sends payment information directly to Visa using the secure VPP API.

Step 3: Visa validates the client, sending the API payment request and routes the payment request to the issuing bank for payment decision.

Step 4: Issuing bank approves or declines the payment request.

Step 5: Visa returns the payment response to the client.

Step 6: The acquiring bank receives the settlement reports and all transaction details from Visa. 

* Clients may include acquirer processors, payment facilitators and merchants where sponsored by Acquirer and approved by Visa. 

Why Use It?

  • Simplify integration efforts with client or partner projects
  • Shorten and accelerate development cycle time
  • Enable development of innovative payment solutions
  • Drive Internet of Things (IoT) enabled commerce experiences

Note: Use of the VPP APIs is subject to Acquirer and Visa approvals.

APIs Included

Authorization API

The Authorization API is used to request approval of card or token-based transactions. To enable the clearing and settlement of an approved transaction, a subsequent Capture API request is required. 

In addition to Authorization API, VPP also offers the following APIs that are restricted. To access the following Visa Payments Processing APIs in sandbox, certification and production you must be pre-approved by your acquirer and Visa. For further information, contact developer@visa.com.

Capture API

The Capture API is used to initiate the clearing and settlement of a previously approved authorization request.  The Capture API request should be submitted as soon as a client fulfills a customer’s order and must be within 30 days of the original authorization request.

Sale API

The Sale API is used for a purchase when goods or services are delivered immediately to the consumer.

Refund API

The Refund API is used to submit credit vouchers or merchandise returns for card and token based transactions.

Void API

The Void API can be used to reverse an outstanding or previously approved transaction. Voids can be also be submitted in case of time-outs.

Verification API

The Verification API can be used to validate cardholder account information. Account verification is supported for both Visa and non-Visa brands*.

* Non-Visa brands include payment networks supported by Visa Authorization Gateway Service.

Processing an Online Payment Transaction

The VPP APIs offer a direct access to the Visa payment processing systems, such as authorization and clearing. The VPP APIs enable Visa clients, such as acquirers, acquirer processors, approved merchants and payment facilitators to process payment transactions directly with VisaNet.
Note: Clients responsible for Internet access.

The following table outlines examples of processing scenarios and features that can be used in new payment projects.

*Requires approval from Visa. 

**Available to all registered developers in the sandbox.

***Non-Visa brands include all payment networks supported by the Visa Authorization Gateway Service.

Security and Authentication

The VPP APIs require Two-Way SSL (Mutual Authentication) method. This authentication method calls for client and server to authenticate and validate each others identities. The authentication message exchange between client and server is called an SSL handshake. During the SSL handshake, both client and server verify each other certificates and if successful, the server grants access to the resource requested by the client.

Click here to view more details on how to obtain a valid client certificate from Visa Developer.

In addition to message authentication credentials, Visa requires encryption of the sensitive data such as PAN or cardholder name and address included in request and response messages. You must appropriately encrypt sensitive data before sending an API request to Visa and you will have to decrypt sensitive data in API responses before using it for processing.

For more information about how to encrypt/decrypt data in the VPP APIs messages, contact developer@visa.com.

Using RESTful API Concepts

The Visa Payments Processing APIs use the following RESTful API concepts:

Resources. Each payment function is accessed with a “resource”, such as authorizations, verifications, sales, captures, refunds and voids. 

HTTP Verbs and Status. HTTP POST verb is used to submit requests. The HTTP status code 200 is returned for a successful API call. Other HTTP status codes, such as 400 and 500, are returned for unsuccessful calls. See the Error Code and Exception Handling section for more details.

Hypermedia links for follow-on actions. VPP APIs use JSON Hypertext Application Language (HAL) to identify the follow-on actions that can be performed on a resource. For example, a payment capture can be performed on a successful payment authorization.

Hypermedia as The Engine of Application State or HATEOAS is a constraint of the REST application architecture.

The VPP APIs use JSON Hypertext Application Language (HAL) to inform the follow-on actions that can be performed on a resource. For example, a capture can be performed on a successful authorization. Hypermedia links are returned for the Authorizations, Captures, Sales and Refunds resources. The HTTP Accept header should support the value of “application/hal+json” for these resources. POST is the only action currently supported for the hypermedia links.

Using correlatnId in API Messages

Using correlatnId in Authorization, Capture, Sale, Refund, Verification API messages

correlatnId is a unique ID that you as a client create for each API request call. This is a different parameter than the requestId that is created by Visa.

VPP APIs support idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if an authorization request fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single authorization request is processed. 

To perform an idempotent request, submit a POST request using a unique value in the correlatnId field. If the transaction is submitted with the same correlatnId value and request fields, VPP APIs will set the duplicateResp field to true and return the results of the original transaction.

The correlatnId field for Authorization should be unique for a period of 180 days. The correlantnId for the rest of the resources should be unique for a period of 48 hours.

Using correlatnId in Voids without resource id

VPP APIs support submitting a Void request prior to receiving the resource id of primary request (Authorization, Capture, Sale and Refund) in case of time-outs. When submitting such Voids, the correlatnId field should contain the value used in the primary request. Otherwise, the void will be rejected.

Service Activation Requirements

Sandbox testing and certification are required for using the VPP APIs. Clients and their development partners will be required to complete testing and certification of the VPP APIs before activation in production.

You can get a test Client ID and test data from the Project Console for testing your integration with the VPP APIs in the sandbox. For certification, you must use client credentials and test data provided by your acquirer. To use the VPP APIs in production, you must be approved by your acquirer and Visa.

You must sign up for the VPP APIs by signing a Visa Developer Program API Agreement. After signing an agreement, Visa will assign an Implementation Manager who will be your main point of contact at Visa during implementation. The Implementation Manager will provide you with a project plan for implementing the VPP APIs and required onboarding forms.

For further information, contact developer@visa.com.

Error Codes and Exception Handling

The VPP APIs use conventional HTTP response codes to indicate the success or failure of an API request. The HTTP status code 200 is returned for a successful API call. Other HTTP status codes, such as 400 and 500, are returned for unsuccessful calls. 

To determine the status of any VPP API call, use the combination of the HTTP status code returned in the response, error code from the Visa 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.

Exception Handling 

HTTP Status Code Error Code Error Description
200
None API request processed successfully. A combination of the actionCd and tranReslt attributes returned in the response indicate the outcome of the transaction (e.g. 00 Approved, 10 Partially Approved, etc.). 
400 Various The message had validation errors due to invalid field lengths, data type, or missing fields.
401 None The API request is returned if user's credentials are invalid.
Authentication failure.
402 Various API request failed due to a processing error or issuer declined the payment transaction. For Capture and Void requests, tranReslt may contain a NotProcessed status.
403 None The URL access is not permitted. Contact your Visa production support contact for assistance.
404 None The URL is invalid or the Resource could not be found.
500 None An internal server error occured. Contact your Visa production support contact for assistance.
503 None Service unavailable. Contact your Visa production support contact for assistance.
504 None Timeout due to a processing issue or a network connectivity issue. Contact your Visa production support contact for assistance.

Best Practices and Tips

The VPP APIs support a combination of cardholder and card account validation checks while processing payment transactions. These checks such as Account Verification (AV), Address Verification (AVS), Card Verification Value 2 (CVV2), and Cardholder Authentication Verification Value (CAVV) can be performed with all VPP APIs (please note that CAVV validation checks are not supported for the Verifcation API).

Note: You should never store cardholder and card account security information collected from consumers.

You are encouraged to implement risk management best practices for payment transactions processed via the VPP APIs, just as you would for any e-commerce transaction. The validation checks performed via VPP APIs are not intended to replace or supplant your own fraud and risk management techniques. They should only supplement your existing controls, models, processes and procedures.