Thanh toán qua máy POS

Bộ API cho phép đối tác tạo đơn hàng thanh toán (POS bill) và đẩy trực tiếp xuống máy POS. Khách hàng thanh toán ngay trên máy POS bằng thẻ hoặc mã QR; kết quả thanh toán được TINGEE gửi về qua Webhook.

Đối tác hỗ trợ

Hiện tại API chỉ hỗ trợ máy POS Payoo (bankBin = "PAYOO").

Trước khi bắt đầu

• Base URL: https://uat-open-api.tingee.vn (UAT) · https://open-api.tingee.vn (PROD)
• Xác thực: Mọi request cần gửi kèm các header x-client-id, x-request-timestamp và chữ ký x-signature (HMAC SHA512). Xem Hướng dẫn lấy API Key & sinh chữ ký.
• Kết quả: API luôn trả về HTTP 200, kiểm tra trường code (00 = thành công). Xem Danh sách mã lỗi.

Quy trình tích hợp

1

Liên kết máy POS

Gọi API Tạo/Liên kết số tài khoản với bankBin = "PAYOO" và accountNumber là mã thiết bị POS Payoo. Máy POS được liên kết ngay, không cần bước xác thực OTP.

2

Tạo đơn hàng

Gọi API create-pos-bill với số tiền cần thanh toán. Đơn hàng được đẩy xuống máy POS và trả về billId.

3

Khách hàng thanh toán trên máy POS

Khách hàng quẹt thẻ hoặc quét mã QR trên máy POS.

4

Nhận kết quả

TINGEE gửi Webhook thanh toán khi giao dịch thành công. Có thể tra cứu trạng thái bằng get-detail-pos-bill hoặc hủy đơn bằng update-pos-bill.

Sơ đồ luồng

Luồng thanh toán qua máy POS

← Vuốt ngang để xem thêm →

Đối soát giao dịch

Webhook thanh toán của đơn hàng POS có các đặc điểm sau:

Trường	Giá trị
bankBin	PAYOO
accountNumber, vaAccountNumber	Mã thiết bị POS.
transactionCode	billId của đơn hàng.
content	Rỗng.
additionalData	Chứa billId, qrAccount (= billId) và extraInfo (nếu có khi tạo đơn).

Dùng billId để đối chiếu kết quả thanh toán với đơn hàng đã tạo.

Danh mục API

Chức năng	Method	Endpoint
Tạo đơn hàng POS	POST	/v1/create-pos-bill
Chi tiết đơn hàng POS	GET	/v1/get-detail-pos-bill
Hủy đơn hàng POS	PUT	/v1/update-pos-bill