PURCHASE_PAYMENT_DECLINED

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.

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.

Payload

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

{
  "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)

Combine reason com retry_url: uma mensagem “seu cartão foi recusado por saldo insuficiente, quer pagar com PIX? ” enviada por WhatsApp em minutos recupera boa parte dessas vendas. O buyer.checkout_phone já vem em E.164.

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.

Integrações

Área de membros

PURCHASE_PAYMENT_DECLINED

Quando é disparado

Payload

O bloco `payment_failure`

Valores de `reason`

Campos-chave

​Quando é disparado

​Payload

​O bloco payment_failure

​Valores de reason

​Campos-chave

Quando é disparado

Payload

O bloco `payment_failure`

Valores de `reason`

Campos-chave