Statuses, polling and reconciliation

Query from the 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 is optional and defaults to true. Wealth Reader rate-limits external queries per intent; apply backoff in your backend too, and do not create another intent while the outcome is ambiguous.

Three separate dimensions

The only positive confirmation is payment_status: settled, derived from an explicit bank settlement status. A technical DONE result, interaction_status: completed or payment_status: pending never means settlement.

Ambiguous outcome

A network failure, timeout or unrecognized response after sending the initiation changes the intent to reconciliation_required and exposes payment_status: unknown. Initiation is not automatically repeated.

The current provider does not offer a query that reconstructs an initiation whose response was lost: its status query requires the opaque context returned by that same initiation. This case therefore needs manual reconciliation; it cannot be recovered by automatic polling or by looking up the callback identifier.

In that case:

1. retain the identifier and idempotency key;
2. do not create another intent or authorize again;
3. query the authenticated Wealth Reader status and retain your safe reconciliation reference;
4. escalate to support; do not keep polling when automatic_recovery is false.

For an intent requiring manual reconciliation, the server-to-server query may 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"
  }
}

These identifiers are redacted references for support. They are not delivered to the widget and do not allow the client to query or reconstruct the provider's internal state.

reason is a Wealth Reader code, never provider text. initiation_rejected means that the provider definitively rejected the initiation; initiation_response_unavailable means that no recognizable response was received. In both cases, initiation has already been transmitted and must not be repeated: retain the reference and escalate to support.

Callback and replay

The SCA return reaches a payments-only callback. Wealth Reader validates correlation, forwards the bank's parameters to the provider unchanged (unexpected names are logged, never used to reject an already authorized return), consumes the return once and keeps sensitive state encrypted. A replay returns only HTTP 409; do not depend on an internal code in the body.

Authentication may require several redirects. Each validated REDIRECT continues in the same SCA window and opens a new callback checkpoint; it does not create another initiation. A DECOUPLED result keeps the intent in processing so the widget can query its status. An explicit RETRY repeats only the already prepared finalization, with bounded delays and attempts. ERROR, PASSWORD, MORE_INFO, SELECT_OPTION, an unknown result or exhaustion of those limits leads to reconciliation, never to a new initiation.

The merchant does not need to publish or process this callback. This version does not send webhooks to the merchant: the public confirmation contract is server-to-server polling.

Widget closure

flow_closed indicates that the visible interaction has ended. The frontend can close the modal, but must not display “paid” on that event. The backend remains responsible for confirmation or reconciliation.

Next step

Complete the Security and testing checklist.