Status, consultas periódicas de status e reconciliação

Consulta a partir do 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 é opcional e true por padrão. Wealth Reader limita consultas externas pela intenção; aplique backoff também no backend e não crie outra intenção desde que o resultado seja ambíguo.

Três dimensões diferentes

A única confirmação positiva é payment_status: settled, derivada de um estado explícito do banco que confirma a liquidação. Um resultado técnico DONE, interaction_status: completed ou payment_status: pending nunca equivale a liquidação.

Resultado ambíguo

Uma queda de rede não reconhecida, tempo de espera ou resposta após a emissão do início altera a intenção para reconciliation_required e expõe payment_status: unknown. O início não se repete automaticamente.

O provedor atual não oferece uma consulta que reconstrua uma iniciação cuja resposta foi perdida: sua consulta de estado requer o contexto opaco retornado por essa mesma iniciação. Portanto, esse caso precisa de reconciliação manual; não pode ser recuperado por consulta periódica do estado automático ou buscando o ID callback.

Nesse caso:

1. manter a chave de idempotência e o identificador;
2. não cria outra intenção nem autoriza novamente;
3. Veja o status autenticado da Wealth Reader e mantenha sua referência segura de reconciliação;
4. entre em contato com o suporte técnico; não continue verificando o status quando automatic_recovery estiver false.

Para uma intenção que precisa de reconciliação manual, a consulta servidor para servidor pode 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"
  }
}

Esses identificadores são referências com dados sensíveis removidos, destinadas ao suporte. Eles não são entregues ao widget e não permitem que o cliente consulte ou reconstrua o estado interno do provedor.

reason é um código Wealth Reader, nunca o texto do fornecedor. initiation_rejected indica que o fornecedor respondeu com uma rejeição definitiva da iniciação; initiation_response_unavailable, que não houve resposta reconhecível. Em ambos os casos, a iniciação já foi transmitida, então não é repetida: mantenha a referência e entre em contato com o suporte técnico.

Retorno e replay

O retorno de SCA chega a um callback exclusivo de pagamentos. Wealth Reader valida a correlação, encaminha os parâmetros do banco ao provedor sem alterações (nomes inesperados são registrados, mas nunca causam a rejeição de um retorno já autorizado), processa o retorno uma única vez e preserva estado sensível criptografado. Uma repetição retorna apenas HTTP 409; não dependa de um código interno no corpo da resposta.

A autenticação pode exigir múltiplos redirecionamentos. Cada REDIRECT validado continua na mesma janela de SCA e abre um novo checkpoint callback; não cria outra iniciação. Um resultado DECOUPLED mantém a intenção em processing para que o widget consulte o status. Um RETRY explícito repete apenas a conclusão já preparada, com uma espera limitada e número de tentativas. ERROR, PASSWORD, MORE_INFO, SELECT_OPTION, um resultado desconhecido ou o esgotamento desses limites terminam em reconciliação, nunca em uma nova iniciação.

O comerciante não precisa publicar ou processar essa callback. Esta versão não envia webhooks para o comerciante: o contrato público de confirmação é a consulta periódica do estado servidor-para-servidor.

Fechando o widget

flow_closed comunica que a interação visível terminou. O frontend pode fechar o modal, mas não deve mostrar "pago" por esse evento. O backend retém a responsabilidade de confirmar ou reconciliar o pagamento.

Próximo passo

Complete a lista de Segurança e Testes.