Getting started with Vantiv’s DevHub

Registering your application with DevHub

Regardless of your coding development environment, the next step is to create an application profile in DevHub. You can create as many application profiles as you want, edit them prior to certification, or remove them anytime. When you create a new application, you are invited to provide information about the application including the payment features you plan to support.

Some of the payment features shown in Figure 2 are required, but others are optional and can be selected depending on your needs. In its initial release, DevHub is supporting eCommerce, card-not-present transactions only, but the platform is designed to support all types of payment transactions. A future release will support card-present payments as well.

DevHub supports a number of optional features that they may not have seen in other payment APIs including capabilities like Pre-paid Indicators, Affluence Indicators, Issuer Country, Account Updater functionality and more. These are important capabilities that developers can leverage in their applications to make their software more appealing to merchants. These features can help merchants reduce fraud and chargebacks, and maximize revenue per transaction.

As an example, recognizing a pre-paid card can be useful to a merchant. These cards have a finite limit, and merchants will want to be cautious accepting these cards for recurring payment transaction. Similarly, indicators of the affluence of a client based on their purchase history may help a merchant decide whether a customer is a good risk to do business with.

If you are unsure of what payment features to include in your application, you can accept the defaults. You can always add or remove features later on. Once you’ve selected the payment features you want to use, you’ll be provided with Test Credentials as shown in Figure 3.

Accepting your first payment with DevHub

Vantiv’s DevHub uses a RESTful JSON API to accept and process transactions. All transactions follow essentially the same format making the environment easy to integrate with. The only things that will change are the variables sent and received in the JSON requests and acknowledgements and the URL endpoints used. To make this clear, let’s look at a few examples.

We will start by authorizing a payment transaction (using one of the test cases built into DevHub) and we will “capture” the transaction so that funds are moved from the cardholders issuing bank to our merchant account. With DevHub, we are using a test account, so the movement of money is simulated. You can authorize and capture as many transactions as you’d like while building and testing your code.

Depending on the programing language you are using, you can consult http://github.com/vantiv for coding examples. To keep things simple, we’ll run our examples directly from the Linux shell using cURL.

Authorizing a payment using DevHub

A sample JSON transaction authorizing a payment is shown in Figure 4. Here we authorize a payment for $101.00 against a provided VISA card. The license string that we looked at earlier has been stored in a local file called .license_id so that the code is not dependent on a specific license.

Explanations of the meanings of the various JSON variables in Figure 4 are provided in the DevHub VDP Data Definitions document available in the Documentation section of the DevHub portal. After running the script shown in Figure 4, DevHub will respond with the JSON formatted response shown in Figure 5. Note the response of “000” and the response message of “Approved” indicating that the Authorization request was successful. Readers familiar with Vantiv’s eCommerce API (formerly known as LitleXML) will recognize the format of the litleOnlineResponse structure in the DevHub response. Additional information is provided in the response including the fraudResult. The meanings of the codes can be found in Vantiv’s LitleXML reference, but an avsResult of “01” means that the nine digit zip code matched, and the cardValidationResult of “M” means that the CVV2/CVC2/CID code was a match providing us with confidence that the cardholder was in possession of the card.

Also important in the response is the tokenResponse structure, provided back to us because we submitted a credit card number as a part of our Authorization request. The tokenResponseCode of 802 means that this card was previously registered, and that a token already exists for it. We are provided back the card type, the BIN (bank identification number) as well as a PaymentAccountID that should be used in future transactions in place of the actual card number. A companion Vantiv solution called eProtect can be used with DevHub to securely convert a real card number into a low-value token from the browser before the card number is ever passed to the eCommerce application. Using eProtect, developers can avoid the need for applications to store or process card data helping reduce PA-DSS scope. The id field, returned as a part of the authorizationResponse is important since we will use this in the next step to capture the authorized transaction.
Capturing the previously authorized transaction
To capture the authorization above, we submit a similar JSON formatted message, except we send the message to the authorizationCompletion endpoint as shown in Figure 6. As part of the Transaction identifier, we provide the TransactionID associated with the previous Authorization as well as the amount that we want to capture in the TransactionAmount field. In this example, even though we authorized up to $101.00 against the card, we are ultimately only capturing $10.00.

After we send the JSON in figure 6, we should receive the response shown in figure 7. The details of the capture operation are included in the captureResponse part of the message. In this example, our capture operation was successful. Note that there are some nice features embedded in the captureResponse like the ability to detect and prevent multiple captures against a single authorization. This is happening here because we ran the transactions repeatedly in the course of testing the application.

These are basic examples, but once you can perform operations like the ones above, all other payment transactions follow the same pattern. All that changes are the RESTful API endpoints and the JSON syntax associated with each type of transaction. Some of the core transaction types supported by DevHub include:

• Authorization
• Capture
• Sale
• Credit
• Void
• Authorization Reversals
• Tokenization

Certifying your payment application

Once you’ve become comfortable with the mechanics of running transactions against DevHub, the next step is to test and certify your application. Unlike some other payment providers, Vantiv provides a self-service facility for validating the functionality of payment applications built into the DevHub portal. Depending on the payment features selected, a series of tests will be visible as shown in Figure 8. Tests are divided into categories, and each test will simulate specific test cases that developers will need to handle to prove proper functionality of their application. These test cases will ultimately help the developer understand the payment platform better and write higher quality code. For example, in the case of an Authorization, test cases include scenarios involving insufficient funds, invalid card numbers, mis-matched addressed during AVS verification and invalid CVV2/CVC2/CID codes.