### Спарювання пристрою [#pair-a-device]
Спарювання призначає пристрою Tapaya `externalDeviceId`, щоб ви могли знайти його у списку пристроїв
і вибрати його як цільовий під час запуску платежу.
#### Призначення з вашого застосунку [#assign-from-your-app]
Ваш застосунок викликає на пристрої функцію Accept SDK, яка призначає йому `externalDeviceId`. Використовуйте
той самий ідентифікатор у кожному виклику Cloud Accept API для цього пристрою.
#### Сканування QR-коду [#scan-a-qr-code]
Мерчант відкриває процес спарювання в Tapaya Platform, яка показує QR-код для
`externalDeviceId`, що призначається. Мерчант сканує його застосунком Tapaya для мерчантів на цільовому
пристрої, і застосунок завершує спарювання.
### Обмін на токен доступу [#exchange-an-access-token]
Обміняйте свій Server Secret Token і `merchantToken` мерчанта на токен доступу за допомогою
`POST /ecr/auth`. `merchantToken` надсилається лише тут; усі подальші виклики надсилають тільки
`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"
}
```
| Код | Опис |
| ----- | --------------------------------------------- |
| `401` | API-токен недійсний або строк його дії минув. |
| `403` | Доступ до мерчанта заборонено. |
**Оновлюйте токен до настання `expiresAt`.** Викличте `POST /ecr/auth/refresh` із поточним, ще дійсним
`accessToken` у заголовку `Authorization`. Ендпоінт повертає те саме тіло з новим токеном; збережіть його
і надалі використовуйте саме його.
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 }
```
| Код | Опис |
| ----- | ---------------------------------------------------------------------------------------------------------- |
| `401` | Токен доступу недійсний, строк його дії минув або його відкликано. Отримайте новий через `POST /ecr/auth`. |
| `403` | Ви більше не маєте доступу до мерчанта. Новий токен не видається. |
### Пошук готового пристрою [#find-a-ready-device]
Отримайте список пристроїв мерчанта за допомогою `GET /ecr/devices`. Додайте `?connected=true`, щоб виключити
відключені пристрої, або отримайте один пристрій за допомогою `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"
}
```
Надсилайте платежі лише на пристрій, у якого `availability` має значення `ready`. Список є лише знімком стану:
доступність перевіряється повторно під час надсилання, тож навіть пристрій у стані `ready` може
відхилити запит. Див. [Доступність пристрою](#device-availability).
### Надсилання запиту на платіж [#submit-a-payment-request]
Надішліть суму на пристрій за допомогою `POST /ecr/payment-requests`. Tapaya зберігає запит і
сповіщає пристрій, який показує екран оплати.
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
```
**Параметри:**
| Поле | Тип | Обов'язкове | Опис |
| ------------------ | --------- | ----------- | ------------------------------------------------------------- |
| `externalDeviceId` | `string` | ✓ | Спарений пристрій, який має показати платіж. |
| `amount` | `integer` | ✓ | Сума в найменшій одиниці валюти (`12500` дорівнює 125,00 Kč). |
| `tipAmount` | `integer` | | Чайові в найменшій одиниці валюти. |
| `currency` | `string` | ✓ | Код валюти ISO 4217. |
| `paymentToken` | `string` | | Наявний платіж, до якого слід прив'язати запит. |
```json title="202 Accepted"
{
"requestId": "...",
"status": "pending",
"paymentToken": null,
"expiresAt": "2026-01-13T16:30:59Z"
}
```
`202 Accepted` означає, що Tapaya зберегла запит. Це не означає, що пристрій його отримав
або що клієнт заплатив. Усе, що завершиться збоєм пізніше, надійде вам як зміна статусу.
**Зробіть повторні спроби безпечними.** Заголовок `Idempotency-Key` є обов'язковим. Повторне використання ключа з тим самим тілом
повертає початковий запит замість запуску другого платежу; повторне використання з іншим
тілом повертає `409 idempotency_conflict`. Прив'яжіть ключ до продажу та спроби, як у
`order-1042-attempt-1`.
### Відстеження результату [#track-the-result]
Стежте за [статусами](#request-statuses) запиту за допомогою вебхуків або періодично опитуйте
`GET /ecr/payment-requests/{requestId}`. Щойно запит досягне статусу `payment_created`, відповідь міститиме
`paymentToken`, а про перебіг самого платежу повідомлятимуть події `payment.updated`.
Щоб отримувати вебхуки, зареєструйте свій HTTPS-ендпоінт за допомогою `POST /ecr/webhook-subscriptions` або задайте
для мерчанта callback URL і типи подій у 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` повертається лише під час створення підписки. Збережіть його в захищеному місці; він
знадобиться вам для перевірки підпису вхідних вебхуків.
Підписка належить інтегратору й мерчанту, а не токену доступу, тому вона зберігається після
оновлення токена. Відповідайте на кожну подію кодом `2xx`, щойно приймете її.
Вебхуки є сповіщеннями, а не підтвердженням оплати, і вебхук може надійти із запізненням або не надійти зовсім. Ніколи
не закривайте продаж лише на підставі вебхука:
* **Коли вебхук надходить,** підтвердьте кінцевий результат через API, наприклад за допомогою запиту з розділу
[Отримання даних платежу](/platform-api/reporting#retrieve-payment-details).
* **Коли вебхук не надходить** протягом тайм-ауту, що відповідає вашому процесу оплати, і не пізніше
`expiresAt` запиту, викличте `GET /ecr/payment-requests/{requestId}`, щоб дізнатися його
поточний статус, а потім підтвердьте платіж через API, як описано вище.