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

Pagaments

Estats, consultes periòdiques i conciliació

Comprova l'estat des del teu backend fins que obtinguis una conclusió bancària. Un callback, un retorn SCA o el tancament d'un widget no constitueixen confirmació financera.

Consulta des del 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 és opcional i true per defecte. Wealth Reader limita les consultes externes per intenció; aplica el backoff també al backend i no creïs una altra intenció sempre que el resultat sigui ambigu.

Tres dimensions diferents

Camp Valors fonamentals El que respons
state ready, authorization_required, processing, reconciliation_required, terminals Estat de flux durador.
interaction_status not_started, authorization_required, processing, completed, finished Si la interacció tècnica ha acabat o continua.
payment_status not_initiated, pending, unknown, settled, rejected, cancelled, expired, failed Resultat financer normalitzat.

L'única confirmació positiva és payment_status: settled, derivada d'un estat bancari explícit de liquidació. Un resultat tècnic DONE, interaction_status: completed o payment_status: pending mai equival a una liquidació.

Resultat ambigu

Una caiguda de xarxa, un temps d'espera exhaurit o una resposta no reconeguda després d'enviar l'inici canvia la intenció a reconciliation_required i exposa payment_status: unknown. L'inici no es repeteix automàticament.

El proveïdor actual no ofereix una consulta que reconstrueixi una iniciació la resposta de la qual s'ha perdut: la seva consulta d'estat requereix el context opac retornat per aquesta mateixa iniciació. Per tant, aquest cas necessita reconciliació manual; no es pot recuperar mitjançant consulta automàtica de l'estat ni buscant l'ID callback.

En aquest cas:

  1. mantenir la clau d'idempotència i l'identificador;
  2. no crea una altra intenció ni autoritza de nou;
  3. Consulta l'estat autenticat de Wealth Reader i conserva la teva referència segura de conciliació;
  4. contacta amb el suport; no continuïs consultant l'estat quan automatic_recovery sigui false.

Per a una intenció que necessiti reconciliació manual, la consulta servidor a servidor pot incloure:

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

Aquests identificadors són referències expurgades per al suport. No es lliuren al widget i no permeten al client consultar o reconstruir l'estat intern del proveïdor.

reason és un codi Wealth Reader, mai el text del proveïdor. initiation_rejected indica que el proveïdor va respondre amb un rebuig definitiu de la iniciació; initiation_response_unavailable, que no hi va haver cap resposta reconeixible. En ambdós casos la iniciació ja s'ha transmès, així que no es repeteix: mantingueu la referència i escaleu a suport.

Referència i repetició

La devolució SCA arriba a un callback de pagament exclusiu. Wealth Reader valida la correlació, reenvia els paràmetres del banc al proveïdor tal com són (es registren noms imprevistos, mai rebutgen una devolució ja autoritzada), consumeix la devolució només una vegada i preserva l'estat sensible xifrat. Una repetició només respon HTTP 409; no depèn d'un codi intern al cos.

L'autenticació pot requerir múltiples redireccions. Cada REDIRECT validada continua a la mateixa finestra de SCA i obre un nou punt de control de callback; no crea una altra iniciació. Un resultat DECOUPLED manté la intenció en processing perquè el widget consulti l'estat. Un RETRY explícit només repeteix la finalització ja preparada, amb una espera limitada i nombre d'intents. ERROR, PASSWORD, MORE_INFO, SELECT_OPTION, un resultat desconegut o l'esgotament d'aquests límits acaben en conciliació, mai en una nova iniciació.

El comerciant no necessita publicar ni processar aquesta callback. Aquesta versió no envia webhooks al comerciant: el contracte públic de confirmació és una consulta servidor a servidor.

Tancant el widget

flow_closed comunica que la interacció visible ha acabat. El frontend pot tancar el modal, però no ha de mostrar "pagat" per aquell esdeveniment. El backend manté la responsabilitat de confirmar o conciliar.

Següent pas

Completa la llista de Seguretat i proves.

Última actualització