Estados, sondeo y conciliación

Consultar desde el 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 es opcional y vale true por defecto. Wealth Reader limita las consultas externas por intención; aplique backoff también en su backend y no cree otra intención mientras el resultado sea ambiguo.

Tres dimensiones distintas

La única confirmación positiva es payment_status: settled, derivada de un estado bancario explícito de liquidación. Un resultado técnico DONE, interaction_status: completed o payment_status: pending nunca equivale a liquidación.

Resultado ambiguo

Una caída de red, timeout o respuesta no reconocida después de emitir el inicio cambia la intención a reconciliation_required y expone payment_status: unknown. No se repite automáticamente la iniciación.

El proveedor actual no ofrece una consulta que reconstruya una iniciación cuya respuesta se perdió: su consulta de estado requiere el contexto opaco devuelto por esa misma iniciación. Por tanto, ese caso necesita conciliación manual; no puede recuperarse mediante sondeo automático ni buscando el identificador de callback.

En ese caso:

1. conserve el identificador y la clave de idempotencia;
2. no cree otra intención ni vuelva a autorizar;
3. consulte el estado autenticado de Wealth Reader y conserve su referencia segura de conciliación;
4. escale a soporte; no continúe sondeando cuando automatic_recovery sea false.

Para una intención que necesita conciliación manual, la consulta server-to-server puede incluir:

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

Esos identificadores son referencias redactadas para soporte. No se entregan al widget y no permiten que el cliente consulte ni reconstruya el estado interno del proveedor.

reason es un código propio de Wealth Reader, nunca texto del proveedor. initiation_rejected indica que el proveedor respondió con un rechazo definitivo a la iniciación; initiation_response_unavailable, que no hubo una respuesta reconocible. En ambos casos la iniciación ya se transmitió, por lo que no se repite: conserve la referencia y escale a soporte.

Callback y repetición

El retorno SCA llega a un callback exclusivo de pagos. Wealth Reader valida la correlación, reenvía al proveedor los parámetros del banco tal cual (los nombres no previstos se registran, nunca rechazan un retorno ya autorizado), consume el retorno una sola vez y conserva el estado sensible cifrado. Una repetición responde únicamente HTTP 409; no dependa de un código interno en el cuerpo.

La autenticación puede necesitar varias redirecciones. Cada REDIRECT validado continúa en la misma ventana SCA y abre un nuevo checkpoint de callback; no crea otra iniciación. Un resultado DECOUPLED mantiene la intención en processing para que el widget consulte el estado. Un RETRY explícito repite únicamente la finalización ya preparada, con espera y número de intentos acotados. ERROR, PASSWORD, MORE_INFO, SELECT_OPTION, un resultado desconocido o el agotamiento de esos límites terminan en conciliación, nunca en una nueva iniciación.

El comercio no necesita publicar ni procesar ese callback. Esta versión no envía webhooks al comercio: el contrato público de confirmación es el sondeo server-to-server.

Cierre del widget

flow_closed comunica que terminó la interacción visible. El frontend puede cerrar el modal, pero no debe mostrar «pagado» por ese evento. El backend conserva la responsabilidad de confirmar o conciliar.

Siguiente paso

Complete la lista de Seguridad y pruebas.