Sviluppatori

Una chiamata. Un link di pagamento.

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.

  1. Crei il pagamento

    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"
      }'
  2. Porti il Suo cliente al link

    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"
    }
  3. Riceva la notifica

    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"
    }

Riferimento rapido

Intestazioni, campi, stati ed errori di POST /payments/?action=fast-track. Il dettaglio completo è nella guida.

Intestazioni della richiesta
IntestazioneConvalida
X-API-KeyLa Sua chiave API di Wealthreader, con i pagamenti attivi.
Idempotency-KeyDa 16 a 128 caratteri: lettere, numeri e . _ : -. È il Suo riferimento del pagamento e torna nella notifica come customer_reference.
Campi del corpo
CampoConvalidaObbligatorio
amountImporto in euro come stringa, con al massimo due decimali: "2450.00". Minimo 0.01.Sì
currencyEUR.Sì
beneficiary.nameNome del beneficiario, da 1 a 140 caratteri.Sì
beneficiary.ibanIBAN del beneficiario, senza spazi e con cifre di controllo valide. Non occorre registrarlo prima.Sì
referenceCausale che vedrà il Suo cliente e che compare nell’estratto conto, fino a 140 caratteri.Sì
priorityinstant per il bonifico istantaneo o normal per il bonifico ordinario.Sì
notification_urlURL https pubblica a cui inviamo la notifica ok o ko.Sì
logoURL https pubblica del logo della Sua azienda in SVG, che la pagina di pagamento mostra accanto al beneficiario.No
Stati del pagamento e notifica
payment_statusSignificatooutcome
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
Codici di errore
HTTPCodiceSignificato
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.

Dettagli di integrazione

Idempotente per progettazione

La stessa chiave con lo stesso corpo restituisce lo stesso link: una chiamata ripetuta non crea mai un secondo pagamento.

Istantaneo o ordinario

Scelga per ogni pagamento il bonifico istantaneo o quello ordinario. Se la banca non accetta l’istantaneo, la notifica arriva come ko.

Il Suo marchio nel pagamento

Invii l’URL del Suo logo in SVG e la pagina di pagamento lo mostra accanto al nome del beneficiario.

La pagina di pagamento

Il Suo cliente controlla importo, beneficiario e causale, sceglie la propria banca e autorizza. Per ora la pagina viene mostrata in spagnolo.

Non chieda un bonifico al Suo cliente: gli invii il pagamento già pronto

Le mostriamo FastTrackPay applicato agli incassi della Sua attività.

Richieda una demo