> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velan.app/llms.txt
> Use this file to discover all available pages before exploring further.

# PURCHASE_PAYMENT_DECLINED

> Disparado quando o cartão do comprador foi recusado e ele não tentou de novo em 5 minutos. Traz o motivo da recusa para você agir.

Corresponde ao evento interno `order.payment_declined`. O comprador preencheu tudo, tentou pagar com cartão e a operadora ou o banco recusou. É o lead mais quente do funil: está a uma ação de converter (outro cartão, PIX, ligar para o banco).

## Quando é disparado

* O pedido está com status `failed` (cartão recusado) há **5 minutos sem nova tentativa**. Se o comprador tentar de novo nesse intervalo, o relógio recomeça; se pagar, você recebe `PURCHASE_APPROVED` e este evento não sai.
* **Uma vez por pedido.** Recusas seguintes no mesmo pedido não geram novo evento; o motivo mais recente fica no painel.
* O envio acontece em lote, a cada 2 minutos, então chega entre 5 e 7 minutos após a última recusa.
* Cartão de crédito, débito, dois cartões e cartão + PIX. PIX e boleto não falham, expiram (`PURCHASE_EXPIRED`).
* Se o pedido continuar parado, aos 15 minutos sai também `PURCHASE_CART_ABANDONED` para o mesmo pedido. Os dois eventos são intencionais: este traz o motivo da recusa, o outro é a régua padrão de abandono. Deduplique por `purchase.transaction` se a sua automação já age aqui.

<Note>
  O status `failed` é **reversível**. O comprador pode voltar ao mesmo link e pagar; quando isso acontece o pedido passa a `paid` e você recebe `PURCHASE_APPROVED` com a mesma `purchase.transaction`. Use-a como chave para casar os dois eventos.
</Note>

## Payload

Mesmo envelope dos demais eventos de pedido, com o bloco extra `data.payment_failure`:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "order_id": 123,
  "creation_date": 1736524800000,
  "event": "PURCHASE_PAYMENT_DECLINED",
  "version": "2.0.0",
  "source": "velan",
  "data": {
    "purchase": {
      "transaction": "abc123-uuid-do-pedido",
      "status": "CANCELLED",
      "order_date": 1736524700000,
      "approved_date": null,
      "refund_date": null,
      "full_price": { "value": 297.00, "currency_value": "BRL" },
      "price": { "value": 297.00, "currency_value": "BRL" },
      "payment": { "type": "CREDIT_CARD", "installments_number": 3 },
      "fees": { "value": 0.0, "currency_value": "BRL" },
      "net_amount": { "value": null, "currency_value": "BRL" },
      "gateway_transaction_id": null,
      "offer": { "code": "abc12345", "name": "Oferta Principal" },
      "order_bump": { "is_order_bump": false, "parent_purchase_transaction": null },
      "tracking": {
        "source": "google",
        "utm_source": "google",
        "utm_medium": "cpc",
        "utm_campaign": "black-friday",
        "utm_content": null,
        "utm_term": null,
        "src": null,
        "sck": null
      }
    },
    "product": {
      "id": 1,
      "name": "Curso de Marketing Digital",
      "external_id": "CRM-1234"
    },
    "buyer": {
      "name": "João Silva",
      "first_name": "João",
      "last_name": "Silva",
      "email": "joao@exemplo.com",
      "checkout_phone": "+5511999990000",
      "document": "123.456.789-00",
      "document_type": "CPF"
    },
    "order_bumps": [],
    "payment_failure": {
      "reason": "insufficient_funds",
      "reason_label": "Saldo ou limite insuficiente",
      "gateway": "mercadopago",
      "gateway_code": "cc_rejected_insufficient_amount",
      "gateway_message": "Saldo insuficiente no cartão.",
      "payment_method": "credit_card",
      "installments": 3,
      "amount": "297.00",
      "attempts": 2,
      "failed_at": "2026-09-24T18:41:07+00:00",
      "card": { "brand": "visa", "last_four_digits": "4242" },
      "retry_url": "https://pay.velan.app/abc12345/abc123-uuid-do-pedido"
    }
  }
}
```

## O bloco `payment_failure`

| Campo | Tipo | Descrição |
| - | - | - |
| `reason` | string | Motivo **normalizado** pela Velan, igual em todos os gateways. Use este campo para automações. Valores abaixo. |
| `reason_label` | string | Texto curto do motivo, em português, pronto para exibir ou enviar ao comprador. |
| `gateway` | string | Gateway que recusou: `mercadopago`, `asaas`, `pagarme`, `stripe`. |
| `gateway_code` | string \| null | Código cru devolvido pelo gateway (ex.: `cc_rejected_insufficient_amount`). Pode ser `null`. |
| `gateway_message` | string | Mensagem da recusa como o comprador viu no checkout. |
| `payment_method` | string | `credit_card`, `debit_card`, `two_cards` ou `card_pix`. |
| `installments` | number | Parcelas escolhidas na tentativa recusada. |
| `amount` | string | Valor tentado, com duas casas decimais. |
| `attempts` | number | Quantas tentativas o pedido já teve. |
| `failed_at` | string | Data e hora da última recusa (ISO 8601, UTC). |
| `card` | object \| null | `brand` e `last_four_digits` quando o gateway informa; `null` caso contrário. |
| `retry_url` | string | Link do checkout já apontando para este pedido: o comprador retoma de onde parou. |

### Valores de `reason`

| `reason` | Significado | O que costuma resolver |
| - | - | - |
| `insufficient_funds` | Saldo ou limite insuficiente | Outro cartão, PIX ou mais parcelas |
| `risk_blocked` | Bloqueado por análise de risco ou segurança | Outro meio de pagamento; confirmar identidade |
| `call_bank` | Banco exige autorização do titular | Pedir para ligar no banco e tentar de novo |
| `bad_security_code` | Código de segurança incorreto | Conferir o CVV |
| `bad_card_number` | Número do cartão inválido ou bandeira não reconhecida | Redigitar o número |
| `bad_card_data` | Validade ou outros dados incorretos | Conferir validade e parcelas |
| `card_disabled` | Cartão desativado, bloqueado ou cancelado | Outro cartão |
| `card_not_allowed` | Tipo de cartão não aceito nesta cobrança (débito, pré-pago ou virtual usado como crédito) | Cartão de crédito |
| `installments_not_allowed` | Parcelamento não permitido para este cartão (internacional ou regra do emissor) | Pagar à vista ou em menos parcelas |
| `rate_limited` | Muitas tentativas no gateway | Aguardar alguns minutos |
| `other` | Recusa sem categoria conhecida | Ver `gateway_message` |

## Campos-chave

| Campo | Valor neste evento |
| - | - |
| `purchase.status` | `CANCELLED` |
| `purchase.approved_date` | `null` |
| `purchase.refund_date` | `null` |
| `data.payment_failure` | presente (só neste evento) |

<Tip>
  Combine `reason` com `retry_url`: uma mensagem "seu cartão foi recusado por saldo insuficiente, quer pagar com PIX? {retry_url}" enviada por WhatsApp em minutos recupera boa parte dessas vendas. O `buyer.checkout_phone` já vem em E.164.
</Tip>

<Warning>
  Não trate este evento como cancelamento definitivo. O comprador pode pagar depois: aguarde o `PURCHASE_APPROVED` antes de encerrar o pedido no seu sistema.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.