Autenticazione
Tutte le rotte /v1/* si autenticano con una chiave API:
Authorization: Bearer sk_live_...
X-API-Key: sk_live_... è accettata allo stesso modo, per i client HTTP che riservano
Authorization ad altro.
Chiavi di prova e chiavi reali
| Prefisso | Modalità | Denaro reale |
|---|---|---|
sk_test_… |
Prova | No — tutto il codice viene eseguito (instradamento, commissioni, controlli), nessun movimento di denaro |
sk_live_… |
Produzione | Sì |
Gli oggetti creati in modalità di prova portano is_test: true e non compaiono mai nei suoi report
di produzione.
La modalità di prova non copre il pagamento istantaneo. Le famiglie PI e tontine rifiutano le chiavi di prova: parlano con un sistema esterno che da noi non ha un ambiente di prova.
Il segreto esiste una sola volta
Alla creazione (o alla rotazione) di una chiave, il segreto è mostrato una volta. Lato server è conservata solo la sua impronta HMAC: nessuno — nemmeno il supporto — può restituirglielo. Perso? Faccia una rotazione: la chiave vecchia è revocata, la nuova è mostrata una volta.
Perché la mia chiave risponde client_inactive?
Una chiave è emessa già alla registrazione, ma non ammette alcuna chiamata finché il conto non è
validato (pratica KYB approvata, conto nello stato active). È la porta di conformità: si apre
con la validazione e si richiude subito in caso di sospensione — la stessa chiave, senza alcun altro
cambiamento.
Ambiti
Ogni chiave porta degli ambiti, e un'operazione fuori ambito risponde 403 insufficient_scope:
incassare, pagare, rimborsare, leggere, gestire i webhook. Emetta la chiave più stretta che faccia
il lavoro — una chiave di lettura per i suoi report non ha bisogno di poter pagare.
Idempotenza
Sulle creazioni (POST /v1/payments, POST /v1/payouts, POST /v1/refunds…), passi un header
Idempotency-Key a sua scelta — per esempio il suo riferimento d'ordine. Una ripetizione con la
stessa chiave restituisce l'operazione originale, mai un doppione; la stessa chiave con un corpo
diverso è rifiutata con 409.
Una chiave per operazione, mai per oggetto padre. Un incasso può essere rimborsato in più volte: una chiave di idempotenza che porti l'identificativo del pagamento farebbe passare il secondo rimborso parziale per una ripetizione del primo. Successo per l'esercente, cliente non rimborsato.
Limite di richieste
300 richieste al minuto per chiave. Oltre, 429 con un header Retry-After — lo rispetti invece di
riprovare subito.
Buone pratiche
- Una chiave per ambiente (produzione, staging), mai condivisa tra servizi.
- Il segreto vive in un gestore di segreti, mai nel codice né nel front-end.
- Rotazione immediata al minimo dubbio — senza interruzione se distribuisce la chiave nuova prima di revocare la vecchia.