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).

#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 motivo da recusa (payment.refused)

Quando a cobrança falha, o objeto da transação (e o payload do webhook transaction.failed) traz o motivo em payment.refused. Nas demais transações o campo é null.

{
  "status": "failed",
  "payment": {
    "refused": {
      "code": "insufficientFundsError",
      "type": "cardError",
      "category": "payment",
      "message": "Insufficient funds or limit.",
      "displayMessage": "Saldo ou limite insuficiente para realizar esta compra. Verifique o limite disponível ou use outro cartão.",
      "reversible": false
    }
  }
}

Os textos são sempre da Selectwin. A resposta bruta da adquirente ou do processador nunca é exposta — nem na API, nem no webhook, nem no painel.

#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": "payments"
  }
}

#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

• Forma de pagamento indisponível para a conta: a transação termina failed, com payment.refused.code: "paymentMethodUnavailable" (no objeto da transação e no webhook transaction.failed).
• O catálogo de error.code por recurso (com o status HTTP de cada um) está em Catálogo de Códigos de Erro.