Cloud Accept API

Appairer un appareil

L’appairage attribue un externalDeviceId à un appareil Tapaya, afin que vous puissiez le retrouver lorsque vous listez les appareils et le cibler lorsque vous lancez un paiement.

Attribuer depuis votre application

Votre application appelle une fonction de l’Accept SDK sur l’appareil pour lui attribuer son externalDeviceId. Utilisez le même identifiant dans chaque appel à la Cloud Accept API concernant cet appareil.

Scanner un QR code

Le commerçant ouvre le parcours d’appairage dans la Tapaya Platform, qui affiche un QR code pour l’externalDeviceId à attribuer. Le commerçant le scanne avec l’application commerçant Tapaya sur l’appareil cible, et l’application finalise l’appairage.

Échanger un jeton d’accès

Échangez votre Server Secret Token et le merchantToken du commerçant contre un jeton d’accès avec POST /ecr/auth. Le merchantToken n’est envoyé qu’ici ; tous les appels suivants envoient uniquement 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"
}

Renouvelez le jeton avant expiresAt. Appelez POST /ecr/auth/refresh avec l’accessToken actuel, encore valide, dans l’en-tête Authorization. L’appel renvoie le même corps avec un nouveau jeton ; enregistrez-le et utilisez-le désormais.

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

Trouver un appareil prêt

Listez les appareils du commerçant avec GET /ecr/devices. Ajoutez ?connected=true pour exclure les appareils déconnectés, ou récupérez un seul appareil avec 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"
}

N’envoyez des paiements qu’à un appareil dont l’availability vaut ready. La liste n’est qu’un instantané : la disponibilité est vérifiée de nouveau lors de l’envoi, si bien qu’un appareil ready peut tout de même refuser une demande. Voir Disponibilité des appareils.

Envoyer une demande de paiement

Envoyez le montant à un appareil avec POST /ecr/payment-requests. Tapaya enregistre la demande et avertit l’appareil, qui affiche l’écran de paiement.

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

Paramètres :

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

Sécurisez les nouvelles tentatives. L’en-tête Idempotency-Key est obligatoire. Réutiliser une clé avec le même corps renvoie la demande d’origine au lieu de lancer un second paiement ; la réutiliser avec un corps différent renvoie 409 idempotency_conflict. Associez la clé à la vente et à la tentative, comme dans order-1042-attempt-1.

Suivre le résultat

Suivez la demande à travers ses statuts avec des webhooks, ou interrogez régulièrement GET /ecr/payment-requests/{requestId}. Dès qu’elle atteint payment_created, la réponse contient le paymentToken, et les événements payment.updated rendent compte de la progression du paiement lui-même.

Pour recevoir des webhooks, enregistrez votre endpoint HTTPS avec POST /ecr/webhook-subscriptions, ou définissez l’URL de callback et les types d’événements du commerçant dans la 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": "..."
}

Un abonnement appartient à l’intégrateur et au commerçant, et non à un jeton d’accès ; il est donc conservé lors du renouvellement du jeton. Répondez à chaque événement par un 2xx dès que vous l’avez accepté.