API di pagamento di massa in crypto: automatizza i pagamenti in modo non custodiale

Cosa fa realmente l'API per i pagamenti di massa in criptovaluta

Una singola chiamata POST /v1/payout riserva i fondi per l'intero lotto, valida ogni destinatario e lo mette in coda per la firma. L'operatore poi firma e trasmette da chiavi offline. Questa è la vera natura di un API per i pagamenti di massa in criptovaluta costruita su un gateway non custodiale: l'API automatizza l'invio, la validazione, lo stato e i webhook — non automatizza la firma, perché le chiavi private non risiedono mai sul server. Non c'è un wallet caldo da svuotare e nessun invio automatico silenzioso. Se questo compromesso ti sembra accettabile, l'API trasforma un pagamento manuale o una corsa di affiliazione in due o tre righe di codice.

Questa è una guida per sviluppatori. Copia il contratto esatto dalla documentazione API in modo che tu possa implementarlo oggi: gli endpoint, la firma HMAC, il Idempotency-Key, la rigorosa validazione 422, il webhook payout.sent e come la cancellazione rilascia il saldo trattenuto. Se vuoi prima una panoramica del prodotto, leggi la pagina sui pagamenti di massa.

Perché è semi-automatizzato e perché questo è un vantaggio per la sicurezza

Niente viene trasmesso dall'applicazione web stessa. Gli indirizzi di ricezione derivano da materiale di chiave pubblica; le chiavi private che autorizzano una spesa rimangono sul tuo hardware, offline. Quindi il flusso è deliberatamente a due fasi. Quando invii un lotto — dal cabinet o tramite l'API — Payora riserva il totale più la commissione per ogni elemento sul tuo saldo interno istantaneamente, in modo che il lotto non possa mai essere speso eccessivamente. Poi un umano (tu o il tuo turno operativo) firma gli elementi in coda offline e li trasmette.

Una violazione del server non può muovere un singolo coin, perché la scatola che riceve la chiamata API non ha nulla con cui firmare. Il costo è un passo di firma per lotto. Per stipendi, corse di affiliazione e regolamenti con i fornitori, questo è un prezzo equo, ed è la stessa architettura descritta in pagare centinaia di wallet senza un wallet caldo. Non modellare mai questo come "chiamata API, coin istantaneamente scomparsi" — sarebbe un prodotto diverso e più rischioso.

Autenticazione e firma della richiesta

L'API per i pagamenti di massa in criptovaluta utilizza la stessa autenticazione del resto di Payora. Ogni richiesta porta tre intestazioni: X-Payora-Key, X-Payora-Timestamp (secondi Unix, ±120s di skew), e X-Payora-Signature. La firma è un HMAC-SHA256 sul timestamp, un punto letterale e il corpo della richiesta grezzo esatto:

X-Payora-Signature = hex(HMAC-SHA256(api_secret, timestamp + "." + raw_body))

Firma i byte che invii effettivamente, prima di qualsiasi riserializzazione. Se il tuo client HTTP ricodifica il JSON, cattura prima il corpo grezzo e calcola l'hash. Questo è lo stesso schema utilizzato per verificare i webhook in entrata, trattato in verifica della firma del webhook HMAC-SHA256.

POST /v1/payout: invia un lotto

Invia una valuta, fino a 500 elementi, e una nota facoltativa. Ogni elemento è un indirizzo, un importo come stringa e un tag facoltativo — il tag di destinazione XRP o il memo XLM quando l'asset ne ha bisogno.

curl -X POST https://api.payora.money/v1/payout \
  -H "X-Payora-Key: pk_live_9f3c8a12" \
  -H "X-Payora-Timestamp: 1753280400" \
  -H "X-Payora-Signature: 7b1e0c4d9a55f2..." \
  -H "Idempotency-Key: payroll-2026-07" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USDT",
    "items": [
      {"address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "amount": "250.00"},
      {"address": "TXk9mP2v7wQ3nR5tYb1cD8eF4gH6jK0lMn", "amount": "1800.00", "tag": ""}
    ],
    "note": "Contrattisti di luglio"
  }'

In caso di successo ottieni 201 con un lotto che puoi tracciare. Il totale è la somma degli importi, la commissione è la commissione di movimento del tuo piano (1,5% su Free) più la commissione di rete del coin’, e entrambi sono già trattenuti dal tuo saldo:

{
  "batch_id": "po_7Qd2K8xM4b",
  "status": "in attesa",
  "currency": "USDT",
  "item_count": 2,
  "total": "2050.00",
  "fee": "20.50",
  "items": [
    {"index": 0, "address": "TR7NHqjeKQ...", "amount": "250.00", "status": "in attesa"},
    {"index": 1, "address": "TXk9mP2v7w...", "amount": "1800.00", "status": "in attesa"}
  ]
}

Accettare pagamenti è ancora 0%; la commissione di movimento si applica solo quando il denaro esce. Le commissioni di rete sono separate e pagate on-chain al momento della trasmissione.

Validazione rigorosa: nessun destinatario silenziosamente scartato

La validazione è tutto o niente di proposito. Se un indirizzo è malformato per la rete scelta, o se un importo ha più posizioni decimali di quelle supportate dal coin, l'intero lotto viene rifiutato con 422 e gli indici problematici. Niente è messo in coda, niente è trattenuto.

HTTP/1.1 422 Entità non elaborabile
{
  "error": "validation_failed",
  "invalid_items": [3, 17],
  "message": "indirizzo non valido all'indice 3; l'importo supera la precisione del coin all'indice 17"
}

Questo è il comportamento che desideri per i pagamenti. Un gateway che ha silenziosamente troncato 1800.123456789 o ha saltato una riga errata pagherebbe meno o scarterebbe una persona, e non te ne accorgeresti fino a quando qualcuno non si lamentasse. Risolvi gli indici contrassegnati e reinvia l'intero lotto.

Idempotenza: i tentativi non pagano mai due volte

Le reti scadono. Una richiesta di pagamento che fallisce a metà è pericolosa da ripetere ciecamente, quindi invia un'intestazione Idempotency-Key — qualsiasi stringa stabile e unica per quel lotto logico (un periodo di pagamento, un gruppo di fatture). Se una richiesta con la stessa chiave arriva di nuovo, Payora restituisce il lotto originale invece di crearne uno secondo. Riutilizza la chiave per ogni tentativo dello stesso lotto; usa una chiave fresca per un lotto genuinamente nuovo.

• Stessa chiave, stesso lotto — sicuro da ripetere dopo un timeout; ottieni il primo risultato.
• Nuova chiave — un nuovo lotto, un nuovo blocco sul tuo saldo.
• Memorizza il batch_id restituito non appena lo hai, in modo da poter riconciliare anche se la risposta è stata persa.

Riconcilia con GET /v1/payout/{id}

Dopo che l'operatore ha firmato, interroga GET /v1/payout/{id} per lo stato attuale e un tx_hash per ogni elemento man mano che ogni transazione viene trasmessa. GET /v1/payout elenca i lotti recenti per dashboard e audit. Memorizza il batch_id e ogni indice di elemento contro i tuoi registri in modo che ogni destinatario corrisponda a un hash on-chain che puoi mostrare loro.

Hai bisogno di ritirarne uno prima che venga firmato? POST /v1/payout/{id}/cancel annulla un lotto ancora in attesa e rilascia il saldo trattenuto per intero. Una volta che gli elementi sono trasmessi, sono on-chain e finali, come qualsiasi transazione in criptovaluta — la cancellazione funziona solo mentre il lotto è in attesa.

Il webhook payout.sent

Invece di interrogare per sempre, iscriviti a payout.sent. Quando l'operatore ha trasmesso ogni elemento in un lotto, Payora attiva un webhook firmato utilizzando la stessa firma HMAC di invoice.paid. Verificalo allo stesso modo — ricalcola la firma su timestamp, punto, corpo grezzo e confronta in tempo costante:

$expected = hash_hmac('sha256', $timestamp . '.' . $raw_body, $webhook_secret);
if (!hash_equals($expected, $signature_header)) { http_response_code(400); exit; }
// payload.event == "payout.sent", payload.batch_id, payload.items[].tx_hash

Solo dopo che quel controllo è superato dovresti contrassegnare il pagamento come completato, inviare ricevute via email o aggiornare i registri. Un webhook non verificato è solo una richiesta HTTP non affidabile.

Una checklist minima per l'integrazione

1. Crea un account e genera chiavi API su register; finanzia il saldo interno nella valuta che utilizzerai per i pagamenti.
2. Costruisci il corpo JSON grezzo, firmalo (timestamp + "." + body) con HMAC-SHA256, allega le tre intestazioni più un Idempotency-Key.
3. POST /v1/payout; su 201 conserva il batch_id, su 422 correggi gli indici contrassegnati e rinvia.
4. Fai firmare e trasmettere offline il lotto in coda dal tuo operatore.
5. Verifica il webhook payout.sent, o interroga GET /v1/payout/{id}, e registra ogni tx_hash.

Questo è l'intero ciclo. L'API rimuove la parte noiosa e soggetta a errori — costruire, validare e tracciare un lotto di 500 righe — mentre la firma offline mantiene al sicuro ciò che conta davvero, le tue chiavi, lontano dal server.

Inizia a costruire

Leggi la sezione API per i pagamenti di massa della documentazione, prendi le chiavi su register e guarda la funzionalità end to end sulla pagina dei pagamenti di massa. Puoi automatizzare il lotto oggi e continuare a firmare dove appartiene — offline.