### Associare un dispositivo [#pair-a-device]
L'associazione assegna un `externalDeviceId` a un dispositivo Tapaya, così può trovarlo quando elenca i dispositivi
e indicarlo come destinazione quando avvia un pagamento.
#### Assegnare dalla Sua app [#assign-from-your-app]
La Sua applicazione chiama una funzione dell'Accept SDK sul dispositivo per assegnarne l'`externalDeviceId`. Usi
lo stesso identificatore in ogni chiamata alla Cloud Accept API per quel dispositivo.
#### Scansionare un codice QR [#scan-a-qr-code]
L'esercente apre la procedura di associazione nella Tapaya Platform, che mostra un codice QR per
l'`externalDeviceId` da assegnare. L'esercente lo scansiona con l'app Tapaya per esercenti sul dispositivo
di destinazione e l'app completa l'associazione.
### Ottenere un token di accesso [#exchange-an-access-token]
Scambi il Suo Server Secret Token e il `merchantToken` dell'esercente con un token di accesso tramite
`POST /ecr/auth`. `merchantToken` viene inviato solo qui; tutte le chiamate successive inviano soltanto
`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"
}
```
| Codice | Descrizione |
| ------ | ----------------------------------------- |
| `401` | Token API non valido o scaduto. |
| `403` | L'accesso all'esercente non è consentito. |
**Rinnovi prima di `expiresAt`.** Chiami `POST /ecr/auth/refresh` con l'`accessToken` attuale, ancora valido,
nell'header `Authorization`. Restituisce lo stesso corpo con un nuovo token; lo salvi
e da quel momento usi quello.
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 }
```
| Codice | Descrizione |
| ------ | -------------------------------------------------------------------------------------------------------------- |
| `401` | Il token di accesso non è valido, è scaduto o è stato revocato. Ne ottenga uno nuovo tramite `POST /ecr/auth`. |
| `403` | Non ha più accesso all'esercente. Non viene emesso alcun nuovo token. |
### Trovare un dispositivo pronto [#find-a-ready-device]
Elenchi i dispositivi dell'esercente con `GET /ecr/devices`. Aggiunga `?connected=true` per escludere
i dispositivi disconnessi, oppure recuperi un singolo dispositivo con `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"
}
```
Invii pagamenti solo a un dispositivo con `availability` pari a `ready`. L'elenco è un'istantanea:
la disponibilità viene verificata di nuovo al momento dell'invio, quindi anche un dispositivo `ready` può rifiutare
una richiesta. Consulti [Disponibilità del dispositivo](#device-availability).
### Inviare una richiesta di pagamento [#submit-a-payment-request]
Invii l'importo a un dispositivo con `POST /ecr/payment-requests`. Tapaya salva la richiesta e
avvisa il dispositivo, che mostra la schermata di pagamento.
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
```
**Parametri:**
| Campo | Tipo | Obbligatorio | Descrizione |
| ------------------ | --------- | ------------ | ------------------------------------------------------------------------- |
| `externalDeviceId` | `string` | ✓ | Il dispositivo associato che deve mostrare il pagamento. |
| `amount` | `integer` | ✓ | Importo nell'unità minore della valuta (`12500` corrisponde a 125,00 Kč). |
| `tipAmount` | `integer` | | Mancia nell'unità minore della valuta. |
| `currency` | `string` | ✓ | Codice valuta ISO 4217. |
| `paymentToken` | `string` | | Un pagamento esistente a cui associare la richiesta. |
```json title="202 Accepted"
{
"requestId": "...",
"status": "pending",
"paymentToken": null,
"expiresAt": "2026-01-13T16:30:59Z"
}
```
`202 Accepted` significa che Tapaya ha salvato la richiesta. Non significa che il dispositivo l'abbia ricevuta
né che il cliente abbia pagato. Qualsiasi errore successivo Le arriva come cambio di stato.
**Renda sicuri i nuovi tentativi.** L'header `Idempotency-Key` è obbligatorio. Riutilizzare una chiave con lo stesso corpo
restituisce la richiesta originale invece di avviare un secondo pagamento; riutilizzarla con un corpo
diverso restituisce `409 idempotency_conflict`. Leghi la chiave alla vendita e al tentativo, come in
`order-1042-attempt-1`.
### Seguire il risultato [#track-the-result]
Segua la richiesta attraverso i suoi [stati](#request-statuses) con i webhook, oppure interroghi periodicamente
`GET /ecr/payment-requests/{requestId}`. Quando raggiunge `payment_created`, la risposta contiene
il `paymentToken` e gli eventi `payment.updated` riportano l'avanzamento del pagamento stesso.
Per ricevere i webhook, registri il Suo endpoint HTTPS con `POST /ecr/webhook-subscriptions`, oppure imposti
l'URL di callback e i tipi di evento per l'esercente nella 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` viene restituito solo alla creazione della sottoscrizione. Lo conservi in modo sicuro; Le
serve per verificare la firma dei webhook in arrivo.
Una sottoscrizione appartiene all'integratore e all'esercente, non a un token di accesso, quindi resta valida
anche dopo il rinnovo del token. Risponda a ogni evento con un `2xx` dopo averlo accettato.
I webhook sono notifiche, non prove di pagamento, e un webhook può arrivare in ritardo o non arrivare affatto. Non
chiuda mai una vendita basandosi solo su un webhook:
* **Quando arriva un webhook,** confermi il risultato finale tramite l'API, ad esempio con
[Recuperare i dettagli del pagamento](/platform-api/reporting#retrieve-payment-details).
* **Quando non arriva alcun webhook** entro un timeout adatto al Suo flusso di checkout, e comunque non oltre
l'`expiresAt` della richiesta, chiami `GET /ecr/payment-requests/{requestId}` per leggerne
lo stato attuale, quindi confermi il pagamento tramite l'API come indicato sopra.