Developers API & Widget
IT
ES · EspañolEN · EnglishFR · FrançaisCA · CatalàDA · DanskDE · DeutschEL · ΕλληνικάFI · SuomiGA · GaeilgeIT · ItalianoJA · 日本語NL · NederlandsNO · NorskPT · PortuguêsRO · RomânăRU · РусскийZH · 中文

Pagamenti

Stati, consultazioni periodiche sullo status e riconciliazione

Controlla lo stato del pagamento dal backend finché non ottieni una conclusione bancaria. Una callback, una ritorno SCA o la chiusura di un widget non costituiscono conferma finanziaria.

Query dal backend

: "${WR_API_KEY:?Defina WR_API_KEY en el entorno seguro de su backend}"

curl --request POST 'https://api.wealthreader.com/payments/?action=status' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${WR_API_KEY}" \
  --data '{
    "payment_intent_id": "11111111-1111-4111-8111-111111111111",
    "refresh": true
  }'

refresh è opzionale e true di default. Wealth Reader limita le query esterne per intento; applica il backoff anche sul backend e non creare un'altra intent purché il risultato sia ambiguo.

Tre dimensioni diverse

Campo Valori fondamentali Cosa rispondi
state ready, authorization_required, processing, reconciliation_required, terminali Stato di flusso duraturo.
interaction_status not_started, authorization_required, processing, completed, finished Se l'interazione tecnica sia finita o continui.
payment_status not_initiated, pending, unknown, settled, rejected, cancelled, expired, failed Risultato finanziario normalizzato.

L'unica conferma positiva è payment_status: settled, derivata da un esplicito stato bancario di avvenuto regolamento. Un risultato tecnico DONE, interaction_status: completed o payment_status: pending non equivale mai al regolamento del pagamento.

Risultato ambiguo

Un blackout di rete non riconosciuto, un timeout o una risposta dopo l'avvio cambia l'intento di reconciliation_required ed espone payment_status: unknown. L'avvio non si ripete automaticamente.

Il provider attuale non offre una query che ricostruisca un'iniziazione la cui risposta è stata persa: la sua query di stato richiede il contesto opaco restituito dalla stessa iniziazione. Pertanto, quel caso necessita di riconciliazione manuale; non può essere recuperata tramite una query periodica dello stato automatico o cercando l'ID callback.

In tal caso:

  1. mantenere la chiave di idempotenza e l'identificatore;
  2. non crea un'altra intenzione né autorizza nuovamente;
  3. Visualizza lo stato autenticato di Wealth Reader e conserva il tuo riferimento sicuro per la riconciliazione;
  4. contatta l'assistenza tecnica; non continuare a controllare lo stato quando automatic_recovery è false.

Per un intento che necessita di riconciliazione manuale, la query server-to-server può includere:

{
  "payment_status": "unknown",
  "reconciliation_required": true,
  "reconciliation": {
    "automatic_recovery": false,
    "reference": "wrp_recon_0123456789abcdef0123",
    "request_id": "11111111-1111-4111-8111-111111111111",
    "correlation_id": "22222222-2222-4222-8222-222222222222",
    "reason": "initiation_rejected"
  }
}

Questi identificatori sono riferimenti privati dei dati sensibili destinati al supporto. Non vengono consegnati al widget e non permettono al cliente di interrogare o ricostruire lo stato interno del provider.

reason è un codice Wealth Reader, mai il testo del fornitore. initiation_rejected indica che il fornitore ha risposto con un rifiuto definitivo dell'iniziazione; initiation_response_unavailable, che non c'è stata una risposta riconoscibile. In entrambi i casi l'iniziazione è già stata trasmessa, quindi non si ripete: mantenere il riferimento e contattare il supporto tecnico.

Richiamo e replay

Il ritorno SCA raggiunge un callback di pagamento esclusivo. Wealth Reader valida la correlazione, inoltra i parametri della banca al fornitore così come sono (vengono registrati nomi imprevisti, non rifiutano mai un ritorno già autorizzato), consuma il ritorno solo una volta e preserva lo stato sensibile criptato. Una ripetizione risponde solo HTTP 409; non dipende da un codice interno nel corpo.

L'autenticazione può richiedere più reindirizzamenti. Ogni REDIRECT validata continua nella stessa finestra SCA e apre un nuovo checkpoint callback; non crea un'altra iniziazione. Un risultato DECOUPLED mantiene l'intento in processing affinché il widget possa interrogare lo stato. Un RETRY esplicito ripete solo il completamento già preparato, con un tempo di attesa e un numero limitato di tentativi. ERROR, PASSWORD, MORE_INFO, SELECT_OPTION, un risultato sconosciuto o l'esaurimento di tali limiti terminano in riconciliazione, mai in una nuova iniziazione.

Il commerciante non è necessario pubblicare o elaborare tale callback. Questa release non invia webhook al commerciante: il contratto pubblico di conferma è la query periodica dello stato server-to-server.

Chiusura del widget

flow_closed comunica che l'interazione visibile è terminata. Il frontend può chiudere il modale, ma non deve mostrare "pagato" per quell'evento. Il backend mantiene la responsabilità di confermare o riconciliare il pagamento.

Passo successivo

Completa l'elenco dei Sicurezza e test.

Ultimo aggiornamento