POS terminal payments

This set of APIs lets partners create payment orders (POS bills) and push them directly to a POS terminal. The customer pays right on the POS terminal by card or QR code; TINGEE sends the payment result via Webhook.

Supported partners

The API currently only supports Payoo POS terminals (bankBin = "PAYOO").

Before you start

• Base URL: https://uat-open-api.tingee.vn (UAT) · https://open-api.tingee.vn (PROD)
• Authentication: Every request must include the x-client-id and x-request-timestamp headers and the x-signature signature (HMAC SHA512). See How to get an API Key & generate the signature.
• Result: The API always returns HTTP 200; check the code field (00 = success). See Error codes.

Integration flow

1

Link the POS terminal

Call the Create/Link account number API with bankBin = "PAYOO" and accountNumber set to the Payoo POS device code. The POS terminal is linked immediately, with no OTP verification step.

2

Create an order

Call the create-pos-bill API with the amount to pay. The order is pushed to the POS terminal and a billId is returned.

3

Customer pays on the POS terminal

The customer swipes a card or scans the QR code on the POS terminal.

4

Receive the result

TINGEE sends the payment Webhook when the transaction succeeds. You can look up the status with get-detail-pos-bill or cancel the order with update-pos-bill.

Flow diagram

POS terminal payment flow

← Swipe to see more →

Transaction reconciliation

The payment Webhook for a POS order has the following characteristics:

Field	Value
bankBin	PAYOO
accountNumber, vaAccountNumber	POS device code.
transactionCode	The order's billId.
content	Empty.
additionalData	Contains billId, qrAccount (= billId) and extraInfo (if provided when creating the order).

Use billId to match the payment result with the order you created.

API catalog

Function	Method	Endpoint
Create POS order	POST	/v1/create-pos-bill
POS order details	GET	/v1/get-detail-pos-bill
Cancel POS order	PUT	/v1/update-pos-bill