Cloud Accept API

Gerät koppeln

Die Kopplung weist einem Tapaya-Gerät eine externalDeviceId zu, sodass Sie es beim Auflisten der Geräte finden und beim Starten einer Zahlung gezielt ansprechen können.

Zuweisung aus Ihrer App

Ihre Anwendung ruft auf dem Gerät eine Funktion des Accept SDK auf, die ihm seine externalDeviceId zuweist. Verwenden Sie in jedem Aufruf der Cloud Accept API für dieses Gerät dieselbe Kennung.

QR-Code scannen

Der Händler öffnet den Kopplungsvorgang in der Tapaya Platform, die einen QR-Code für die zuzuweisende externalDeviceId anzeigt. Der Händler scannt ihn mit der Tapaya-Händler-App auf dem Zielgerät, und die App schließt die Kopplung ab.

Zugriffstoken eintauschen

Tauschen Sie Ihr Server Secret Token und das merchantToken des Händlers mit POST /ecr/auth gegen ein Zugriffstoken ein. merchantToken wird nur hier gesendet; alle späteren Aufrufe senden nur 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"
}

Erneuern Sie das Token vor expiresAt. Rufen Sie POST /ecr/auth/refresh mit dem aktuellen, noch gültigen accessToken im Header Authorization auf. Der Endpoint gibt denselben Body mit einem neuen Token zurück; speichern Sie es und verwenden Sie ab dann nur noch dieses.

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

Einsatzbereites Gerät finden

Listen Sie die Geräte des Händlers mit GET /ecr/devices auf. Mit ?connected=true lassen Sie nicht verbundene Geräte weg; ein einzelnes Gerät rufen Sie mit GET /ecr/devices/{externalDeviceId} ab.

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

Senden Sie Zahlungen nur an ein Gerät, dessen availability den Wert ready hat. Die Liste ist eine Momentaufnahme: Die Verfügbarkeit wird beim Absenden erneut geprüft, daher kann auch ein Gerät mit ready eine Anfrage ablehnen. Siehe Geräteverfügbarkeit.

Zahlungsanfrage senden

Senden Sie den Betrag mit POST /ecr/payment-requests an ein Gerät. Tapaya speichert die Anfrage und benachrichtigt das Gerät, das den Zahlungsbildschirm anzeigt.

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

Parameter:

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

Sichern Sie Wiederholungsversuche ab. Der Header Idempotency-Key ist erforderlich. Wird ein Schlüssel mit demselben Body erneut verwendet, wird die ursprüngliche Anfrage zurückgegeben, statt eine zweite Zahlung zu starten; wird er mit einem anderen Body erneut verwendet, wird 409 idempotency_conflict zurückgegeben. Binden Sie den Schlüssel an den Verkauf und den Versuch, wie bei order-1042-attempt-1.

Ergebnis verfolgen

Verfolgen Sie die Anfrage durch ihre Status mit Webhooks, oder fragen Sie regelmäßig GET /ecr/payment-requests/{requestId} ab. Sobald sie payment_created erreicht, enthält die Antwort das paymentToken, und Events vom Typ payment.updated melden den Fortschritt der Zahlung selbst.

Um Webhooks zu empfangen, registrieren Sie Ihren HTTPS-Endpoint mit POST /ecr/webhook-subscriptions oder legen Sie die Callback-URL und die Event-Typen für den Händler in der Tapaya Platform fest.

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

Ein Abonnement gehört dem Integrator und dem Händler, nicht einem Zugriffstoken, und bleibt daher bei der Erneuerung des Tokens bestehen. Beantworten Sie jedes Event mit einem 2xx, sobald Sie es angenommen haben.