Come testare un gateway di pagamento in criptovaluta prima di andare live

Non puoi testare un gateway di pagamento crypto in un sandbox su Payora, perché Payora non ne ha uno: nessuna modalità testnet, nessuna chiave API in modalità test, nessuna fattura falsa. Quello che fai invece è ispezionare il checkout reale ospitato su /demo, riprodurre un webhook che hai firmato tu stesso contro il tuo gestore, quindi inviare un pagamento reale di circa un dollaro alla tua fattura su una rete economica. Quest'ultimo passaggio costa spiccioli e dimostra l'unica cosa che un sandbox non potrebbe mai dimostrare.

Perché non c'è un sandbox, e perché questo non è il problema che pensi sia

Un sandbox è un simulatore. Ti consente di provare il tuo codice contro una finzione scritta dal gateway. Questo è genuinamente utile per i processori di carte, dove l'acquirente, il motore di rischio e le ferrovie di regolamento sono tutti opachi e non hai altro modo per entrare.

La crypto è diversa. La parte che si rompe in produzione è quasi mai la chiamata API. È la catena: un pagamento che atterra sulla rete sbagliata, un blocco del tasso scaduto mentre l'acquirente copiava l'indirizzo, una politica di conferma che nessuno ha letto, un indirizzo che il server ha derivato dalla chiave sbagliata. Un sandbox conia una fattura pagata dal nulla. Non ti dice nulla su tutto ciò. Peggio, ti dice che tutto va bene, che è la bugia più costosa che un test possa produrre.

Quindi il modo onesto per testare un gateway di pagamento crypto è una scala: tutto ciò che puoi verificare gratuitamente prima, poi un piccolo pagamento reale che esercita l'intera catena dall'inizio alla fine. Ecco l'ordine in cui lo eseguirei.

1. Guarda il checkout reale prima di scrivere una riga di codice

Apri /demo. Genera una fattura live sul checkout ospitato reale, la stessa pagina che vedranno i tuoi acquirenti. Nessun account, nessun codice. Guarda cosa succede realmente: come si comporta il selettore di monete, come appare la finestra di blocco del tasso, cosa vede l'acquirente mentre una transazione è ancora non confermata, cosa succede quando il timer scade.

Cinque minuti qui risparmiano una discussione dopo, perché la maggior parte dei bug di integrazione inizia come un modello mentale errato del flusso. Leggi /docs insieme ad esso e abbina ogni schermo ai campi della fattura dietro di esso. Poi crea il tuo account su /register e ottieni la tua chiave API e api_secret.

2. Esercita il tuo gestore webhook senza spendere nulla

Questo è il grande momento. Il tuo gestore è il codice che trasforma "denaro arrivato" in "il cliente ha ricevuto il suo oggetto", ed è il pezzo che puoi testare in modo esaustivo gratuitamente, perché possiedi il segreto che firma il webhook. Qualsiasi cosa Payora possa firmare, tu puoi firmare.

Lo schema è HMAC semplice. La firma è hex(hmac_sha256(timestamp . '.' . rawBody, api_secret)), inviata in X-Payora-Signature, con lo stesso timestamp in X-Payora-Timestamp. Il timestamp deve essere entro ±120 secondi da adesso, e ogni consegna porta un Idempotency-Key header che rimane stabile attraverso i tentativi dello stesso evento. Firma il rawbyte del corpo, non un array ricodificato — la ricodifica è il motivo classico per cui una firma corretta fallisce.

<?php
// Sign a webhook exactly the way Payora signs one, and POST it at your own endpoint.
$secret = 'YOUR_API_SECRET';                          // the secret your handler verifies with
$url    = 'https://yoursite.com/payora-webhook.php';  // your endpoint, on your dev host

$body = json_encode([
    'event'      => 'invoice.paid',
    'invoice_id' => 'inv_local_1',
    'order_id'   => '1001',
    'status'     => 'paid',
    'amount'     => '1.00',
    'currency'   => 'USD',
    'asset'      => 'USDT',
    'network'    => 'tron',
], JSON_UNESCAPED_SLASHES);

$ts  = (string) time();
$sig = hash_hmac('sha256', $ts . '.' . $body, $secret);   // lowercase hex

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $body,          // send the RAW body you signed
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'X-Payora-Timestamp: ' . $ts,
        'X-Payora-Signature: ' . $sig,
        'Idempotency-Key: whk_local_1',
    ],
]);
$out  = curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
echo "$code\n$out\n";

Punta questo al tuo endpoint di sviluppo e avrai un generatore di webhook che non costa nulla e funziona in un ciclo. Il lato della verifica — confronto a tempo costante, controlli della finestra, perché devi leggere il flusso di input grezzo — è trattato in dettaglio in verifica della firma del webhook con HMAC-SHA256.

3. I test che catturano effettivamente i bug

Esegui ciascuno di questi contro il tuo gestore e controlla il database, non solo lo stato HTTP. I risultati attesi non sono note a piè di pagina; sono il test.

• Firma valida → 200, ordine contrassegnato come pagato, esattamente una volta.
• Lo stesso webhook consegnato due volte (stesso Idempotency-Key) → ancora esattamente un ordine pagato. Nessun doppio credito, nessuna seconda chiave di licenza, nessuna seconda etichetta di spedizione. Questo è il bug reale più comune nelle integrazioni di pagamento, e i tentativi sono normali, non eccezionali.
• Corpo manomesso con la vecchia firma — cambia amount da 1.00 a 1000.00, mantieni la firma → rifiutato, ordine NON pagato.
• Firma errata o assente → rifiutato. Un vuoto X-Payora-Signature deve fallire esattamente come uno errato.
• Timestamp scaduto — impostalo a dieci minuti fa → rifiutato nella finestra, anche se l'HMAC stesso è valido.
• ID fattura sconosciuto o estero → rifiutato senza problemi. Nessun errore fatale, nessun 500, nessuna riga scritta a metà.
• Il tuo endpoint restituisce 500 → il tentativo di ripetizione che segue non deve essere applicato due volte. Chiudi la connessione al database a metà gestore se vuoi essere sicuro.
• Confronto a tempo costante — usa hash_equals(), mai ==. E non registrare mai il api_secret, non a livello di debug, non troncato, non una sola volta.

Se tutti e otto passano, il tuo gestore è in una forma migliore rispetto alla maggior parte delle integrazioni live. Ora nota cosa nessuno di loro ha dimostrato: che il denaro può effettivamente raggiungerti.

4. Un piccolo pagamento reale a te stesso

Ora spendi un dollaro. Crea una fattura tramite l'API o un link di pagamento da /accept-payments, apri il checkout e pagalo dal tuo stesso portafoglio, alla tua stessa fattura, con circa $1.

Scegli una rete economica e veloce in modo che questo costi centesimi piuttosto che dollari: TON (Gram), Tron e Solana confermano tutti in pochi secondi per una frazione di centesimo. Non eseguire questo sulla mainnet di Bitcoin a meno che Bitcoin non sia specificamente ciò che stai spedendo — aspetterai dieci minuti per tentativo e pagherai per il privilegio.

Questo singolo pagamento è l'unico test che esercita l'intera catena: blocco del tasso, rilevamento on-chain, conferma alla politica di quell'asset (vedi quante conferme sono sicure), webhook firmato, il tuo database. Se funziona, la tua integrazione funziona. Se non funziona, il fallimento è reale e specifico — ed è esattamente ciò che vuoi scoprire in un martedì tranquillo e non durante un lancio.

5. Dimostra di poter prelevare i soldi

Tutti saltano questo passaggio. È il passo che fa male.

Prima di prendere il pagamento di un singolo cliente, preleva quel dollaro su un wallet che controlli. Controlla /balance, esegui un prelievo o un trasferimento, osserva che arrivi. Se prevedi di pagare fornitori o affiliati, invia un lotto attraverso /mass-payouts con due righe e importi triviali, e conferma che il passaggio di firma offline funzioni sulla tua macchina reale con il tuo materiale di chiave reale — non in teoria, sulla macchina.

Un gateway in cui puoi ricevere ma da cui non puoi prelevare non è un gateway. È una trappola con una bella pagina di checkout. Scoprire questo con $1 bloccato è una storia che racconti dopo. Scoprire questo con $40.000 bloccati è un pomeriggio molto diverso.

6. Verifica che gli indirizzi derivati siano effettivamente tuoi

Questo è specifico per configurazioni non custodiali ed è non negoziabile. Payora deriva gli indirizzi di ricezione solo da materiale di chiave pubblica — il tuo xPub o chiave pubblica master. Le chiavi private non toccano mai il server. Questo è l'intero modello di sicurezza e comporta un requisito fondamentale: l'xPub che hai incollato deve essere quello che il tuo portafoglio possiede effettivamente.

Quindi verificalo in modo indipendente. Prendi un indirizzo che il server ha derivato per una fattura, deriva lo stesso indice dal tuo xPub tu stesso — nel tuo software di portafoglio, o con qualsiasi libreria HD-wallet offline — e confronta le stringhe carattere per carattere. Se corrispondono, ogni pagamento arriva da qualche parte da cui puoi spendere. Se non corrispondono, ogni pagamento è perso, silenziosamente, con un checkout verde e un ordine pagato a farti compagnia. Il spiegatore xPub e HD walletti guida attraverso la derivazione.

Fallo prima di andare live. Non dopo il primo reclamo.

Il compromesso, dichiarato onestamente

Nessun sandbox significa che il tuo primo vero test costa un po' di soldi e un po' di attenzione. Questo è un costo genuino e non farò finta del contrario. Ciò che ottieni in cambio è un test che è stato vero. Un sandbox ti avrebbe dato un segno di spunta verde per la chiamata API e non ti avrebbe detto nulla sul blocco del tasso, sulla politica di conferma, sul percorso di prelievo, o se gli indirizzi erano tuoi — le quattro cose che decidono effettivamente se vieni pagato.

Un dollaro, un pomeriggio e una lista di controllo battono un simulatore che è d'accordo con te.

Pronto a farlo? Crea un account gratuito su /register, conia la tua prima fattura da /accept-payments, e lavora lungo la lista. L'intera scala richiede circa un'ora e all'incirca un dollaro.