Visa Developer Payment Guide - Visa Checkout and Vantiv

Document created by mobileteam on Dec 1, 2016Last modified by lsolheim on Aug 6, 2018
Version 22Show Document
  • View in full screen mode

Introduction for the Visa Developer


Visa Checkout™ is a digital payment service in which consumers can store card information for Visa, MasterCard, Discover, and American Express cards. It provides a quick integration method for merchants that want to accept payments from any of these card holders.


Visa Checkout is flexible and imposes only a few requirements for its use. It can be added easily to existing websites and mobile applications.


You can add Visa Checkout buttons to existing pages and implement business and event logic using your choice of programming languages. Worldpay supports Visa Checkout purchases from your website or mobile application.  See the links below for relevant payments topics for the Visa Developer coding to Visa Checkout.


At present, Visa Checkout is supported on Vantiv's core processing platforms via Vantiv's eProtect service. Developers will use Visa Checkout and eProtect to obtain an eProtect Registration ID as explained below and use this token to process an Authorization via ISO 8583 or 610 message formats just as they would with any eProtect enterprise integration.



Important Resources

Before you get started it's a good idea to familiarize yourself with these resources from Visa and Vantiv.

  • VISA Developer Center - Visa Checkout QuickStart - this is your main source of information about Visa Checkout. Developers may want to start here, and return to this page on Vantiv O.N.E. for details about adding eProtect support and Vantiv specific Visa Checkout code examples.
  • Visa Developer Center - Things To Know - this is a useful checklist of important things a developer should know before starting a Visa Checkout Integration
  • Visa Developer Center - Documentation - this is where you can find key documentation about Visa Checkout APIs depending on whether you are adding Visa Checkout to a website or a mobile.
  • Vantiv eProtect Solution for Visa Checkout - This is Vantiv specific documentation offered as a supplement to the Visa developer resources above. This will help developers understand how Visa Checkout interacts with the eProtect service.
  • Vantiv Enterprise eProtect Integration Guide - This is a Vantiv specific document that describes how to process Authorizations and Sales to Vantiv's core processing systems. It is assumed that developers already integrated to these platforms adding Visa Checkout as a new wallet will already be familiar with the ISO 8583 or 610 interfaces.


Visa Checkout Operation with Vantiv eProtect

tw vantiv eprotect with visa checkout.png

Vantiv's eProtect is a service that helps developers solve card-not-present challenges by virtually eliminating payment related data from order handling systems. When a card holder submits their account information, your checkout page or app calls the eProtect service to register the provided credit card in exchange for a token. This token can then be used as a method of payment by Vantiv's core systems.


No card data is actually transmitted via your web server or handled by your app making eProtect a good solution for reducing PCI PA DSS scope.


The high-level sequence of events is slightly different depending on whether you are adding Visa Checkout to a web page (including a mobile web page) or to a native iOS or Android Application. The specific steps for each case are similar and are explained in detail below:


Visa Checkout Operation with eProtect from a Mobile Website


  1. When the consumer selects the Visa Checkout option on your website, the Visa Checkout SDK requests payment data from Visa Checkout.
  2. When Visa Checkout receives the call from your website via the Get Payment Data API , Visa creates a "payment.success" event using the Vantiv API key. Included in the payment.success event is encrypted PAN (primary account number) data representing the user's method of payment. This may be a Visa card or another card brand.
  3. Visa Checkout returns this payment.success event (described here ) to your web application.
  4. The merchant site sends the payment data passed to the payment.success event handler along with other details to Vantiv's eProtect service using the sendToEprotect() method and Vantiv decrypts the payment data containing the PAN. eProtect vaults the PAN and returns a Registration ID along with additional customer information contained in the eProtect response.
  5. The merchant website then forwards the transaction along with the eProtect Registration ID to Vantiv's processing server as it would for any other eProtect transaction
  6. The server constructs an Authorization or Sale transaction using the eProtect Registration ID and submits it to one of Vantiv's core systems for processing. The format of the Authorization will depend on whether the merchant is using ISO 8583 or 610 message formats to connect to Vantiv transactional systems.
  7. Vantiv relays the transaction with appropriate information to the card networks for approval.
  8. Vantiv sends an Approval/Decline message back to your system. This message is in the standard response format for an Authorization Sale response and it includes a separate Vantiv token that can be retained for future use including card-on-file functionality.
  9. You then return the Approval/Decline message to your website.


Modifying your HTML page to use Visa Checkout with Vantiv eProtect


When using Visa Checkout with Vantiv eProtect, minor changes are required to the website checkout page as shown in the Visa Checkout Quick Start guide . Some additional changes are required to add eProtect to the web page as well.


  • Within the header of your web page (<HEAD> tags), you'll want to make sure that you add Vantiv's eProtect library is loaded as shown below. There are different JavaScript libraries to include depending on whether you are processing against Vantiv's "pre-live" environment or "production environment". You can find details in the manual Vantiv eProtect Solution for Visa Checkout documentation.


<script type
" src



  • You will need to modify the onVisaCheckoutReady() JavaScript function described in the Visa development documentation to add support for eProtect as shown below. Note the creation of the eProtect object ep where you initialize eProtect. Developers will call Visa's V.init() function according to the Visa Checkout developer documentation passing an API key returned by eProtect's getVisaCheckoutApiKey() method and an externalClientId provided by your Vantiv implementation consultant. An example is shown below including an externalClientId that you can use to verify the functionality.


function onVisaCheckoutReady() {
var ep = new eProtect();
apikey: ep.getVisaCheckoutApiKey(), //Vantiv's current Visa Checkout API Key
sourceId: "Merchant Defined Source ID",
externalClientId: "stefan_sandwiches", //Merchant's client id - get this from Vantiv's implementations team
settings: {
paymentRequest: {


  • Inside V.init(), the developer creates the payment request as specified in the Visa Checkout documentation. An example is shown below. Note that the integration provides developers with the opportunity to pass custom name-value pairs related to the transaction as customData.


paymentRequest: {
     merchantRequestId: "Merchant defined request ID",
     currencyCode: "USD",
     subtotal: "10.00",
     shippingHandling: "2.00",
     tax: "2.00",
     discount: "1.00",
     giftWrap: "2.00",
     misc: "1.00",
     total: "16.00",
     description: "...corp Product",
     orderId: "Merchant defined order ID",
     promoCode: "Merchant defined promo code",
     customData: {
          "nvPair": [
               { "name": "customName1", "value": "customValue1" },
               { "name": "customName2", "value": "customValue2" }


  • The heart of the integration with eProtect is the line of code below added to the end of the Visa Checkout V.on("payment.success") :


new eProtect().sendToEprotect(vantivRequest, formFields, submitAfterLitle, AfterLitle, onTimeoutAfterLitle, timeout);


  • The vantivRequest structure contains details like the eProtect URL endpoint and the merchant's eProtect credentials
  • formFields refers to a list of hidden HTML INPUT fields where details like the paypageRegistrationId (the low-value token) and the bank identification number (BIN) will be returned by the eProtect library
  • The next three functions are callbacks, and the eProtect response object will be passed to one of the supplied JavaScript functions depending on whether the transaction is successful, there is an error or there is a timeout


  • A working example configured for use with the Visa Checkout Sandbox is presented at this URL:


You can view the source to see exactly how the JavaScript has been modified for use with eProtect.


The full source code for the HTML page is replicated here.


This example together with the Visa Checkout documentation should be sufficient for most web developers to understand the integration and how to modify the merchant's website.


You will want to replace the "Paypage ID" in the Test Input Fields area with your own eProtect credentials provided by Vantiv. The Test Input fields in a production application would generally have the attribute "type=hidden". They are exposed in our simple example so that developers can see and change the values if they choose.


Assuming a check out with Visa Checkout is successful, the Paypage Registration ID and the Bin values will be extracted from the eProtect response. The Paypage Registration ID is the value that represents the payment credential that is subsequently used to make the Authorization or Sale request.




Test the Visa Checkout integration

  • To exercise the Visa Checkout example, you can visit our test page at
  • Once page loads, simply click the Visa Checkout icon.
  • You will be invited to check out using the Visa Checkout Sandbox as shown below.
  • If you don't already have a Visa Checkout sandbox account, you can create one on the fly.
  • You can load your VISA Checkout wallet with one of the sample cards provided on the checkout form. For example, 4100000000000001 for VISA and 5123456789012007 for MasterCard. In the sandbox, expiry dates are not validated, so you can use whatever expiry dates you'd like for testing. We recommend that you use the Vantiv supplied test card numbers rather than the test card supplied on the Visa Checkout developer site.



Once you authenticate yourself to the Visa Checkout sandbox, you can select a card on file in your wallet and confirm your address on file. The card on file should be one of the test cards above.



When you press "Continue", a payment.success event will be triggered. The VISA Checkout API will retrieve the payment object that includes the encrypted PAN and other payment details and the JavaScript executing in the client will send all of this information along with Vantiv specific information to Vantiv's eProtect service using sendToEprotect() as shown in the code example above.


The eProtect response if successful should contain the paypageRegistrationID, the Bin and additional information as shown below.


On successful completion of a transaction, eProtect should populate the (normally hidden) HTML INPUT fields in your browser with the paypageRegistrationID and Bin as shown.



The additional fields on the forms will also be populated with details returned by eProtect. You can check the Vantiv eProtect Solution for Visa Checkout documentation for details about the fields below.




Processing an Authorization or Sale

The procedure above explains the process for vaulting the payment credentials obtained from Visa Checkout with Vantiv in exchange for a Registration ID. Once you have the Registration ID, the next step is to create an Authorization or Sale transaction and process that request through one of Vantiv's payment processing front-ends.


Typically these authorizations are initiated from a merchant's server. Unfortunately, we can't provide a complete example here, because the methods for creating an Authorization or Sale using the Registration ID vary by Vantiv Platform.


You can read about this in detail and review examples for both ISO 8583 and 610 the Vantiv Enterprise eProtect Integration Guide.


Examples are provided for the following Vantiv platforms:


  • Vantiv  Systems - ISO 8583 message format
  • Vantiv  Systems - 610 message format
  • Host-to-Host Format (HHMI)


If you are coding using Vantiv's ISO 8583 specification, you may also want to refer to the Vantiv ISO 8583 specification.


If you are coding to Vantiv's 610 message format, you may want to refer to the Vantiv 610 Interface Reference Guide.


While we focus on paypageRegistrationId in our example above (representing the method of payment) developers will need to pass other information to the payment front end. This includes details like the Authorization amount, Cardholder address details, Card type, Card expiration date and more. These data items should already be readily accessible to the developer because they are either determined prior to checkout or returned as values by Visa Checkout or eProtect .


Visa Checkout Operation with eProtect from within a Mobile App


The second mode of operation is using Visa Checkout from within an iOS or Android OS mobile app.


From the perspective of processing an Authorization or Sale with one of Vantiv's front-ends, the process when using a mobile app is identical to a website, but the method of interacting with eProtect to exchange the Visa Checkout payment credentials for the eProtect low-value token is different.


Rather than relying on a JavaScript library running in the client browser to post values to eProtect, developers will need to POST values to the eProtect end point themselves from within the Mobile app.


Using VISA Checkout with eProtect from a mobile App is covered in detail in these two manuals.


These manuals provide details of how to call eProtect from within your mobile app.