Statusuri, consultări periodice privind statutul și reconciliere

Interogare din 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 este opțional și true implicit. Wealth Reader limitează interogările externe prin intenție; aplică backoff și pe backend și nu crea o altă intenție atâta timp cât rezultatul este ambiguu.

Trei dimensiuni diferite

Singura confirmare pozitivă este payment_status: settled, derivată dintr-un stare bancară care confirmă explicit decontarea. Un rezultat tehnic DONE, interaction_status: completed sau payment_status: pending nu constituie niciodată decontare.

Rezultat ambiguu

O întrerupere nerecunoscută a rețelei, un timeout sau un răspuns după ce startul este emis schimbă intenția de a reconciliation_required și expune payment_status: unknown. Pornirea nu se repetă automat.

Furnizorul curent nu oferă o interogare care să reconstruiască o inițiere al cărei răspuns a fost pierdut: interogarea sa de stare necesită contextul opac returnat de aceeași inițiere. Prin urmare, acest caz necesită reconciliere manuală; nu poate fi recuperat prin interogare periodică a stării automate sau prin căutarea ID-ului callback.

În acest caz:

1. păstrează cheia de idempotență și identificatorul;
2. nu creează o altă intenție și nu autorizează din nou;
3. Vizualizați statusul autentificat al Wealth Reader și păstrați referința securizată pentru reconciliere;
4. contactați suportul tehnic; nu continuați să verificați statusul când automatic_recovery este false.

Pentru o intenție care necesită reconciliere manuală, interogarea server-la-server poate include:

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

Acești identificatori sunt referințe pentru suport din care au fost eliminate datele sensibile. Ei nu sunt livrați către widget și nu permit clientului să interogheze sau să reconstruiască starea internă a furnizorului.

reason este un cod Wealth Reader, niciodată textul furnizorului. initiation_rejected indică faptul că furnizorul a răspuns cu o respingere definitivă a inițierii; initiation_response_unavailable, că nu a existat un răspuns recognoscibil. În ambele cazuri, inițierea a fost deja transmisă, deci nu se repetă: păstrează referința și contactează suportul tehnic.

Callback și reluare

Returnarea SCA ajunge la o callback de plată exclusivă. Wealth Reader validează corelația, transmite parametrii băncii către furnizor așa cum sunt (numele neprevăzute sunt înregistrate, nu resping niciodată o returnare deja autorizată), procesează revenirea o singură dată și păstrează starea criptată și sensibilă. O repetiție răspunde doar HTTP 409; nu depinde de un cod intern în corp.

Autentificarea poate necesita mai multe redirecționări. Fiecare REDIRECT validată continuă în aceeași fereastră de SCA și deschide un nou punct de control callback; nu creează o altă inițiere. Un rezultat DECOUPLED menține intenția în processing ca widgetul să interogheze statusul. Un RETRY explicit repetă doar finalizarea deja pregătită, cu un număr limitat de așteptare și de încercări. ERROR, PASSWORD, MORE_INFO, SELECT_OPTION, un rezultat necunoscut sau epuizarea acestor limite se încheie cu reconciliere, niciodată cu o nouă inițiere.

Comerciantul nu trebuie să publice sau să proceseze acel callback. Această versiune nu trimite webhook-uri către comerciant: contractul public de confirmare este interogarea periodică a stării server-la-server.

Închiderea widget-ului

flow_closed comunică că interacțiunea vizibilă s-a încheiat. Frontend-ul poate închide modalul, dar nu trebuie să arate "plătit" pentru acel eveniment. Backend-ul își păstrează responsabilitatea de a confirma sau reconcilia plata.

Pasul următor

Completați lista Securitate și testare.