### Appairer un appareil [#pair-a-device]
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 [#assign-from-your-app]
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 [#scan-a-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 [#exchange-an-access-token]
É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
`.
cURL
TypeScript
```bash
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"
}'
```
```typescript
const res = await fetch('https://api.tapaya.com/ecr/auth', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${process.env.TAPAYA_SECRET_TOKEN}`,
},
body: JSON.stringify({ merchantToken: 'unique_merchant_id_from_your_db' }),
});
const { accessToken, expiresAt } = await res.json();
```
```json title="200 OK"
{
"accessToken": "...",
"tokenType": "Bearer",
"expiresAt": "2026-01-13T16:30:59Z"
}
```
| Code | Description |
| ----- | ----------------------------------------- |
| `401` | Jeton API invalide ou expiré. |
| `403` | L’accès au commerçant n’est pas autorisé. |
**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
TypeScript
```bash
curl -X 'POST' 'https://api.tapaya.com/ecr/auth/refresh' \
-H 'Authorization: Bearer ACCESS_TOKEN'
```
```typescript
const res = await fetch('https://api.tapaya.com/ecr/auth/refresh', {
method: 'POST',
headers: { Authorization: `Bearer ${accessToken}` },
});
const renewed = await res.json(); // { accessToken, tokenType, expiresAt }
```
| Code | Description |
| ----- | ----------------------------------------------------------------------------------------------- |
| `401` | Le jeton d’accès est invalide, expiré ou révoqué. Échangez-en un nouveau avec `POST /ecr/auth`. |
| `403` | Vous n’avez plus accès au commerçant. Aucun nouveau jeton n’est émis. |
### Trouver un appareil prêt [#find-a-ready-device]
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
TypeScript
```bash
curl 'https://api.tapaya.com/ecr/devices/till-01' \
-H 'Authorization: Bearer ACCESS_TOKEN'
```
```typescript
const res = await fetch('https://api.tapaya.com/ecr/devices/till-01', {
headers: { Authorization: `Bearer ${accessToken}` },
});
const device = await res.json();
const canPay = device.availability === 'ready';
```
```json title="200 OK"
{
"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](#device-availability).
### Envoyer une demande de paiement [#submit-a-payment-request]
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
TypeScript
```bash
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"
}'
```
```typescript
const res = await fetch('https://api.tapaya.com/ecr/payment-requests', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${accessToken}`,
'Idempotency-Key': 'order-1042-attempt-1',
},
body: JSON.stringify({
externalDeviceId: 'till-01',
amount: 12500, // 125.00 Kč
tipAmount: 500, // 5.00 Kč
currency: 'CZK',
}),
});
const { requestId } = await res.json(); // 202 Accepted
```
**Paramètres :**
| Champ | Type | Obligatoire | Description |
| ------------------ | --------- | ----------- | -------------------------------------------------------------------------------- |
| `externalDeviceId` | `string` | ✓ | L’appareil appairé qui doit afficher le paiement. |
| `amount` | `integer` | ✓ | Montant dans la plus petite unité de la devise (`12500` correspond à 125,00 Kč). |
| `tipAmount` | `integer` | | Pourboire dans la plus petite unité de la devise. |
| `currency` | `string` | ✓ | Code de devise ISO 4217. |
| `paymentToken` | `string` | | Un paiement existant auquel rattacher la demande. |
```json title="202 Accepted"
{
"requestId": "...",
"status": "pending",
"paymentToken": null,
"expiresAt": "2026-01-13T16:30:59Z"
}
```
`202 Accepted` signifie que Tapaya a enregistré la demande. Cela ne signifie pas que l’appareil l’a vue
ni que le client a payé. Tout ce qui échoue ensuite vous parvient sous forme de changement de statut.
**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 [#track-the-result]
Suivez la demande à travers ses [statuts](#request-statuses) 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
TypeScript
```bash
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"]
}'
```
```typescript
const res = await fetch('https://api.tapaya.com/ecr/webhook-subscriptions', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${accessToken}`,
},
body: JSON.stringify({
url: 'https://integrator.example.com/webhooks/tapaya',
events: ['payment_request.updated', 'payment.updated'],
}),
});
const { subscriptionId, signingSecret } = await res.json(); // 201 Created
```
```json title="201 Created"
{
"subscriptionId": "...",
"url": "https://integrator.example.com/webhooks/tapaya",
"events": ["payment_request.updated", "payment.updated"],
"signingSecret": "..."
}
```
`signingSecret` n’est renvoyé qu’à la création de l’abonnement. Conservez-le en lieu sûr ; vous
en avez besoin pour vérifier la signature des webhooks entrants.
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é.
Les webhooks sont des notifications, et non une preuve de paiement ; un webhook peut arriver en retard, ou ne jamais arriver. Ne
clôturez jamais une vente sur la seule base d’un webhook :
* **Lorsqu’un webhook arrive,** confirmez le résultat final via l’API, par exemple avec
[Récupérer les détails d’un paiement](/platform-api/reporting#retrieve-payment-details).
* **Lorsqu’aucun webhook n’arrive** dans un délai adapté à votre parcours d’encaissement, et au plus tard
à l’`expiresAt` de la demande, appelez `GET /ecr/payment-requests/{requestId}` pour lire son
statut actuel, puis confirmez le paiement via l’API comme ci-dessus.