Pagamenti Fast Track

Il pagatore apre quell'URL e autorizza il pagamento nella propria banca. Dietro le quinte viene creata la stessa intenzione immutabile del resto dell'API: importo, beneficiario e causale vengono fissati prima di arrivare al browser e l'intestazione Idempotency-Key evita un secondo addebito se la chiamata si interrompe.

Creare il pagamento

POST /payments/?action=fast-track

Intestazioni obbligatorie: Content-Type: application/json, X-API-Key e Idempotency-Key. La chiave ha da 16 a 128 caratteri, inizia con una lettera o un numero e ammette solo lettere, numeri e . _ : -; un UUID v4 va bene. Se manca o la sua lunghezza non è valida, la risposta è 400 idempotency_key_required; se usi altri caratteri, 422 invalid_customer_reference. Questa chiave è anche il riferimento dell'esercente: non serve inviarla nel corpo. Se ripeti la stessa chiave con lo stesso corpo, ricevi di nuovo lo stesso URL. Se la riutilizzi con dati diversi, la risposta è 409 idempotency_conflict.

Tutti i campi sono obbligatori tranne logo. Il corpo segue una lista di campi consentiti. Un campo in più, o uno obbligatorio mancante, risponde 422 invalid_request. logo fa parte del pagamento: ripetere la stessa Idempotency-Key con un altro logo dà anch'esso 409 idempotency_conflict.

Un bonifico istantaneo non ha un limite proprio in questa API. La banca rifiuta quello che non può accettare, anche per importo, e il rifiuto arriva come KO al notification_url.

: "${WR_API_KEY:?Defina WR_API_KEY en el entorno seguro de su backend}"
: "${WR_PAYMENT_IDEMPOTENCY_KEY:?Genere un UUID v4 para este pago}"

curl --request POST 'https://api.wealthreader.com/payments/?action=fast-track' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${WR_API_KEY}" \
  --header "Idempotency-Key: ${WR_PAYMENT_IDEMPOTENCY_KEY}" \
  --data '{
    "amount": "15.50",
    "currency": "EUR",
    "beneficiary": {
      "name": "Comercio Online S.L.",
      "iban": "ES9121000418450200051332"
    },
    "reference": "Pedido 78901",
    "priority": "normal",
    "notification_url": "https://tienda.example.com/pagos/aviso",
    "logo": "https://tienda.example.com/marca/logo.svg"
  }'

La risposta, con 201 la prima volta e 200 se la chiave esisteva già, contiene l'URL e l'identificatore del pagamento:

{
  "url": "https://widget.wealthreader.com/payments/pay/#payment_intent_id=…&widget_token=…&api_origin=https%3A%2F%2Fapi.wealthreader.com",
  "payment_intent_id": "22222222-2222-4222-8222-222222222222"
}

Reindirizza il pagatore all'URL. Il token si trova nel frammento, scade con il widget (di solito 15 minuti) e non deve essere registrato nei tuoi log. Conserva il payment_intent_id insieme al tuo ordine.

Avviso di OK o KO

Quando Wealthreader controlla lo stato del pagamento e lo trova in uno stato finale, esegue un POST a notification_url con Content-Type: application/json e User-Agent: WealthReader-Payments:

{
  "outcome": "ok",
  "payment_status": "settled",
  "customer_reference": "11111111-1111-4111-8111-111111111111",
  "payment_intent_id": "22222222-2222-4222-8222-222222222222"
}

• outcome è ok solo se la banca ha regolato il pagamento (settled). rejected, cancelled, expired e failed generano l'avviso ko. Un esito ambiguo (reconciliation_required) non è finale e non viene notificato.
• customer_reference è la tua Idempotency-Key e payment_intent_id è l'identificatore restituito alla creazione del pagamento.
• Rispondi 2xx per considerare l'avviso consegnato. Wealthreader attende al massimo 3 secondi e non segue i reindirizzamenti.
• Lo stesso avviso può arrivare più di una volta: tratta customer_reference più outcome come idempotenti.
• Un URL che non sia https pubblico viene rifiutato alla creazione del pagamento e viene ricontrollato prima di ogni invio.

Quando arriva. Lo stato viene controllato mentre il pagatore resta sulla pagina di pagamento, che lo consulta fino all'esito finale o fino alla scadenza della sessione di pagamento, e ogni volta che consulti POST /payments/?action=status. Non esiste un invio programmato separato: se il pagatore chiude la pagina prima che la banca concluda, o se il tuo server non risponde 2xx, l'avviso viene inviato al controllo successivo. Per questo, se non hai ricevuto l'avviso qualche minuto dopo aver reindirizzato il pagatore, consulta lo stato con il payment_intent_id; questa consultazione fa partire anche l'avviso in sospeso. Vedi Stati, polling e riconciliazione.

L'avviso non è firmato. Prima di consegnare un bene o un servizio di valore, conferma l'esito con POST /payments/?action=status usando la tua X-API-Key e il payment_intent_id: solo payment_status: settled in quella risposta costituisce una conferma finanziaria.