POS Integration via PayProtocol
To communicate with the PayServer from your POS Software you can use the PayProtocol (P3),
which is designed specifically for easy payment integration. This protocol is
platform and technology agnostic, all you need is a TCP socket, which is available
on all major platforms.
We also offer the PayClient, a ready-made
library that implements the protocol in C#/.NET. If your system uses these
technologies we highly recommend you use this library instead of doing your
own implementation. The PayClient provides all the functionality of the protocol
encapsulated in a easy-to-use, native API.
Message Transport
The P3 protocol itself only defines the messages exchanged between the client and the
server. The server supports two transport layer protocols used to deliver the
messages: WebSocket and framed TCP.
P3 over WebSocket
This option makes use of the modern and high-level WebSocket protocol. This protocol is based on top
of TCP so it is technically possible on all platforms, however, depending on
your technology and language it might not have an available implementation.
An advantage of this protocol is that, if it is already implemented in your
technology, it provides a much simpler integration for you. It is also
implemented in all modern web browsers, so you can use it to integrate a
card reader with your web-based POS Software or eCommerce System.
The WebSocket protocol the PayServer uses adheres to WebSocket 13 specification (RFC 6455),
which defines the initial handshake, message framing and fragmentation as used by
the server. We recommend using a pre-made implementation library rather than
implementing WebSocket from scratch; if such library is not available for your
technology it is better to use our second transport option.
P3 over TCP
This option makes use of the relatively low-level TCP protocol,
which is natively implemented on all major platforms and should be
available from all languages and technologies. However, because of
its simplicity, it takes more of an effort to implement.
On the TCP level all messages are simply a stream of bytes. To distinguish the messages,
length prefix framing is used to specify the length of the message in big-endian
order. This framing results in each application message being prefixed by a 4 byte
header. The application message itself is a UTF-8 encoded JSON.
Therefore, to read a message, you would first read four bytes of
the input stream as an unsigned integer X. Then you would read the
next X bytes of the actual application message, which you process
as a UTF-8 string. Similarly, to send a message, you first
calculate its size in bytes and send this value as a 4 byte
unsigned integer, then the message. A standard caveat of this
transport protocol is that the message may be split into multiple
packets and not received at the same time.
Messaging Pattern
The P3 protocol is based on the classic request-response messaging pattern. For each
request the client sends it can expect exactly one corresponding response from the
server. However, contrary to some other popular protocols, the response doesn't
have to be returned right away or before another request. Some requests, such as a
request to execute a transaction, may produce long running operations. For these
cases the protocol makes an extension to the request-response model. The protocol
includes:
- Update messages, which inform the client about the state of the operation before the final response arrives.
- , and action messages, which prompt the client to send another request in order to continue with the process.
Every request the client sends needs to contain a
tag
, which allows you to keep track which update,
action or response message is related to the request you've sent.
Your implementation needs to provide a unique tag
value for each request you make. We suggest generating a UUID for
this.For example when running an
EXECUTE_TRANSACTION_REQUEST
with tag
ea99bacc-c05e-4cb5-b2c1-858172124873
, you will receive
this tag in all subsequent EXECUTE_TRANSACTION_UPDATE
,
EXECUTE_TRANSACTION_ACTION
and
EXECUTE_TRANSACTION_RESPONSE
messages.Further, when you request a transaction, you send in the path to
the device which you wish to use for the transaction.
Message Structure
The messages defined by the P3 protocol are formatted in
JSON.
Message Header
Every message includes the same header fields:
{ "type": "<message type>", "resource": "path/to/device", "tag": "a required tag which will be present in all updates/responses for this request and must be generated by integrator", // ... }
All possible message types are described in detail on a separate
message specification page.
The
resource
specifies a configured
resource for which is the message intended. If there is none the
field is null
or can be omitted.As mentioned, there are four categories of messages:
request
, response
,
update
and action
. The
response messages also include status and error information in the
header:{ // ... "status": "OK|ERROR", "error": { "type": "error type", "message": "error message", "developerMessage": "information which may be useful to the integrating developers" } // ... }
The
status
is OK
if the message was processed by the server and correctly executed.
If there was something wrong with the execution, the message status
is ERROR
.The
error
field is non-null if and only
if the status
of the response is
ERROR
. In some cases, there may still be a
response body to according to the message type; for example, if you
are executing a transaction which failed at a later stage, you can
find the transaction data inside the message body.Message Data
The data for each message is embedded in a field with the same
name as the message type, but converted to lowerCamelCase. For
example, if you send a
LOGIN_MERCHANT_REQUEST
you should also populate field
loginMerchantResponse
in the message JSON
object. Similarly, when the server sends a LOGIN_MERCHANT_RESPONSE
you can expect only the
loginMerchantResponse
field of the message
to contain the message type specific data.Message Specification
All the message types and their message data supported by the P3
protocol are specified in message
specification.
Protocol Usage
Usage of the protocol and sample message flows are shown in protocol usage.