### Spárovanie zariadenia [#pair-a-device]
Párovanie priradí zariadeniu Tapaya `externalDeviceId`, takže ho môžete nájsť pri výpise zariadení
a zacieliť naň pri spustení platby.
#### Priradenie z vašej aplikácie [#assign-from-your-app]
Vaša aplikácia zavolá na zariadení funkciu Accept SDK, ktorá mu priradí `externalDeviceId`. Vo všetkých
volaniach Cloud Accept API pre toto zariadenie používajte rovnaký identifikátor.
#### Naskenovanie QR kódu [#scan-a-qr-code]
Obchodník otvorí v Tapaya Platform postup párovania, ktorý zobrazí QR kód pre priraďované
`externalDeviceId`. Obchodník ho naskenuje aplikáciou Tapaya pre obchodníkov na cieľovom
zariadení a aplikácia párovanie dokončí.
### Výmena za prístupový token [#exchange-an-access-token]
Vymeňte svoj Server Secret Token a `merchantToken` obchodníka za prístupový token pomocou
`POST /ecr/auth`. `merchantToken` sa odosiela len tu; všetky ďalšie volania odosielajú iba
`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 alebo API token s uplynutou platnosťou. |
| `403` | Prístup k obchodníkovi nie je povolený. |
**Obnovte token pred `expiresAt`.** Zavolajte `POST /ecr/auth/refresh` s aktuálnym, stále platným
`accessToken` v hlavičke `Authorization`. Endpoint vráti rovnaké telo s novým tokenom; uložte si ho
a odvtedy používajte už len 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` | Prístupový token je neplatný, vypršal alebo bol zneplatnený. Získajte nový výmenou cez `POST /ecr/auth`. |
| `403` | K obchodníkovi už nemáte prístup. Nový token sa nevydá. |
### Vyhľadanie pripraveného zariadenia [#find-a-ready-device]
Zariadenia obchodníka vypíšte pomocou `GET /ecr/devices`. Pridaním `?connected=true` vynecháte
odpojené zariadenia; jedno konkrétne zariadenie načítate pomocou `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 posielajte len na zariadenie, ktorého `availability` je `ready`. Výpis je len momentálny snímok:
dostupnosť sa znova overuje pri odoslaní, takže aj zariadenie v stave `ready` môže požiadavku
odmietnuť. Pozrite [Dostupnosť zariadenia](#device-availability).
### Odoslanie požiadavky na platbu [#submit-a-payment-request]
Sumu odošlite na zariadenie pomocou `POST /ecr/payment-requests`. Tapaya požiadavku uloží a
upozorní zariadenie, ktoré zobrazí platobnú 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
```
**Parametre:**
| Pole | Typ | Povinné | Popis |
| ------------------ | --------- | ------- | ------------------------------------------------------- |
| `externalDeviceId` | `string` | ✓ | Spárované zariadenie, ktoré má platbu zobraziť. |
| `amount` | `integer` | ✓ | Suma v najmenšej jednotke meny (`12500` je 125,00 Kč). |
| `tipAmount` | `integer` | | Prepitné v najmenšej jednotke meny. |
| `currency` | `string` | ✓ | Kód meny podľa ISO 4217. |
| `paymentToken` | `string` | | Existujúca platba, ku ktorej sa má požiadavka pripojiť. |
```json title="202 Accepted"
{
"requestId": "...",
"status": "pending",
"paymentToken": null,
"expiresAt": "2026-01-13T16:30:59Z"
}
```
`202 Accepted` znamená, že Tapaya požiadavku uložila. Neznamená to, že ju zariadenie zaznamenalo,
ani že zákazník zaplatil. Čokoľvek, čo zlyhá neskôr, sa k vám dostane ako zmena stavu.
**Zabezpečte bezpečné opakovanie požiadaviek.** Hlavička `Idempotency-Key` je povinná. Opätovné použitie kľúča s rovnakým telom
vráti pôvodnú požiadavku namiesto spustenia druhej platby; opätovné použitie s iným telom
vráti `409 idempotency_conflict`. Naviažte kľúč na predaj a pokus, napríklad
`order-1042-attempt-1`.
### Sledovanie výsledku [#track-the-result]
Sledujte požiadavku cez jej [stavy](#request-statuses) pomocou webhookov, alebo pravidelne volajte
`GET /ecr/payment-requests/{requestId}`. Keď požiadavka dosiahne stav `payment_created`, odpoveď obsahuje
`paymentToken` a priebeh samotnej platby hlásia udalosti `payment.updated`.
Ak chcete prijímať webhooky, zaregistrujte svoj HTTPS endpoint pomocou `POST /ecr/webhook-subscriptions`, alebo
pre obchodníka nastavte callback URL a typy udalostí 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` sa vracia len pri vytvorení odberu. Bezpečne si ho uložte; budete
ho potrebovať na overenie podpisu prichádzajúcich webhookov.
Odber patrí integrátorovi a obchodníkovi, nie prístupovému tokenu, takže pri obnovení tokenu
zostáva zachovaný. Na každú udalosť odpovedzte kódom `2xx`, hneď ako ju prijmete.
Webhooky sú oznámenia, nie doklad o platbe, a niektorý môže doraziť neskoro alebo nemusí doraziť vôbec. Nikdy
neuzatvárajte predaj len na základe webhooku:
* **Keď webhook dorazí,** overte konečný výsledok cez API, napríklad pomocou
[Načítanie podrobností platby](/platform-api/reporting#retrieve-payment-details).
* **Keď webhook nedorazí** v časovom limite vhodnom pre váš pokladničný proces, najneskôr však
do `expiresAt` požiadavky, zavolajte `GET /ecr/payment-requests/{requestId}`, aby ste zistili
jej aktuálny stav, a potom overte platbu cez API, ako je uvedené vyššie.