Cloud Accept API

Pair a Device

Pairing assigns an externalDeviceId to a Tapaya device, so you can find it when listing devices and target it when starting a payment.

Assign from your app

Your application calls an Accept SDK function on the device to assign its externalDeviceId. Use the same identifier in every Cloud Accept API call for that device.

Scan a QR code

The merchant opens the pairing flow in the Tapaya Platform, which shows a QR code for the externalDeviceId to assign. The merchant scans it with the Tapaya merchant app on the target device, and the app completes pairing.

Exchange an Access Token

Exchange your Server Secret Token and the merchant's merchantToken for an access token with POST /ecr/auth. merchantToken is sent only here; every later call sends just 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"
}

Renew before expiresAt. Call POST /ecr/auth/refresh with the current, still-valid accessToken in the Authorization header. It returns the same body with a new token; store it and use it from then on.

curl -X 'POST' 'https://api.tapaya.com/ecr/auth/refresh' \
-H 'Authorization: Bearer ACCESS_TOKEN'

Find a Ready Device

List the merchant's devices with GET /ecr/devices. Add ?connected=true to leave out disconnected devices, or fetch one device with 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"
}

Send payments only to a device whose availability is ready. The list is a snapshot: availability is checked again when you submit, so a ready device can still turn a request down. See Device availability.

Submit a Payment Request

Send the amount to a device with POST /ecr/payment-requests. Tapaya stores the request and notifies the device, which shows the payment screen.

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

Parameters:

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

Make retries safe. The Idempotency-Key header is required. Reusing a key with the same body returns the original request instead of starting a second payment; reusing it with a different body returns 409 idempotency_conflict. Tie the key to the sale and attempt, as in order-1042-attempt-1.

Track the Result

Follow the request through its statuses with webhooks, or poll GET /ecr/payment-requests/{requestId}. Once it reaches payment_created, the response carries the paymentToken, and payment.updated events report the payment's own progress.

To receive webhooks, register your HTTPS endpoint with POST /ecr/webhook-subscriptions, or set the callback URL and event types for the merchant in the 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": "..."
}

A subscription belongs to the integrator and merchant, not to an access token, so it survives token renewal. Answer each event with a 2xx once you've accepted it.