Tham chiếu Terminal

Đối tượng, status, lỗi và event webhook cho Terminal.

Hãy đọc tổng quan và trang tích hợp trước.

Đối tượng Reader

Trường	Kiểu	Mô tả
id	string	Mã reader.
label	string	Tên mà thu ngân gọi thiết bị này. Văn bản tự do.
status	enum	ACTIVE, BLOCKED, COMPROMISED hoặc REVOKED.
connection_status	enum	online hoặc offline.
created_at	timestamp	Thời điểm reader đăng ký lần đầu.
updated_at	timestamp	Thời điểm bản ghi reader thay đổi gần nhất.

Status của reader

Reader có một trong bốn status.

Status	Ý nghĩa
ACTIVE	Reader có thể nhận thanh toán.
BLOCKED	Reader tạm thời dừng.
COMPROMISED	Reader dừng vĩnh viễn vì lý do an ninh.
REVOKED	Reader dừng vĩnh viễn theo yêu cầu.

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.

Status kết nối

Giá trị	Ý nghĩa
online	Reader gửi tín hiệu gần đây.
offline	Reader chưa gửi tín hiệu gần đây.

Đối tượng Terminal

Trường	Kiểu	Mô tả
id	string	Mã Terminal.
merchant_id	string	Merchant mà Terminal này thuộc về.
location_id	string, có thể null	Location mà Terminal này giao dịch.
name	string	Tên mà merchant gọi Terminal này.
type	enum	softpos.
status	enum	pending, active hoặc deleted.
capabilities	array	Các phương thức thanh toán Terminal có thể nhận.
permissions	object	Những việc Terminal được phép làm.

Status của Terminal

Status	Ý nghĩa
pending	Terminal đã đăng ký nhưng chưa sẵn sàng nhận thanh toán.
active	Terminal có thể nhận thanh toán.
deleted	Merchant đã rút Terminal này.

Mục capability

Trường	Kiểu	Mô tả
name	enum	card_present, napas_qr hoặc visa_qr.
status	enum	active, pending, restricted hoặc unsupported.

Chỉ capability active được chấp nhận. Terminal nhận một phương thức thanh toán khi capability của phương thức đó là active.

Permissions

Trường	Kiểu	Mô tả
accept_payment	bool	Terminal có thể nhận một thanh toán.
export_invoice	bool	Terminal có thể xuất hóa đơn.
view_history	bool	Terminal có thể xem lịch sử thanh toán.

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.

Event webhook

Event của PaymentIntent

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.

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.