Cloud Accept API

Associare un dispositivo

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

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

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

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

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 -X 'POST' 'https://api.tapaya.com/ecr/auth/refresh' \
-H 'Authorization: Bearer ACCESS_TOKEN'

Trovare un dispositivo pronto

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

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.

Inviare una richiesta di pagamento

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

Parametri:

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

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

Segua la richiesta attraverso i suoi stati 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 -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": "..."
}

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.