gjsissons

Payment APIs Demystified - Five Common Types

Blog Post created by gjsissons on Apr 18, 2017

As developers know, APIs come in all shapes and sizes.   In this article, I’ll look at how APIs are commonly used in payments and offer a framework for classifying some of Vantiv’s more popular payment APIs.

 

Webopedia defines an API as follows:

 

“An Application Programming Interface (API) is a set of routines, protocols and tools for building software applications.  An API specifies how software components should interact.” 

 

Obviously, this is a broad definition. It covers everything from opening an OS file to accessing hardware features on a graphics card.  In payments, we can frame APIs more narrowly.  Most payment applications are transactional, and involve sending and retrieving messages to and from remote systems across dedicated links or IP networks.  Examples include authorizing a payment, setting up a subscription, or initiating a bank transfer from a mobile app.

 

Because most payment transactions are message-oriented, protocols loom large in payments.  Below is a description of five types of APIs common in payment applications.

 

1. Message formats & protocols

 

The core protocol used in payments is the ISO 8583 standard.  Although it meets the definition of an API, it is better described as a protocol or message format.  ISO 8583 messages may travel from a merchant terminal or ATM, through to a merchant acquirer, through to card networks, and ultimately to card issuing banks.  The standard is quite detailed and coding ISO transactions requires a sophisticated understanding of how payment networks operate.

 

ISO 8583 format message are usually sent over TCP via socket connections, but it can operate over other transports as well including dial-up, direct links or X.25 networks.  Most developers probably won’t code ISO 8583 messages directly unless they are working at a large retailer, bank, payment processor or payment gateway.

 

Vantiv provides Enterprise retailers and high-volume merchants with the ability to code directly to our core payment systems using the ISO 8583 standard.  When ISO messages are sent across the wire they are very dense and look like a stream of characters with many bit-mapped or binary coded fields.  A parsed view of a partial ISO 8583 message is shown below.  These types of message provide developers with complete flexibility and access to all network features, but they are difficult to code to.  To make integrations easier, Vantiv also exposes more consumable APIs, message specs and SDKs to developers (discussed below) where we manage the translation to ISO 8583 behind the scenes.

 

partial ISO message.JPG

 

2. SOAP XML Web Services

 

SOAP refers to the Simple Object Access Protocol.  SOAP is a W3C XML based standard that allows organizations to publish interfaces such that they are discoverable and platform agnostic.  Interfaces are described using WSDL, the web-services description language.  SOAP Web Services are most commonly provided over HTTPS, however SOAP can run over other transports as well.  The protocol provides an envelope, a set of encoding rules for expressing application defined data types, and a convention for representing procedure calls and responses.  SOAP can be a little verbose, because it was designed to have a lot of functionality.  Several Vantiv platforms expose SOAP interfaces including Vantiv’s core platforms, Vantiv’s eCommerce platform, Vantiv’s Express Platform and the MercuryPay platform.

 

A nice property of a SOAP API is that it is self-documenting.  For example, visiting the endpoint of the MercuryPay SOAP API (https://w1.mercurycert.net/ws/ws.asmx) in a browser shows the available SOAP methods and documents how they are called.

 

3. HTTP/S POST APIs

 

While SOAP is widely accepted as an industry standard, for applications that don’t need all the functionality of SOAP, simpler HTTP POST APIs have become popular.  With these types of APIs, developers create their own HTTP requests and send messages directly to a network endpoint.  Although we refer to them as HTTP APIs, it is standard practice to send traffic over an SSL/TLS encrypted HTTPS connection.

 

HTTP POST APIs can take several forms – they can send and receive JSON, XML or simple key-value pairs.  Popular tools for interacting with HTTP endpoints include cURL and Postman.  Authentication can be performed in the HTTP header or credentials can be included in the message payload itself.  While POST APIs can support any type of payload, JSON is often preferred because it is lightweight, flexible, and easily parsed.

 

This is popular style of coding is also supported by multiple Vantiv APIs including Vantiv’s Express API, Vantiv’s eCommerce API, and various management APIs such as the Merchant Management API used by Payment Facilitators.  This style of API is also used by Apple Pay iOS Apps to simplify Apple Pay integrations.

 

A cURL example showing the use of Vantiv’s eProtect HTTPS POST API is shown here.

 

curl -H "Content-Type: application/x-www-form-urlencoded" -d \
"paypageId=a2y4o6m8k0&reportGroup=67890&orderId=cust_order&id=12345&accountNumber=5454545454545454&cvv=111" \
https://request-prelive.np-securepaypage-litle.com/LitlePayPage/paypage

 

The endpoint accepts PCI sensitive data like card credentials or a token and responds with a JSON payload containing a low-value token that can be used in lieu of payment credentials:

 

{
"paypageRegistrationId":"Z01GbG9qcTRKdXA4MXhKbkNoRGZNYkRsK1JKZG5oS3ZPcWJmYkRlbHUxV1VjM1UzdnpLcHY1ZUhDeU1uWm4wZQ\u003d\u003d",
"bin":"545454",
"type":"MC",
"firstSix":"545454",
"lastFour":"5454",
"litleTxnId":"82920346960773572",
"orderId":"cust_order",
"response":"870",
"responseTime":"2017-04-12T12:33:01",
"message":"Success",
"reportGroup":"67890","id":"12345"
}

 

The eProtect service can either be called directly (as above) or for eCommerce applications a JavaScript library loaded into your web-page and optionally served from Vantiv via an iFrame can call the service on your behalf to avoid exposing your application to PCI sensitive data.

 

4. REST APIs

 

REST stands for Representational State Transfer.  It is not an API unto itself, rather it is an architectural style for expressing an HTTP-based API.  APIs that adhere to this coding style are said to be RESTful.  Developers who understand how to code to HTTP POST APIs (above) will automatically understand RESTful APIs because the mechanics of interacting with them are the same.  The main difference is in how the API is organized.  A RESTful API borrows from object-oriented design principles and typically provides multiple URL endpoints that correspond to objects being manipulated.

 

For example, if I have a URL endpoint /Charge representing a charge to a credit or debit card, I might create or update a charge against the endpoint using a POST method or retrieve one or more charges using the GET method.  Manipulating a specific instance of a charge would involve using an end-point like /Charge/<Charge-id> in a well-designed REST API.  I might have other entities such as Customers, Disputes or Tokens that I interact with in the same way using common verbs like create, update, delete and list.

 

Additional JSON or XML can be sent with each HTTP request to provide more instruction to the endpoint at the discretion of the API designer.  There are often “shades of grey” between HTTP POST APIs and REST APIs depending on how fully the API designer has embraced REST design principles.

 

Vantiv exposes multiple RESTful APIs as well to various payment platforms.   Examples are the REST API to MercuryPay, and the triPOS cloud API below, both designed around REST principles.

 

tirpos.png

 

5. SDKs

 

Software Development Kits are client-side libraries that abstract and simplify coding to the above interfaces.   SDK’s are usually programming language aligned.  For example a Microsoft developer building a point of sale application will appreciate a C#/.NET SDK easily consumable with Visual Studio.  eCommerce developers might prefer a PHP or Java SDK that makes it easier to formulate payment transactions from within a web application.  The SDKs are responsible for generating and parsing the various messages formats described above.  It’s important to understand that it is ultimately XML or JSON formatted messages (or in some cases ISO messages) that are sent across the wire regardless of whether a developer codes to an SDK or a protocol specification.

 

SDKs are useful, but they present a double-edged sword. They simplify coding, but also introduce a new source of complexity in the form of a client-side software component that their application depends on.  Also, some SDKs may not expose all the advanced capabilities offered by a payment platform, meaning that for some functions developers will need to code to the message specification.

 

Opinions vary, but some developers will prefer to code directly to a protocol specification (like an XML spec or RESTful API) to take unknowns out of the equation and avoid dependencies that could impact their release cycles.

 

Vantiv offers several SDKs including C#, PHP, JAVA, Ruby and Python SDKs for our eCommerce platform. A sample credit card authorization using Vantiv’s eCommerce Java SDK is shown below

 

import com.litle.sdk.*; 
import com.litle.sdk.generate.*; 

//Authorization 
public class AuthExample { 
   public static void main(String[] args) { 
       Authorization auth = new Authorization(); 
       auth.setOrderId("1"); 
       auth.setAmount(10010L); 
       auth.setOrderSource(OrderSourceType.ECOMMERCE); 
       Contact billToAddress = new Contact(); 
       billToAddress.setName("John Smith"); 
       billToAddress.setAddressLine1("1 Main St."); 
       billToAddress.setCity("Burlington"); 
       billToAddress.setState("MA"); 
       billToAddress.setCountry(CountryTypeEnum.US); 
       billToAddress.setZip("01803-3747"); 
       auth.setBillToAddress(billToAddress); 
       CardType card = new CardType(); 
       card.setNumber("3750*******0003"); 
       card.setExpDate("0119"); 
       card.setCardValidationNum("349"); 
       card.setType(MethodOfPaymentTypeEnum.AX); 
       auth.setCard(card); 

       AuthorizationResponse response = new LitleOnline().authorize(auth); 
       //Display Results 
       System.out.println("Response: " + response.getResponse()); 
       System.out.println("Message: " + response.getMessage()); 
       System.out.println("Litle Transaction ID: " + response.getLitleTxnId()); 
   } 
} 

 

 

The Bottom Line

 

When it comes to payments there are a great many APIs, but most fall into one of the categories described above.  Once you master the mechanics of coding to on API in a category, other APIs in the same family become accessible and easy to use.

 

For a summary of the various APIs and resources available to eCommerce developers, sign-up to Vantiv O.N.E. and visit our eCommerce Guides and Resources area.

 

Developers building In-store, Integrated point-of-sale platforms can visit a similar collection of API documentation in our Point-of-Sale documentation area.

Outcomes