# Adapters

In a typical payment transaction flow, the transaction initiates on the terminal with certain parameters such as transaction parameters (Amount, Currency, etc), EMV Parameters (Card Cryptogram, TVR, etc) and merchant store parameters. Payment terminal sends them to the Poynt Cloud encoded in the Poynt data structure. Some of these parameters are used internally by Poynt Cloud for certain controls before sending the message to the acquirer.

Some others are sent to acquirer for online authorization or settlement. With the growing number of acquirers and acquirer message protocols, the main need was to enable partners/acquirers to define their mapping from the Poynt data structure to acquirer message format to give them more control and flexibility. With these Adapters any partner and acquirer can integrate Poynt terminals to their acquiring host without need of Poynt’s development on the Poynt Cloud platform.

Let's dive in!

# Adapter Framework

Poynt Cloud Adapter Framework is an extensible framework for integrating Poynt terminals with external payment processing systems.

The framework grew out of a desire by the Poynt engineering team to make it possible for any developers working with terminals running Poynt OS to connect it with any payment processing backend. Payment processing integration is something we do often enough that we want to let-go some of our knowledge and share it with everyone.

The Framework is made up of three main parts:

• IDE

• Adapter

• Runtime

Developers use the IDE to define and code their Adapters. Adapters is nothing more than a combination of configurations and Javascript codes written by the developer. Adapters are deployed into the runtime environment in order to process traffic coming from Poynt terminals.

Key features of Poynt Cloud Adaptor development platform is as following :

• Support of various authorization message formats (VISA Gen II, ISO8583, JSON, XML, etc)

• Support of all major transaction types (Authorization, Capture, Void, Refund, Card Verification, Balance Inquiry, etc) & custom transaction types

• Support of different settlement modes (Terminal, automatic-host, terminal-initiated host)

• Ability to define custom merchant on-boarding data (installments, tax, etc)

• Built in multi-hosts routing support

• Hardware agnostic

# Adapter Platform Modules

The diagram below shows the architecture of the Lego platform.

# IDE

The IDE is a web-based editor located at lego-ci.poynt.net (opens new window). Developers will need to create a developer accounts in order to login. Once logged in, they can create adapters and share it with other developers belonging to the same organization the developers is in.

# Adapters

Adapters are what developers create. It consists of basic configurations like the external system hostname/IP, connection protocol, encoding protocols, etc. It also contains Javascript codes that the developer write in order to map data from Poynt terminals to the external system like PAN, amount, track data, etc...

# Proxy-Adapters

Proxy-Adapters are used for multi-host feature which requires you to build a lego adapter for each host you want to use. Then create a “Proxy” adapter that sits on top of your other adapters

So for example, if an acquirer wants to connect to a different host for Amex transactions, there are three (3) adapters: Proxy Adapter, Amex Adapter, and Non-Amex Adapter (rest of scheme).

# Runtime

Adapters are nothing more than configuration and code. It needs a runtime environment to execute in. By default, the IDE is connected to the Poynt development cloud, which contains an instance of the Runtime environment. When developers edit/update their adapter, they can directly deploy/reload it into this runtime environment.

In the Runtime, the main engine is the Script Execution Engine with 2 handlers : Request Handler and Response Handler.

Request Handler is the portion of the Script Execution Engine that converts the Poynt data structure to acquirer request message. Request Handler gets the transaction request from the POS terminal along with Poynt data structure. It finds the adapter assigned to the merchant, chooses the operation based on the type of the transaction request and converts the Poynt data structure to Acquirer authorization request message. The authorization message is sent to the acquirer.

Response Handler is the portion of the Script Execution Engine that converts the acquirer response message to the Poynt data structure. Response Handler gets the authorization response from the acquirer. It finds the matching adapter for the merchant, maps acquirer authorization response message to the related response fields in the Poynt data structure. The Poynt data structure is sent to the POS terminal.

Once an adapter is deemed production ready, it will need to be submitted for approval to be deployed into the Production Runtime, which is hosted on a separate environment.