Tích hợp Terminal

Trang này trình bày các bước phía server. Hãy đọc tổng quan trước.

Trước khi bắt đầu

Hãy xác nhận các điều sau với Ops hoặc account manager:

Đã có Account, Merchant, ít nhất một Location và một Terminal.
Có ít nhất một reader đã được duyệt cho Terminal đó.
Bạn có một API key.

Thu một khoản thanh toán

Chọn một reader. Liệt kê các reader đã được duyệt cho Terminal. Chọn reader có status là ACTIVE và connection_status là online.
bash
```
curl "https://bn.cake.vn/api/terminal/readers?status=ACTIVE" \
  -H "Bn-Api-Key: $BN_SECRET_KEY"
```
Endpoint công khai để liệt kê reader theo Terminal đang nằm trong lộ trình. Hiện tại, hãy liên hệ account manager để xác nhận reader nào đã được duyệt cho một Terminal.
Tạo PaymentIntent. Không đặt confirm. PaymentIntent phải ở trạng thái requires_payment_method.

Gửi PaymentIntent tới reader.

bash

curl -X POST "https://bn.cake.vn/api/terminal/readers/$READER_ID/process_payment_intent" \
  -H "Bn-Api-Key: $BN_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_intent_id": "YOUR_PAYMENT_INTENT_ID",
    "process_config": { "enable_customer_cancellation": true }
  }'

Response trả về một reader_action có status in_progress. Response này xác nhận reader đã nhận action. Response này không xác nhận thanh toán.

Đọc kết quả. Lắng nghe các webhook ở mục kế tiếp. Nếu cần dự phòng, hãy truy vấn PaymentIntent.

Webhooks

Theo dõi thanh toán bằng các event của PaymentIntent. Các event này giống với thanh toán online.

Event	Mô tả
`payment_intent.status.succeeded`	Thanh toán đã hoàn tất.
`payment_intent.status.requires_payment_method`	Thanh toán bị từ chối. Hãy gửi lại PaymentIntent tới reader.
`payment_intent.status.canceled`	PaymentIntent đã bị hủy.

Để theo dõi chính reader, hãy dùng các event của reader action.

Event	Mô tả
`reader_action.status.succeeded`	Bahn đã ủy quyền thanh toán.
`reader_action.status.failed`	Thanh toán bị từ chối, hết thời gian chờ, hoặc reader mất kết nối. Hãy đọc `failure_code`, `failure_message` và `failure_decline_code`.
`reader_action.status.canceled`	Bạn hoặc khách hàng đã hủy action.

Xem Sự kiện để biết đầy đủ payload.

Bị từ chối và thử lại

Sau khi bị từ chối, PaymentIntent quay về requires_payment_method. Hãy gửi lại đúng PaymentIntent đó tới reader. Không tạo PaymentIntent mới. Không phân tích message trong code. Hãy dùng code và decline_code. Giá trị code lấy từ last_payment_error của PaymentIntent, ví dụ card_declined, insufficient_funds, expired_card hoặc processing_error.

Hủy một action

bash

curl -X POST "https://bn.cake.vn/api/terminal/readers/$READER_ID/cancel_action" \
  -H "Bn-Api-Key: $BN_SECRET_KEY"

Bahn chấp nhận lệnh gọi này ngay cả khi thanh toán đang được ủy quyền. Hãy kiểm tra status của PaymentIntent trước khi bạn hoàn tất đơn hàng. Đặt enable_customer_cancellation là true để cho phép khách hàng hủy trên reader.

Lỗi

Mã lỗi	Loại	HTTP status	Nguyên nhân	Việc cần làm
`terminal_reader_busy`	`api_error`	500	Reader đang chạy một action.	Chờ đến khi action kết thúc. Hoặc gọi `cancel_action`.
`terminal_reader_timeout`	`api_error`	500	Reader không phản hồi kịp thời.	Thử lại request.
`intent_invalid_state`	`invalid_request_error`	400	PaymentIntent không ở trạng thái `requires_payment_method`.	Tạo PaymentIntent mới.
`resource_missing`	`invalid_request_error`	400	Reader không có action nào đang chạy.	Kiểm tra reader trước khi hủy.

Bahn đặt HTTP status theo loại lỗi: card_error và invalid_request_error trả về 400, authentication_error trả về 401, idempotency_error trả về 409, rate_limit_error trả về 429, và api_error trả về 500.

Nếu reader vẫn ở in_progress sau khi mất kết nối, hãy gọi cancel_action để đặt lại reader.

Quản lý reader

Tác vụ	Request
Liệt kê	`GET /api/terminal/readers`
Truy vấn	`GET /api/terminal/readers/{id}`
Đổi tên	`POST /api/terminal/readers/{id}` kèm `label`
Xóa	`DELETE /api/terminal/readers/{id}`

Reader có một trong các status sau: ACTIVE, BLOCKED, COMPROMISED hoặc REVOKED. Reader chỉ rời ACTIVE theo một chiều. Để dùng lại thiết bị, hãy duyệt thiết bị đó thành một reader mới. Khi xóa, reader chuyển sang REVOKED. Các khoản thanh toán trước đó của reader vẫn được lưu lại.

Bước tiếp theo

Hoạt động thay cho một merchant đã kết nối nếu bạn xây platform. Nếu không, hãy xem tham chiếu.

Tích hợp Terminal ​

Trước khi bắt đầu ​

Thu một khoản thanh toán ​

Webhooks ​

Bị từ chối và thử lại ​

Hủy một action ​

Lỗi ​

Quản lý reader ​

Bước tiếp theo ​