In this tutorial, we provide a step by step example showing how developers can get started coding to the Express platform. You can code Express payment transactions in your language of choice.
The Express API is most commonly used for card present (CP) applications but may be used for eCommerce card not present (CNP) applications as well.
Examples are available at http://github.com/elementps.
What you’ll need
Express is a service-side API designed to work with your choice of languages and tools. You simply need a platform that can open a secure sockets connection to an internet host. The examples below were tested on Windows and Linux, but should work on any platform that supports cURL, a popular solution for interacting with server-side web interfaces without the need to write code.
Most Linux distributions include cURL. If not, it can be easily installed using tools like yum or apt-get, depending on your distribution. On Windows, you can obtain cURL from multiple sources. We used the cURL implementation included in Cygwin in our examples from Cygwin.com. Cygwin is a free open source Unix-like environment for Windows. If using Cygwin, you will need to make sure you include cURL as part of the Cygwin installation as it is not selected by default.
Although not needed for this example, a full explanation of the parameters included in each payment transaction can be found in the Express API guide at http://www.elementps.com/portals/0/Express-Interface-Specification.pdf.
Aside from a client environment supporting cURL, the only other thing you’ll need is a free test account.
Obtaining a free test account
Obtaining your free test account for Vantiv’s Express API is easy. Simply visit the URL below, register, and your credentials will be sent you via email.
You’ll be provided with four identifiers that you’ll need to retain and make use of in the examples below.
There are multiple ways to interface with Express including SOAP web-services interfaces and hosted payments. In our example we simply post XML transactions over a secure HTTP interface to an endpoint provided by Vantiv at https://certtransaction.elementexpress.com.
Authorizing a transaction
With Express API credentials in hand, we’re now able to authorize a payment transaction. It is a common practice to pre-authorize payments in cases where the final payment amount is not known in advance such as when checking into a hotel, renting a car or purchasing fuel at an automated pump. Prior authorization makes sure that the customer has funds available in advance of a purchase.
Run the command below to open a connection to Vantiv’s test endpoint and pre-authorize a payment amount of $10.00 using a customer’s credit card. You will need to modify the example to include your own test credentials supplied by Vantiv in the previous step.
Important note: In this, and all examples shown here, please do not use real credit card numbers. Please use only the test credit card numbers supplied by Vantiv. The last four digits of the card have intentionally been replaced with “XXXX” in the example above. Before the example will actually work, you will need to replace XXXX above with the final digits of the card 6781. We have avoided spelling out the card number in our examples lest fraud filters of various types mistakenly flag this post as containing real, sensitive cardholder data.
If successful, you should see a response like the one below (although cURL may not format the XML response depending on your environment).
Express provides details of the transaction in the response including the Card Logo and a masked version of the card that can be displayed to the customer following the authorization. Developers will want to retain the TransactionID above for the next step – completing the payment transaction.
Completing a payment transaction
To complete a previously authorized payment transaction, you can use a CreditCardAuthorizationCompletion operation. Note that you will need to provide the specific TransactionID received with the authorization response in Step 3 above. The number will be unique to your own authorization transaction.
Paste the example below into your local environment after inserting your own account credentials and the previously authorized TransactionID.
If the completion of the sale is successful, you will see a response like the following:
You should retain the transactionID of theCreditCardAuthorizationCompletation transaction in case it is necessary to provide a refund or credit in future.
Issuing a refund
In some cases, you may need to issue a refund or provide a credit to a customer’s credit card. Vantiv provides two transactions types for this purpose – A CreditCardReturn and a CreditCardCredit. A CreditCardReturn is used to provide a refund referencing the TransactionID associated with the Authorization Completion operation. Returns are only valid within 90 days of a transaction. A CreditCardCredit can be used to credit a card without referencing the TransactionID, in which case the developer will need to provide information identifying the card.
In the example below, we fully refund the previous transaction by referencing the TransactionID, eliminating the need to pass sensitive card data through the encrypted channel once more.
Assuming the CreditCardReturn is successful, you will see a response similar to the one below:
The Express API has many rich features and is able to process many payment sources including Credit, Debit and eCheck payments in both CP and CNP scenarios for a variety of industry use cases. Some additional capabilities include:
- Tokenization – a solution that substitutes sensitive cardholder PAN data for non-PCI sensitive tokens, helping the merchant reduce risk by avoiding the need to store and handle sensitive card data.
- Hosted Payments – a solution that removes the software vendor from PA-DSS scope, by shifting the responsibility to Vantiv for handling card data.
- Recurring transactions – allowing cards to be billed on a period basis based on a specified recurrence pattern.
- triPOS – a client-side software solution that interfaces to Express and simplifies interfacing to a variety of POS peripherals while simultaneously reducing PA-DSS scope for developers.