Receipt request · Developer Docs

The communication between sale app and the POS app is via JSON messages. To initiate a payment, you make a PosRequest from the POS app. This is then sent to the sale app on APOLLO, where the shopper can then present their card, or wallet and complete the payment.

Endpoint

The current version of API lives at http://{terminal_ip}:8080/sp/v1/payment

Make a payment

The example below shows how you would make a HK$30.00 payment using the posRequest:

Make a POST request to the endpoint, specify the following in the header:
- Content-Type: application/json in header
In the message body:
- posId: your POS unique ID
- messageId: your unique ID generated by the POS app for this transaction
- transactionType: the requested transaction type
- originalTerminalTransactionId: required for the void, tip-adjust or auth completion. it is the returned TransactionId from the previous posResponse, this unique ID is generated by the payment core.
- requestAmount: the value of the transaction
- currency: the currency in ISO-4217 Alpha-3 code format, eg. HKD, USD
- preferredEntryMode: the preferred entry mode for the payment app to start the transaction (CARD | QR_SCAN | QR_PRESENT | CASH | DEFAULT)

curl -X POST \
  http://10.1.1.1:8080/sp/v1/payment \
  -H 'Content-Type: application/json' \
  -d '{
    "posId": "12345",
    "messageId": "23y418jisdhf939h3asdf9a",
    "transactionType": "SALE",
    "originalTerminalTransactionId": "",
    "requestAmount": 30,
    "currency": "HKD",
    "preferredEntryMode": "CARD"
}'

On APOLLO, it switches to the payment app for transaction processing. At this point, the merchant can still change the payment method.
The customer present their card, cash or QR wallet.
Follow the instructions on the APOLLO screen to complete the transaction.
When the transaction is done, the transaction status (Approved | Declined | Error) is displayed on the APOLLO screen and it returns a JSON response to the POS app as following.

{
  "messageId": " 926",
  "posId": "1234",
  "responseResult": "SUCCESS",
  "terminalTransactionId": "530736b9b58b7977441c3a8448650af660ce3ae8",
  "transactionPrintData": {
    "authenticationMethod": "UNKNOWN_METHOD",
    "baseAmount": 30.0,
    "cardData": {
      "aid": "a0000000031010",
      "appName": "VISA CREDIT",
      "atc": "0001",
      "cardholderName": "CARDHOLDER NAME",
      "maskedExpiry": "XX/XX",
      "maskedPan": "XXXXXXXXXXXX0010",
      "tc": "fd412c3c15f3a44",
      "tsi": "e800",
      "tvr": "0080800000"
    },
    "currency": "HKD",
    "dateTime": "2019-04-25T10:46:10+0000",
    "entryMode": "CHIP",
    "paymentBrand": "VISA",
    "paymentInstrumentType": "CARD",
    "posReferenceId": "926",
    "shopAddress": "",
    "shopEmail": "",
    "shopLogo": "",
    "shopName": "Shop Name",
    "shopPhone": "",
    "totalAmount": 30.0,
    "transactionId": "530736b9b58b7977441c3a8448650af660ce3ae8",
    "transactionStatus": "APPROVED",
    "transactionType": "SALE"
  }
}

If you want to go back to your app when finish payment, we suggest using moveTaskToFront after get the response in your app.

val activityManager = applicationContext.getSystemService(Context.ACTIVITY_SERVICE) as ActivityManager
activityManager.moveTaskToFront(taskId,0)

For more example, checkout the API Examples Refer to API Reference for the full list of fields