Idempotente per progettazione
La stessa chiave con lo stesso corpo restituisce lo stesso link: una chiamata ripetuta non crea mai un secondo pagamento.
Sviluppatori
FastTrackPay è un endpoint dell’API di pagamento di Wealthreader: HTTPS e JSON. Invii il pagamento, reindirizzi il Suo cliente e riceva la notifica con il Suo riferimento.
Per iniziare, attiviamo i pagamenti e il Suo profilo di pagamento sulla Sua chiave API di Wealthreader. Se utilizza già l’API, è la stessa chiave.
Un POST con la Sua chiave API, una chiave di idempotenza che è anche il Suo riferimento e il corpo del pagamento: importo, valuta, beneficiario, causale, priorità e URL di notifica.
# Creare il pagamento
curl 'https://api.wealthreader.com/payments/?action=fast-track' \
-H "X-API-Key: $API_KEY" \
-H "Idempotency-Key: invoice-F-2026-104" \
-H "Content-Type: application/json" \
-d '{
"amount": "2450.00",
"currency": "EUR",
"beneficiary": {
"name": "Azienda Esempio S.r.l.",
"iban": "ES9121000418450200051332"
},
"reference": "Fattura F-2026-104",
"priority": "instant",
"notification_url": "https://example.com/payments/notice"
}'
La risposta contiene l’URL del pagamento e il suo identificativo. Reindirizzi il Suo cliente all’URL: scade dopo pochi minuti (15 per impostazione predefinita), quindi la crei quando il cliente sta per pagare.
{
"url": "https://widget.wealthreader.com/payments/pay/#payment_intent_id=…&widget_token=…",
"payment_intent_id": "22222222-2222-4222-8222-222222222222"
}
Quando il pagamento raggiunge uno stato finale, inviamo un POST alla Sua notification_url con outcome ok o ko e il Suo riferimento in customer_reference. Risponda con un codice 2xx.
La notifica può arrivare più di una volta e non è firmata: prima di consegnare qualcosa di valore, confermi lo stato con POST /payments/?action=status.
{
"outcome": "ok",
"payment_status": "settled",
"customer_reference": "invoice-F-2026-104",
"payment_intent_id": "22222222-2222-4222-8222-222222222222"
}
Intestazioni, campi, stati ed errori di POST /payments/?action=fast-track. Il dettaglio completo è nella guida.
| Intestazione | Convalida |
|---|---|
X-API-Key | La Sua chiave API di Wealthreader, con i pagamenti attivi. |
Idempotency-Key | Da 16 a 128 caratteri: lettere, numeri e . _ : -. È il Suo riferimento del pagamento e torna nella notifica come customer_reference. |
| Campo | Convalida | Obbligatorio |
|---|---|---|
amount | Importo in euro come stringa, con al massimo due decimali: "2450.00". Minimo 0.01. | Sì |
currency | EUR. | Sì |
beneficiary.name | Nome del beneficiario, da 1 a 140 caratteri. | Sì |
beneficiary.iban | IBAN del beneficiario, senza spazi e con cifre di controllo valide. Non occorre registrarlo prima. | Sì |
reference | Causale che vedrà il Suo cliente e che compare nell’estratto conto, fino a 140 caratteri. | Sì |
priority | instant per il bonifico istantaneo o normal per il bonifico ordinario. | Sì |
notification_url | URL https pubblica a cui inviamo la notifica ok o ko. | Sì |
logo | URL https pubblica del logo della Sua azienda in SVG, che la pagina di pagamento mostra accanto al beneficiario. | No |
payment_status | Significato | outcome |
|---|---|---|
settled |
La banca ha regolato il pagamento. | ok |
rejected |
La banca ha rifiutato il pagamento, anche per l’importo o perché non accetta il bonifico istantaneo. | ko |
cancelled |
È stato annullato prima di essere completato. | ko |
expired |
La sessione di pagamento è scaduta senza essere completata. | ko |
failed |
Non è stato possibile completare il pagamento. | ko |
pending |
In corso: non è ancora uno stato finale. | Ancora nessuna notifica |
| HTTP | Codice | Significato |
|---|---|---|
400 |
idempotency_key_required |
Manca l’intestazione Idempotency-Key o la sua lunghezza non è valida. |
401 |
invalid_api_key |
Chiave API non valida. |
403 |
payments_not_allowed, payment_profile_required |
La Sua chiave non ha i pagamenti attivi o manca il profilo di pagamento. |
409 |
idempotency_conflict |
Ha riutilizzato una Idempotency-Key con dati diversi. |
422 |
invalid_request, invalid_amount, invalid_beneficiary, invalid_notification_url |
Corpo non valido: un campo in più o mancante, oppure importo, beneficiario o URL di notifica errati. |
429 |
api_limit_reached |
Ha raggiunto il limite di chiamate. |
503 |
payments_disabled |
I pagamenti non sono disponibili in questo momento. |
Gli errori restituiscono un JSON con success a false e il codice della tabella in error.code.
La stessa chiave con lo stesso corpo restituisce lo stesso link: una chiamata ripetuta non crea mai un secondo pagamento.
Scelga per ogni pagamento il bonifico istantaneo o quello ordinario. Se la banca non accetta l’istantaneo, la notifica arriva come ko.
Invii l’URL del Suo logo in SVG e la pagina di pagamento lo mostra accanto al nome del beneficiario.
Il Suo cliente controlla importo, beneficiario e causale, sceglie la propria banca e autorizza. Per ora la pagina viene mostrata in spagnolo.
Apri la guida Pagamenti Fast Track (si apre in una nuova scheda) Apri il riferimento dell’API (si apre in una nuova scheda) Richiedi l’accesso
Le mostriamo FastTrackPay applicato agli incassi della Sua attività.