Cloud Accept API

Spárování zařízení

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

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

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

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

Vyhledání připraveného zařízení

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 '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 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í.

Odeslání požadavku na platbu

Částku odešlete na zařízení pomocí POST /ecr/payment-requests. Tapaya požadavek uloží a upozorní zařízení, které zobrazí platební 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"
    }'

Parametry:

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

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

Sledujte požadavek přes jeho stavy 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 -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": "..."
}

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.