Developers API & Widget
ES
ES · Español

Pagos

Estados, sondeo y conciliación

Consulte el estado desde su backend hasta obtener una conclusión bancaria. Un callback, un retorno SCA o el cierre del widget no constituyen una confirmación financiera.

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

Campo Valores principales Qué responde
state ready, authorization_required, processing, reconciliation_required, terminales Estado durable del flujo.
interaction_status not_started, authorization_required, processing, completed, finished Si terminó o continúa la interacción técnica.
payment_status not_initiated, pending, unknown, settled, rejected, cancelled, expired, failed Resultado financiero normalizado.

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

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.

Callback y repetición

El retorno SCA llega a un callback exclusivo de pagos. Wealth Reader valida la correlación y los parámetros permitidos, 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.

Última actualización