Recusas de Pagamento

Visão Geral

A criação de uma cobrança na Selectwin é assíncrona. Quando você chama POST /v1/transactions (ou cria/renova uma Assinatura), a API responde imediatamente com 201 Created e a transação nasce com status: "pending". A cobrança junto ao adquirente é processada em segundo plano.

Por isso, uma recusa de cartão normalmente NÃO chega como um erro HTTP síncrono nessa chamada. O resultado da cobrança — incluindo uma recusa — aparece de duas formas:

1. No objeto da transação, cujo status passa a failed (recusa).
2. Em um webhook: a recusa dispara o evento transaction.failed (ver Catálogo de Eventos).

Por que assim? A orquestração pode tentar mais de uma rota/adquirente antes de concluir o resultado. Acompanhar a transação pelos webhooks é o padrão recomendado — veja Proibição de Polling.

Como acompanhar o resultado da cobrança

Os status possíveis de uma transação incluem pending, pre-authorized, approved, failed, refused, canceled, refunded, chargeback, dispute, fraud-review, analyzing e awaiting.

O envelope de erro 402 (Payment Required)

Em superfícies síncronas de pagamento, uma falha de processamento pode retornar HTTP 402 com o envelope de erro padrão (os mesmos campos de qualquer erro — status, statusCode, category, code, message, resource; ver Tratamento de Erros):

{
  "error": {
    "status": "Payment Required",
    "statusCode": 402,
    "category": "payment",
    "code": "paymentDeclined",
    "message": "The payment was declined by the issuer.",
    "resource": "payorch"
  }
}

Importante: o envelope de erro não carrega os campos type, displayMessage nem reversible. Esses não fazem parte do contrato de erro público. Trate o resultado pelo error.code (em erros síncronos) e pelo status da transação + webhooks (no fluxo assíncrono de criação).

Boas Práticas

1. Não faça polling para descobrir o resultado — escute os webhooks transaction.approved / transaction.failed (ver Proibição de Polling).
2. Keye no error.code (em respostas de erro síncronas) e no status da transação, não no texto de message (que pode mudar).
3. Em caso de recusa (failed), para cobrar de novo inicie uma nova transação — idealmente com outro cartão ou forma de pagamento.
4. Teste os cenários com os Cartões de Teste (ex.: o cartão de failed) antes de ir para produção.

Notas

• Erros de configuração/conta (ex.: nenhum provedor configurado para o modo solicitado) retornam 422 com code: "providerNotConfigured" e resource: "payorch".
• O catálogo de error.code por recurso (com o status HTTP de cada um) está em Catálogo de Códigos de Erro.