Cloud Accept API

Спарювання пристрою

Спарювання призначає пристрою Tapaya externalDeviceId, щоб ви могли знайти його у списку пристроїв і вибрати його як цільовий під час запуску платежу.

Призначення з вашого застосунку

Ваш застосунок викликає на пристрої функцію Accept SDK, яка призначає йому externalDeviceId. Використовуйте той самий ідентифікатор у кожному виклику Cloud Accept API для цього пристрою.

Сканування QR-коду

Мерчант відкриває процес спарювання в Tapaya Platform, яка показує QR-код для externalDeviceId, що призначається. Мерчант сканує його застосунком Tapaya для мерчантів на цільовому пристрої, і застосунок завершує спарювання.

Обмін на токен доступу

Обміняйте свій Server Secret Token і merchantToken мерчанта на токен доступу за допомогою POST /ecr/auth. merchantToken надсилається лише тут; усі подальші виклики надсилають тільки 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"
}

Оновлюйте токен до настання expiresAt. Викличте POST /ecr/auth/refresh із поточним, ще дійсним accessToken у заголовку Authorization. Ендпоінт повертає те саме тіло з новим токеном; збережіть його і надалі використовуйте саме його.

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

Пошук готового пристрою

Отримайте список пристроїв мерчанта за допомогою GET /ecr/devices. Додайте ?connected=true, щоб виключити відключені пристрої, або отримайте один пристрій за допомогою 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"
}

Надсилайте платежі лише на пристрій, у якого availability має значення ready. Список є лише знімком стану: доступність перевіряється повторно під час надсилання, тож навіть пристрій у стані ready може відхилити запит. Див. Доступність пристрою.

Надсилання запиту на платіж

Надішліть суму на пристрій за допомогою POST /ecr/payment-requests. Tapaya зберігає запит і сповіщає пристрій, який показує екран оплати.

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

Параметри:

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

Зробіть повторні спроби безпечними. Заголовок Idempotency-Key є обов'язковим. Повторне використання ключа з тим самим тілом повертає початковий запит замість запуску другого платежу; повторне використання з іншим тілом повертає 409 idempotency_conflict. Прив'яжіть ключ до продажу та спроби, як у order-1042-attempt-1.

Відстеження результату

Стежте за статусами запиту за допомогою вебхуків або періодично опитуйте GET /ecr/payment-requests/{requestId}. Щойно запит досягне статусу payment_created, відповідь міститиме paymentToken, а про перебіг самого платежу повідомлятимуть події payment.updated.

Щоб отримувати вебхуки, зареєструйте свій HTTPS-ендпоінт за допомогою POST /ecr/webhook-subscriptions або задайте для мерчанта callback URL і типи подій у 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": "..."
}

Підписка належить інтегратору й мерчанту, а не токену доступу, тому вона зберігається після оновлення токена. Відповідайте на кожну подію кодом 2xx, щойно приймете її.