Cloud Accept API

Spárovanie zariadenia

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

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

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

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 <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"
}

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 -X 'POST' 'https://api.tapaya.com/ecr/auth/refresh' \
-H 'Authorization: Bearer ACCESS_TOKEN'

Vyhľadanie pripraveného zariadenia

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 '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"
}

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.

Odoslanie požiadavky na platbu

Sumu odošlite na zariadenie pomocou POST /ecr/payment-requests. Tapaya požiadavku uloží a upozorní zariadenie, ktoré zobrazí platobnú obrazovku.

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"
    }'

Parametre:

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

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

Sledujte požiadavku cez jej stavy 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 -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": "..."
}

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.