### Ghép nối thiết bị [#pair-a-device]
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 [#assign-from-your-app]
Ứ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 [#scan-a-qr-code]
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 [#exchange-an-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
`.
cURL
TypeScript
```bash
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"
}'
```
```typescript
const res = await fetch('https://api.tapaya.com/ecr/auth', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${process.env.TAPAYA_SECRET_TOKEN}`,
},
body: JSON.stringify({ merchantToken: 'unique_merchant_id_from_your_db' }),
});
const { accessToken, expiresAt } = await res.json();
```
```json title="200 OK"
{
"accessToken": "...",
"tokenType": "Bearer",
"expiresAt": "2026-01-13T16:30:59Z"
}
```
| Mã | Mô tả |
| ----- | --------------------------------------- |
| `401` | API token không hợp lệ hoặc đã hết hạn. |
| `403` | Không được phép truy cập merchant. |
**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
TypeScript
```bash
curl -X 'POST' 'https://api.tapaya.com/ecr/auth/refresh' \
-H 'Authorization: Bearer ACCESS_TOKEN'
```
```typescript
const res = await fetch('https://api.tapaya.com/ecr/auth/refresh', {
method: 'POST',
headers: { Authorization: `Bearer ${accessToken}` },
});
const renewed = await res.json(); // { accessToken, tokenType, expiresAt }
```
| Mã | Mô tả |
| ----- | -------------------------------------------------------------------------------------------------- |
| `401` | Access token không hợp lệ, đã hết hạn hoặc đã bị thu hồi. Đổi lấy token mới bằng `POST /ecr/auth`. |
| `403` | Bạn không còn quyền truy cập merchant. Không có token mới nào được cấp. |
### Tìm thiết bị sẵn sàng [#find-a-ready-device]
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
TypeScript
```bash
curl 'https://api.tapaya.com/ecr/devices/till-01' \
-H 'Authorization: Bearer ACCESS_TOKEN'
```
```typescript
const res = await fetch('https://api.tapaya.com/ecr/devices/till-01', {
headers: { Authorization: `Bearer ${accessToken}` },
});
const device = await res.json();
const canPay = device.availability === 'ready';
```
```json title="200 OK"
{
"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ị](#device-availability).
### Gửi yêu cầu thanh toán [#submit-a-payment-request]
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
TypeScript
```bash
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"
}'
```
```typescript
const res = await fetch('https://api.tapaya.com/ecr/payment-requests', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${accessToken}`,
'Idempotency-Key': 'order-1042-attempt-1',
},
body: JSON.stringify({
externalDeviceId: 'till-01',
amount: 12500, // 125.00 Kč
tipAmount: 500, // 5.00 Kč
currency: 'CZK',
}),
});
const { requestId } = await res.json(); // 202 Accepted
```
**Tham số:**
| Trường | Kiểu | Bắt buộc | Mô tả |
| ------------------ | --------- | -------- | --------------------------------------------------------------------- |
| `externalDeviceId` | `string` | ✓ | Thiết bị đã ghép nối sẽ hiển thị khoản thanh toán. |
| `amount` | `integer` | ✓ | Số tiền theo đơn vị nhỏ nhất của loại tiền tệ (`12500` là 125,00 Kč). |
| `tipAmount` | `integer` | | Tiền tip theo đơn vị nhỏ nhất của loại tiền tệ. |
| `currency` | `string` | ✓ | Mã tiền tệ ISO 4217. |
| `paymentToken` | `string` | | Một khoản thanh toán hiện có để gắn yêu cầu vào. |
```json title="202 Accepted"
{
"requestId": "...",
"status": "pending",
"paymentToken": null,
"expiresAt": "2026-01-13T16:30:59Z"
}
```
`202 Accepted` nghĩa là Tapaya đã lưu yêu cầu. Điều đó không có nghĩa là thiết bị đã nhận được yêu cầu
hay khách hàng đã thanh toán. Mọi lỗi xảy ra sau đó sẽ được gửi tới bạn dưới dạng thay đổi trạng thái.
**Đả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ả [#track-the-result]
Theo dõi yêu cầu qua các [trạng thái](#request-statuses) 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
TypeScript
```bash
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"]
}'
```
```typescript
const res = await fetch('https://api.tapaya.com/ecr/webhook-subscriptions', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${accessToken}`,
},
body: JSON.stringify({
url: 'https://integrator.example.com/webhooks/tapaya',
events: ['payment_request.updated', 'payment.updated'],
}),
});
const { subscriptionId, signingSecret } = await res.json(); // 201 Created
```
```json title="201 Created"
{
"subscriptionId": "...",
"url": "https://integrator.example.com/webhooks/tapaya",
"events": ["payment_request.updated", "payment.updated"],
"signingSecret": "..."
}
```
`signingSecret` chỉ được trả về khi tạo đăng ký (subscription). Hãy lưu trữ nó an toàn; bạn
cần nó để xác minh chữ ký của các webhook gửi đến.
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 đó.
Webhook là thông báo, không phải bằng chứng thanh toán, và một webhook có thể đến muộn hoặc hoàn toàn không đến. Không bao giờ
chốt giao dịch bán hàng chỉ dựa vào webhook:
* **Khi có webhook đến,** hãy xác nhận kết quả cuối cùng qua API, ví dụ bằng
[Truy xuất chi tiết thanh toán](/platform-api/reporting#retrieve-payment-details).
* **Khi không có webhook nào đến** trong khoảng thời gian chờ phù hợp với quy trình thanh toán của bạn, và không muộn
hơn `expiresAt` của yêu cầu, hãy gọi `GET /ecr/payment-requests/{requestId}` để đọc
trạng thái hiện tại, sau đó xác nhận khoản thanh toán qua API như trên.