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:
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
# Adapter Platform Modules
The diagram below shows the architecture of the Lego platform.
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.
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).
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.