AdvanPay - POS Integration using REST API

Introduction

This guide aims to serve as a primer into the task of integrating your PoS with a Keonn AdvanPay.

Integrating with our reader comes basically in two forms, using the REST API and using the TCP socket 3177. 

• • The REST API: is the main way to control and manage the reader and poll it for data.

  • The TCP Socket: is the main way to subscribe to the reader and receive real time data.

This guide wants to show how integrate with the device to carry out the most common operations.

Initial Setup

Typically the reader only needs to be configured once, but it can be configured whenever necessary as long as the RF is off.

1. Identify the reader (Device IP, Device ID)

2. Set ADVANPAY_PAYMENT read mode (Changing the read mode section)

3. Configure the reader (Loading configuration section)

4. Repeat step 2 with ADVANPAY_RETURN and then ADVANPAY_READMODE if necessary.

5. Save to persist configuration across reboots (Saving configuration section)

(The Read modes can be configured using REST API instead)

Common operations

Changing the read mode

HTTP PUT http://ip/device/activeReadMode with the name of the read mode (case sensitive) in the body. 

Examples using CURL would be: 

curl -X PUT http://{ip}/device/activeReadMode -d "ADVANPAY_PAYMENT"

curl -X PUT http://{ip}/device/activeReadMode -d "ADVANPAY_RETURN"

curl -X PUT http://{ip}/device/activeReadMode -d "ADVANPAY_READONLY"

Starting and stopping the device

Start: HTTP GET http://ip/device/start

Stop: HTTP GET http://ip/device/stop

Examples:

curl http://{ip}/device/start

curl http://{ip}/device/stop

Saving configuration

To make configuration persist across device reboots it must be saved, the REST operation is:

curl http://{ip}/device/confAllSave

Wait for confirmation from the POS before sending tag data to the cloud

If we inform the next flags in Advanced JSON Config in SCloudService: {"payQueueTTL":3,"payConfirmationNeeded":true}, once a tag is read (in any of the pay's read modes) it will wait for the POS confirmation of that tag's EPC before sending the data to the cloud.  

If the EPC is not confirmed in less than "payQueueTTL", the EPC will expire.

HTTP GET http://ip/device/POSAPI/send/{EPC} 

Examples using CURL would be: 

curl http://ip/device/POSAPI/send/{EPC}

Other interesting REST operations

• Epc can be changed upon payment/return

• Configuration can be exported/imported

• Raw reads can be polled instead of using TCP

• Apply a filter to only accept tags with ceirtain EPC pattern.

Read real time data

The reader offers the TCP socket 3177 as the main way to read real time data from the reader.

To open a test connection to the socket simple type nc <dev_ip> 3177 in a Linux/MacOS/WSL terminal or setting up PuTTy this way in any major desktop Operating System.

The reader yields data in a HTTP-y way, by first giving a header with structure (notice the empty line at the end):

ADVANNET/1.1

Content-Length:0

Content-Type:text/xml

This is an example of a heartbeat message: has no content but by receiving it AdvanNet informs that it's still on and reachable.

Device start event:

ADVANNET/1.1

Content-Length:476

Content-Type:text/xml

<?xml version="1.0" encoding="UTF-8"?>

<eventMessage>

  <type>eventMessage</type>

  <ts>1612521348306</ts>

  <status>OK</status>

  <event>

    <class>com.keonn.advannet.impl.event.DefaultAdvanNetEvent</class>

    <type>ADVANNET_INFO</type>

    <typeclass>com.keonn.spec.event.AdvanNetEvent$AdvanNetEventType</typeclass>

    <advanNetId>AdvanNet-instance-34:03:de:a2:87:f1--1</advanNetId>

    <msg>Device[AdvanPay-cf-eu-120] started in mode: ADVANPAY_PAYMENT</msg>

  </event>

</eventMessage>

Payment Event:

ADVANNET/1.1

Content-Length:515

Content-Type:text/xml

<?xml version="1.0" encoding="UTF-8"?>

<deviceEventMessage>

  <type>deviceEventMessage</type>

  <ts>1612521351103</ts>

  <status>OK</status>

  <event>

    <class>TAG_EVENT</class>

    <type>TAG_ADPY_PAYMENT</type>

    <typeclass>com.keonn.spec.event.DeviceEvent$EventType</typeclass>

    <deviceId>AdvanPay-cf-eu-120</deviceId>

    <epc>3036014fac0aa297ddffbe7c</epc>

  </event>

  <deviceId>AdvanPay-cf-eu-120</deviceId>

</deviceEventMessage>

TCP Output can be configured in JSON format as well.
You will find more event types in the TCP section in https://wiki.keonn.com/rfid-systems/payment-systems/advanpay-120