### Spárování zařízení [#pair-a-device]
Párování přiřadí zařízení Tapaya `externalDeviceId`, takže je můžete najít při výpisu zařízení
a zacílit na ně při spuštění platby.
#### Přiřazení z vaší aplikace [#assign-from-your-app]
Vaše aplikace zavolá na zařízení funkci Accept SDK, která mu přiřadí `externalDeviceId`. Ve všech
voláních Cloud Accept API pro toto zařízení používejte stejný identifikátor.
#### Naskenování QR kódu [#scan-a-qr-code]
Obchodník otevře v Tapaya Platform postup párování, který zobrazí QR kód pro přiřazované
`externalDeviceId`. Obchodník jej naskenuje aplikací Tapaya pro obchodníky na cílovém
zařízení a aplikace párování dokončí.
### Výměna za přístupový token [#exchange-an-access-token]
Vyměňte svůj Server Secret Token a `merchantToken` obchodníka za přístupový token pomocí
`POST /ecr/auth`. `merchantToken` se odesílá pouze zde; všechna další volání odesílají jen
`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"
}
```
| Kód | Popis |
| ----- | ------------------------------------------------------ |
| `401` | Neplatný API token nebo API token s prošlou platností. |
| `403` | Přístup k obchodníkovi není povolen. |
**Obnovte token před `expiresAt`.** Zavolejte `POST /ecr/auth/refresh` s aktuálním, stále platným
`accessToken` v hlavičce `Authorization`. Endpoint vrátí stejné tělo s novým tokenem; uložte si jej
a nadále používejte už jen ten nový.
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 }
```
| Kód | Popis |
| ----- | ------------------------------------------------------------------------------------------------------- |
| `401` | Přístupový token je neplatný, vypršel nebo byl zneplatněn. Získejte nový výměnou přes `POST /ecr/auth`. |
| `403` | K obchodníkovi již nemáte přístup. Nový token se nevydá. |
### Vyhledání připraveného zařízení [#find-a-ready-device]
Zařízení obchodníka vypište pomocí `GET /ecr/devices`. Přidáním `?connected=true` vynecháte
odpojená zařízení; jedno konkrétní zařízení načtete pomocí `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"
}
```
Platby posílejte pouze na zařízení, jehož `availability` je `ready`. Výpis je jen momentální snímek:
dostupnost se znovu ověřuje při odeslání, takže i zařízení ve stavu `ready` může požadavek
odmítnout. Viz [Dostupnost zařízení](#device-availability).
### Odeslání požadavku na platbu [#submit-a-payment-request]
Částku odešlete na zařízení pomocí `POST /ecr/payment-requests`. Tapaya požadavek uloží a
upozorní zařízení, které zobrazí platební obrazovku.
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
```
**Parametry:**
| Pole | Typ | Povinné | Popis |
| ------------------ | --------- | ------- | ------------------------------------------------------- |
| `externalDeviceId` | `string` | ✓ | Spárované zařízení, které má platbu zobrazit. |
| `amount` | `integer` | ✓ | Částka v nejmenší jednotce měny (`12500` je 125,00 Kč). |
| `tipAmount` | `integer` | | Spropitné v nejmenší jednotce měny. |
| `currency` | `string` | ✓ | Kód měny podle ISO 4217. |
| `paymentToken` | `string` | | Existující platba, ke které se má požadavek připojit. |
```json title="202 Accepted"
{
"requestId": "...",
"status": "pending",
"paymentToken": null,
"expiresAt": "2026-01-13T16:30:59Z"
}
```
`202 Accepted` znamená, že Tapaya požadavek uložila. Neznamená to, že jej zařízení zaznamenalo
ani že zákazník zaplatil. Cokoli, co selže později, se k vám dostane jako změna stavu.
**Zajistěte bezpečné opakování požadavků.** Hlavička `Idempotency-Key` je povinná. Opětovné použití klíče se stejným tělem
vrátí původní požadavek místo spuštění druhé platby; opětovné použití s jiným tělem
vrátí `409 idempotency_conflict`. Svažte klíč s prodejem a pokusem, například
`order-1042-attempt-1`.
### Sledování výsledku [#track-the-result]
Sledujte požadavek přes jeho [stavy](#request-statuses) pomocí webhooků, nebo pravidelně volejte
`GET /ecr/payment-requests/{requestId}`. Jakmile požadavek dosáhne stavu `payment_created`, odpověď obsahuje
`paymentToken` a průběh samotné platby hlásí události `payment.updated`.
Chcete-li přijímat webhooky, zaregistrujte svůj HTTPS endpoint pomocí `POST /ecr/webhook-subscriptions`, nebo
pro obchodníka nastavte callback URL a typy událostí v 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` se vrací pouze při vytvoření odběru. Bezpečně si jej uložte; budete
jej potřebovat k ověření podpisu příchozích webhooků.
Odběr patří integrátorovi a obchodníkovi, nikoli přístupovému tokenu, takže při obnovení tokenu
zůstává zachován. Na každou událost odpovězte kódem `2xx`, jakmile ji přijmete.
Webhooky jsou oznámení, nikoli doklad o platbě, a některý může dorazit pozdě, nebo nemusí dorazit vůbec. Nikdy
neuzavírejte prodej pouze na základě webhooku:
* **Když webhook dorazí,** ověřte konečný výsledek přes API, například pomocí
[Načtení podrobností platby](/platform-api/reporting#retrieve-payment-details).
* **Když webhook nedorazí** v časovém limitu vhodném pro váš pokladní proces, nejpozději však
do `expiresAt` požadavku, zavolejte `GET /ecr/payment-requests/{requestId}`, abyste zjistili
jeho aktuální stav, a poté ověřte platbu přes API, jak je uvedeno výše.