Push Payment to Devices

POST 
/openapi/v1/devices/payments/push

Đẩy lệnh thanh toán trực tiếp xuống thiết bị vật lý tại quầy thu ngân — hiển thị trên máy POS hoặc phát loa thông báo Soundbox.

Hệ thống nhận yêu cầu, giải mã payload, xác định thiết bị đích rồi publish bản tin xuống MQTT broker. Thiết bị nhận lệnh gần như tức thời.

Mã hóa: payload request phải được bọc trong trường data và mã hóa AES-256-CBC (hex). Response không mã hóa — trả về JSON thuần { code, message }.

Bất đồng bộ: code = "00" chỉ xác nhận lệnh đã được đẩy xuống broker thành công, không đảm bảo thiết bị đã xử lý xong giao dịch. Kết quả giao dịch cuối cùng nhận qua IPN/webhook.

Payload trước khi mã hóa

POS (Smart POS):

{
  "serial_no": "00059012710",
  "order_id": "0129210912",
  "amount": 150000,
  "type": "pos",
  "action": "SALE",
  "request_id": "00017-058-0001",
  "extra_data": { "Atom1": "F4" }
}

Soundbox:

{
  "serial_no": "SB-001234",
  "amount": 150000,
  "qr_string": "00020101021138550010A000000727...",
  "type": "soundbox"
}

Bảng trường dữ liệu

Trường	Kiểu	Bắt buộc	Mô tả
type	String	✅	Loại thiết bị nhận lệnh: pos hoặc soundbox
serial_no	String	✅	Số serial (mã định danh duy nhất) của thiết bị
amount	Integer	✅ (trừ action = SETTLEMENT)	Số tiền (VNĐ). Với type = pos phải > 0; với type = soundbox chấp nhận >= 0
order_id	String	✅ nếu type = pos (trừ action = SETTLEMENT)	Mã hóa đơn — tối đa 16 ký tự
qr_string	String	✅ nếu type = soundbox	Chuỗi nội dung mã QR lấy từ API Create QR
action	String	✕	Chỉ dùng với type = pos. Mặc định SALE. Xem bảng bên dưới
action_data	String	✅ nếu action là VOID hoặc PREAUTH_COMPLETE	Chỉ dùng với type = pos. Mã tham chiếu giao dịch gốc (retrievalRefNo)
trace_no	String	✕	Chỉ dùng với type = pos. Số trace của giao dịch gốc, đi kèm VOID / PREAUTH_COMPLETE
txn_id	String	✕	Chỉ dùng với type = pos. Mã giao dịch gốc, đi kèm PREAUTH_COMPLETE
request_id	String	✕	Chỉ dùng với type = pos. Mã định danh yêu cầu phía đối tác. Bỏ trống thì hệ thống tự sinh UUID
extra_data	Object	✕	Chỉ dùng với type = pos. Dữ liệu bổ sung, chuyển nguyên vẹn xuống thiết bị. Mặc định {}

Gửi action kèm type = "soundbox" sẽ bị từ chối với mã 04.

Bảng action (chỉ áp dụng cho type = pos)

action	Ý nghĩa	Trường bắt buộc kèm theo
SALE (mặc định)	Thanh toán thường	order_id, amount
MOTO	Thanh toán không xuất trình thẻ	order_id, amount
PREAUTH	Tạm giữ hạn mức (pre-authorization)	order_id, amount
PREAUTH_COMPLETE	Hoàn tất giao dịch tạm giữ	order_id, amount, action_data; nên gửi kèm trace_no, txn_id
VOID	Hủy giao dịch / giải tỏa Preauth	order_id, amount, action_data; nên gửi kèm trace_no
SETTLEMENT	Tổng kết lô giao dịch trong ngày	Không cần order_id và amount

Bảng mã trạng thái (code)

Code	Mô tả	HTTP	Khi nào trả về
00	Success	200	Đã đẩy lệnh xuống thiết bị thành công
01	Authenticate error	401	Thiếu/sai thông tin xác thực, không xác định được CIF
02	The requested URL was not found on the server	404	Sai đường dẫn endpoint
03	Unknown error	200	Không publish được lệnh xuống thiết bị, hoặc lỗi nội bộ
04	Bad request	400	Payload sai định dạng, thiếu trường bắt buộc, type/action không hợp lệ

Trường hợp code = "03" do không publish được xuống thiết bị vẫn trả HTTP 200 (giữ tương thích ngược với đối tác đang chạy production). Đối tác phải kiểm tra code, không chỉ dựa vào HTTP status.

Request

Responses

200

Yêu cầu được xử lý — kiểm tra trường code để biết kết quả

400

Payload không hợp lệ hoặc thiếu trường bắt buộc

401

Lỗi xác thực — thiếu/sai token hoặc không xác định được CIF