Payment request · Developer Docs

Using the payment to make payment request to the APOLLO and let it take care of the card/ QR wallet handling and process with the host.

Endpoint

http://{{terminal_ip}}:8080/sp/v1/payment

Supported payment

The supported payments might vary depending on different acquiring host

The APOLLO is versatile for taking different kinds of payment. Below table is a summary of what payment method and transaction type available on the APOLLO.

Transaction	Sale	Tip adjust	Auth	Offline sale	Auth comp	Refund
Card ¹	✓	✓	✓	✓		✓
Card (UnionPay)	✓	✓	✓		✓	✓
QR Wallet ²	✓					✓
Octopus	✓
EPS	✓
Cash	✓

Void transaction	Void sale	Void auth	Void offline	Void auth comp	Void refund
Card ¹	✓		✓		✓
Card (UnionPay)	✓	✓		✓	✓
QR Wallet ²	✓				✓
Octopus
EPS
Cash

¹ Card: Visa, Mastercard, JCB, American Express

² QR Wallet: Alipay, WeChat Pay, FPS, UnionPay QR

Make a payment request

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

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, eg. SALE
- requestAmount - the requested total amount of the transaction
- currency - the currency in ISO-4217 Alpha-3 code format, eg. HKD
- preferredEntryMode- (optional) the preferred entry mode for the payment app to start the transaction

Refer to API reference - PosRequestData for the detail data structure

cURL

Android (Kotlin)

curl --request POST '{{baseUrl}}/{{module_spectra}}/{{apiVersion}}/payment' \
--header 'Content-Type: application/json' \
--data '{
  "messageId":{{messageId}},
  "posId": {{posId}},
  "transactionType": "SALE",
  "requestAmount": 50,
  "currency": {{currency}},
  "preferredInstrument": {{preferredInstrument}},
  "forceAcquirer": {{forceAcquirer}}
}'

TODO()

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.
APOLLO displays the transaction status (result). It then returns the JSON response to the POS as following.

{
  "messageId": "23y418jisdhf939h3asdf9a",
  "posId": "12345",
  "responseCode": 0,
  "responseResult": "SUCCESS",
  "terminalTransactionId": "1b1ae97ed00aa14a0b539967b682f1beb58a3197",
  "transactionResult": {
    "acquirerId": "HostSim-VMJ",
    "acquirerMid": "000001001001122",
    "acquirerTid": "59802730",
    "appName": "Debit Mastercard",
    "approvalCode": "102454",
    "createTime": "2020-10-22T02:24:54+0000",
    "currency": "HKD",
    "entryMode": "CONTACTLESS",
    "maskedPan": "************7128",
    "paymentMethod": "MASTER",
    "poiReferenceId": "1b1ae97ed00aa14a0b539967b682f1beb58a3197",
    "posReferenceId": "23y418jisdhf939h3asdf9a",
    "totalAmount": 30,
    "trace": 36,
    "tranStatus": "APPROVED",
    "tranType": "SALE",
    "...": "..."
  }
}

If you want to go back to your app when finish payment, we suggest using moveTaskToFront after getting 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