Crypto-casinò
Torrent Gear
Come funzionano i pagamenti API dei provider
L'API di pagamento è un contratto tra l'applicazione e il provider che trasforma «creare un pagamento», «confermare 3DS», «rimborsare», «pagare il cliente» e «ottenere lo status» in chiamate affidabili e ripetibili. Sotto il cofano ci sono dozzine di regole: tornizzazione, idempotency, webhook, antifrode, code, SLA e verifiche. Di seguito è una mappa pratica di come funziona la maggior parte dei provider.
Modello di base: quali entità sono quasi sempre
Payment/Cargo - Tentativo di prelievo (authorize + capture o subito purchase).
Payment Method - Card (PAN/token), conto bancario/alias, portafoglio, metodo locale.
Customer è l'essenza del cliente/pagatore (a volte opzionale).
Payout/Transfer è un pagamento in uscita per il cliente/merchant.
Rifund/Reversal - Ritorno al pagamento di origine (closed-loop).
Webhook Event - Notifica di stato asincrona.
Dispute/Marceback è una discussione sulla rete di pagamento (per carte).
Order/Invoice è il contesto aziendale intorno al pagamento.
Autenticazione e sicurezza
Chiavi API/OAUTh 2. 0/ mTLS per server-k-server.
I token client sono token monouso per frontend (per non illuminare i segreti).
Torning mappe - PAN va al provider; Lei conserva solo il token.
PCI DSS - Se vedi PAN, sei nella zona PCI; meglio evitare e utilizzare campi host/SDK.
HMAC firma webhook - verifica che l'evento provenga dal provider.
Architettura a due zone - fronte pubblico (JS/SDK) e backend privato (chiavi, risk-logic).
Idempotency, code e coerenza
Idempotency-Key nel titolo: la ripetizione della query (durante il timeout) non duplica.
L'Outbox/Saga ha detto che è stato concordato «spedire il pagamento».
I retrai con backoff sono solo per errori temporanei. La matrice retryable/no-retryable è obbligatoria.
Endpoint tipici (schemi e flow)
1) Carte (Visa/Mastercard, ecc.)
POST/payments - Crea un pagamento («amount», «currency», «payment _ method _ token», «capture» = false/true).
POST /payments/{id}/confirm — шаг 3-D Secure 2 (challenge/redirect result).
POST/payments/{ id }/capture - Cattura dopo autorizzazione (parziale/totale).
POST/payments/{ id }/refund - Restituisce (parti, fino all'importo originale).
GET /payments/{id} — статус (authorized, captured, failed, requires_action).
3-D Secure/SCA - Il provider restituirebbe «richiers _ action» + «client _ secret »/URL per challenge. Dopo la conferma del cliente, il fronte restituirà il risultato al tuo backend.
2) A2A / Open Banking (Pay by Bank)
POST/payments ha risposto con «redirect _ url» alla banca del cliente.
Il cliente viene autorizzato dalla banca «webhook» payment. succeeded/failed`.
GET/payments/{ id} è lo stato finale (spesso solo asincrono).
3) Metodi locali (PIX, PayID, FPX, iDEAL, ecc.)
POST/payments riceverà «qr _ code »/« deeplink »/« copy _ code».
Mostra all'utente che aspetta webhook l'iscrizione.
Timeout e TTL per il codice fanno parte del contratto.
4) Pagamenti (payouts)
POST /payouts (`amount`, `currency`, `destination_token` или `card_token`/`bank_alias`).
GET /payouts/{id} — статусы (`queued`, `sent`, `paid`, `failed`).
Webhook'payout '. paid/failed "è la fonte della verità.
Loop chiuso: è preferibile pagare per la fonte (reversal) prima delle alternative.
Webhook'la fonte della verità '
Eventi dì payment ". pending/authorized/captured/failed`, `payment. requires_action`, `refund. succeeded`, `payout. paid`, `dispute. created, eccetera.
Consegna: con i retrai, firmata HMAC, spesso «almeno una volta», mantenendo l'idepotenza del processore.
Best practice: elaborare il webhook, aggiornare il ledger e rispondere 2xx. Ogni logica aziendale dopo è asincrona.
Elaborazione degli errori e degli stati
Codice HTTP: «2xx» successo; «4xx» errore del client (convalida, frod/rifiuto della banca, token errato); «5xx» - provider.
Причины отказов: `insufficient_funds`, `do_not_honor`, `stolen_card`, `limit_exceeded`, `risk_decline`, `bank_unavailable`.
Finestre di ripetizione: per 3DS, non è possibile ritrarre infinitamente; A2A: TTL ridirect/codice per payouts - backoff.
Antifrode e rischi
Device-fingerprinting e dati comportamentali - tramite il provider JS/SDK o il proprio livello.
Elenchi: rischio BIN, nero/bianco dei metodi/ASN/paesi.
Gate regolabili: limiti per nuovi strumenti, «cool-off», velocity, controlli soglia RG/AML.
Criteri: 'pass/step-up/hold/block', basato su schemi + regole.
Caratteristiche dei binari
Carte: autorizzazioni vs clearing (possibile spostamento dell'importo), 3DS2, rimborsi per operazione iniziale, controversie/charjback.
A2A/Open Banking: redirect/consent-flow, alto aprove, basso costo; Tutto è asincrono e dipende molto dalla banca.
Velocità locali: QR/alias, webhook istantaneo, TTL e compressione rigorosa.
OCT/Push-to-Card - Richiede il token card, il supporto Fast Funds per l'emittente, senza 3DS.
Versioning e compatibilità
Le versioni API sono «/v1 »,« data-versioni »nell'intestazione o phicheflagi.
Modifiche Backwards-compatibile - Solo campi non distruttivi.
Deprecazioni: grafico di output di versioni precedenti, gate di migrazione, Web duplicati durante la migrazione.
Osservabilità e SLA
Metriche: p95 tempo di autorizzazione/pagamento, approve rate secondo BIN/banca/metodo, quota di retrai, Web League.
Loghi: correlazione per «richiest _ id», «idempotency _ key», «payment _ id».
Alert: aumento dei rigori in una banca/paese specifica, aumento dei timeout, eventi duplicati.
Accoppiamento e finanza
Ledger: record doppio, registri immutabili, stati'authorized/captured/refunded '.
I rapporti del provider e della banca sono stati resi noti dal suo atore.
Indirizzi: conserva provider _ reference, network _ reference, payout _ reference, questo salva lo zapport.
Sandbox, certificazione e prode
Sandbox: token di prova/mappe/banche, simulazione 3DS/rediretti, «pulsanti» per gli stati del webhook.
Valigette di prova: successo/rifiuto, 3DS challenge, timeout del provider, webhook duplicato, parziale capture/refund, annullamento del redirect, payout fail.
Go-live: chiavi di prone, domini di webhook, IP-allowlist, abilitare antifrode, impostare limiti e alert.
Mini esempi (schematico)
Crea pagamento (carta)
POST /v1/payments
{
"amount": 9232, "currency": "EUR", "payment_method_token": "pm_tok_123", "capture": true, "metadata": {"order_id": "ORD-1001"}
}
→ 200 { "id": "pay_abc", "status": "requires_action", "next_action": {"type":"redirect", "url":"..."} }Webhook sul successo dell'iscrizione
POST /webhooks
{
"type": "payment. captured", "data": {"id":"pay_abc","amount":9232,"currency":"EUR","metadata":{"order_id":"ORD-1001"}}
}Pagamento (payout)
POST /v1/payouts
{
"amount": 5000, "currency": "EUR", "destination_token": "dest_tok_456", "metadata": {"user_id":"u_77"}
}Assegno foglio di implementazione
1. Architettura chiave: segreti server separati, client usa e getta.
2. Idempotency: ogni chiamata write + elaboratori idipotenti di webhoop.
3. Web Hookie firma HMAC, retrai, coda delle attività, monitoraggio delle lame.
4. 3DS/SCA e ready: elaborazione di RM/timeout, nuovo tentativo di friendly-UX.
5. Antifrode/limiti: velocity, nuovi oggetti, black list, RG/AML soglie.
6. Ledger e compressione, doppio filmato, incrocio a tre facce, alert di anomalie.
7. L'orchestrazione è il provider di riserva, le regole di routing BIN/paese/somma.
8. Monitoraggio: dashboard approve rate/p95/retrai, alert su banche/metodi.
9. Legale/PCI: tornitura, criteri di restituzione, loop di payouts chiuso.
10. Piano di degrado: canale kill-switch, code, modalità manuale per operazioni critiche.
Errori frequenti
Storage PAN sul proprio lato senza PCI o tornizzazione.
L'assenza di idempotency rappresenta una ripresa dei pagamenti e dei pagamenti in caso di timeout.
La logica delle risposte sincroniche non conta i webhoop.
Un provider per il mercato, senza fallback/cascata.
Nessuna procedura di cancellazione 3DS/Redirect per i cestini persi.
La scorciatoia si è rivelata una transazione «dipendente» e «perduta».
La mancanza di SLA e di alert chiari vede il problema del cliente, non lei.
Mini-FAQ
Cosa c'è di più sicuro, stato sincronizzato o webhook?
Webhook è la fonte della verità; La risposta sincrona è solo «accolta/necessaria azione».
Possiamo fare a meno di 3DS?
Dipende dalla regolazione/rischio. In CE/UK - SCA è obbligatorio; per l'high-risk è meglio di step-up.
Come aumentare l'approve rate?
Orchestrazione BIN/barattolo/metodo, binari locali, retrai intelligenti, descrittori corretti, antifrode a basso FPR.
Perché il payout non è immediato?
Dipende dal binario (EST/A2A/locale), dalla banca del destinatario e dai limiti. Facciamo una finestra onesta SLA e uno status stram.
I pagamenti API non sono solo «creare un pagamento». Questa è una disciplina: l'autenticazione sicura, la tornizzazione dei idempotency, i webhoop asincroni, il er e l'antifrode/AML, l'orchestrazione e il monitoraggio. Costruire un processo secondo questo schema, mantenere i canali di riserva e un UX trasparente - e il vostro livello di pagamento sarà veloce, prevedibile e resistente ai guasti di banche e fornitori.