Cloud Accept API

Ghép nối thiết bị

Việc ghép nối gán một externalDeviceId cho thiết bị Tapaya, để bạn có thể tìm thấy thiết bị khi liệt kê danh sách thiết bị và chỉ định thiết bị đó khi bắt đầu một khoản thanh toán.

Gán từ ứng dụng của bạn

Ứng dụng của bạn gọi một hàm của Accept SDK trên thiết bị để gán externalDeviceId cho thiết bị. Hãy dùng cùng một định danh trong mọi lệnh gọi Cloud Accept API cho thiết bị đó.

Quét mã QR

Merchant mở quy trình ghép nối trong Tapaya Platform, nơi hiển thị một mã QR cho externalDeviceId cần gán. Merchant quét mã bằng ứng dụng merchant của Tapaya trên thiết bị đích, và ứng dụng sẽ hoàn tất việc ghép nối.

Đổi lấy access token

Đổi Server Secret Token của bạn và merchantToken của merchant lấy một access token bằng POST /ecr/auth. merchantToken chỉ được gửi ở đây; mọi lệnh gọi sau đó chỉ gửi Authorization: Bearer <accessToken>.

curl -X 'POST' 'https://api.tapaya.com/ecr/auth' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer REPLACE_ME' \
-d '{
        "merchantToken": "unique_merchant_id_from_your_db"
    }'

{
    "accessToken": "...",
    "tokenType": "Bearer",
    "expiresAt": "2026-01-13T16:30:59Z"
}

Gia hạn trước expiresAt. Gọi POST /ecr/auth/refresh với accessToken hiện tại, vẫn còn hiệu lực, trong header Authorization. Endpoint này trả về cùng nội dung phản hồi với một token mới; hãy lưu token đó và dùng nó từ đó trở đi.

curl -X 'POST' 'https://api.tapaya.com/ecr/auth/refresh' \
-H 'Authorization: Bearer ACCESS_TOKEN'

Tìm thiết bị sẵn sàng

Liệt kê các thiết bị của merchant bằng GET /ecr/devices. Thêm ?connected=true để loại bỏ các thiết bị đã ngắt kết nối, hoặc lấy một thiết bị bằng GET /ecr/devices/{externalDeviceId}.

curl 'https://api.tapaya.com/ecr/devices/till-01' \
-H 'Authorization: Bearer ACCESS_TOKEN'

{
    "externalDeviceId": "till-01",
    "name": "Front counter",
    "connected": true,
    "availability": "ready",
    "lastSeenAt": "2026-01-13T16:30:59Z",
    "updatedAt": "2026-01-13T16:30:59Z"
}

Chỉ gửi thanh toán tới thiết bị có availability là ready. Danh sách chỉ là bản lưu (snapshot) tại một thời điểm: tình trạng sẵn sàng được kiểm tra lại khi bạn gửi yêu cầu, nên một thiết bị ready vẫn có thể từ chối yêu cầu. Xem Tình trạng sẵn sàng của thiết bị.

Gửi yêu cầu thanh toán

Gửi số tiền tới một thiết bị bằng POST /ecr/payment-requests. Tapaya lưu yêu cầu và thông báo cho thiết bị, thiết bị sẽ hiển thị màn hình thanh toán.

curl -X 'POST' 'https://api.tapaya.com/ecr/payment-requests' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Idempotency-Key: order-1042-attempt-1' \
-d '{
        "externalDeviceId": "till-01",
        "amount": 12500,
        "tipAmount": 500,
        "currency": "CZK"
    }'

Tham số:

{
    "requestId": "...",
    "status": "pending",
    "paymentToken": null,
    "expiresAt": "2026-01-13T16:30:59Z"
}

Đảm bảo thử lại an toàn. Header Idempotency-Key là bắt buộc. Dùng lại một key với cùng nội dung yêu cầu sẽ trả về yêu cầu ban đầu thay vì bắt đầu khoản thanh toán thứ hai; dùng lại key đó với nội dung khác sẽ trả về 409 idempotency_conflict. Hãy gắn key với giao dịch bán hàng và lần thử, như trong order-1042-attempt-1.

Theo dõi kết quả

Theo dõi yêu cầu qua các trạng thái của nó bằng webhook, hoặc thăm dò GET /ecr/payment-requests/{requestId}. Khi yêu cầu đạt payment_created, phản hồi sẽ chứa paymentToken, và các sự kiện payment.updated báo tiến trình của chính khoản thanh toán.

Để nhận webhook, hãy đăng ký endpoint HTTPS của bạn bằng POST /ecr/webhook-subscriptions, hoặc đặt URL callback và các loại sự kiện cho merchant trong Tapaya Platform.

curl -X 'POST' 'https://api.tapaya.com/ecr/webhook-subscriptions' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-d '{
        "url": "https://integrator.example.com/webhooks/tapaya",
        "events": ["payment_request.updated", "payment.updated"]
    }'

{
    "subscriptionId": "...",
    "url": "https://integrator.example.com/webhooks/tapaya",
    "events": ["payment_request.updated", "payment.updated"],
    "signingSecret": "..."
}

Một đăng ký thuộc về bên tích hợp và merchant, không thuộc về access token, nên nó vẫn được giữ nguyên khi gia hạn token. Hãy phản hồi mỗi sự kiện bằng mã 2xx khi bạn đã chấp nhận sự kiện đó.