Cartões

Autorização e transações

Cada compra passa pelo motor de autorização da Verdin, que aprova ou recusa em tempo real. Toda tentativa — aprovada ou não — vira uma transação que você pode consultar.

Listar transações

GET/api/v1/cards/:id/transactions

Retorna as transações do cartão em ordem decrescente de data, no formato de lista paginado.

Campo	Tipo	Descrição
`limit`	integeropcional	Quantidade de transações por página (padrão 20, máximo 100).

cURL

curl "https://api.verdin.com.br/api/v1/cards/clxcard.../transactions?limit=10" \
  -H "Authorization: Bearer vrd_live_..."

200 OK

{
  "object": "list",
  "data": [
    {
      "id": "clxtxn1a2b3c4d5e6f7g8h9i",
      "object": "card_transaction",
      "card_id": "clxcard1a2b3c4d5e6f7g8h9",
      "merchant_name": "Padaria do Zé",
      "category": "food",
      "amount": 1290,
      "currency": "BRL",
      "status": "approved",
      "decline_reason": null,
      "created_at": "2026-07-04T12:10:00.000Z"
    },
    {
      "id": "clxtxn0z9y8x7w6v5u4t3s2r",
      "object": "card_transaction",
      "card_id": "clxcard1a2b3c4d5e6f7g8h9",
      "merchant_name": "Loja XPTO",
      "category": null,
      "amount": 990000,
      "currency": "BRL",
      "status": "declined",
      "decline_reason": "limit_exceeded",
      "created_at": "2026-07-04T12:05:00.000Z"
    }
  ],
  "has_more": false
}

Campos da transação

Campo	Tipo	Descrição
`merchant_name`	stringopcional	Nome do estabelecimento.
`category`	stringopcional	Categoria informada na compra, ou null.
`amount`	integeropcional	Valor em centavos (sempre positivo).
`status`	stringopcional	`approved`, `declined` ou `refunded`.
`decline_reason`	stringopcional	Motivo da recusa quando declined; null quando aprovada.

O motor de autorização

Ao receber uma compra, a Verdin decide na hora aplicando, em ordem, estas regras. A primeira que falhar recusa a transação e vira o decline_reason:

decline_reason	Rótulo	Quando
`card_frozen`	Cartão congelado	O cartão está com status frozen.
`card_canceled`	Cartão cancelado	O cartão foi cancelado (definitivo).
`limit_exceeded`	Limite mensal excedido	A compra ultrapassaria o monthly_limit no mês corrente.
`insufficient_balance`	Saldo insuficiente	O seu saldo Verdin é menor que o valor da compra.

Se todas passarem, a compra é approved, o valor é debitado do seu saldo com lançamento no extrato (tipo CARD_PURCHASE) e você recebe uma notificação. Recusas também notificam, com o motivo.

Simular uma compra (sandbox)

POST/api/mock/card-purchase

Em ambiente de testes (provider mock), dispare o motor de autorização diretamente:

cURL

curl http://localhost:3900/api/mock/card-purchase \
  -H "Content-Type: application/json" \
  -d '{
    "card_id": "clxcard1a2b3c4d5e6f7g8h9",
    "merchant_name": "Padaria do Zé",
    "amount": 1290,
    "category": "food"
  }'

Aprovada

{
  "ok": true,
  "approved": true,
  "transaction": {
    "id": "clxtxn1a2b3c4d5e6f7g8h9i",
    "object": "card_transaction",
    "card_id": "clxcard1a2b3c4d5e6f7g8h9",
    "merchant_name": "Padaria do Zé",
    "category": "food",
    "amount": 1290,
    "currency": "BRL",
    "status": "approved",
    "decline_reason": null,
    "created_at": "2026-07-04T12:10:00.000Z"
  }
}

/api/mock/card-purchase só responde quando PAYMENT_PROVIDER === "mock". Em produção, as compras chegam pela rede de cartões — não por esse endpoint.

Emitir cartãoVolte para a emissão e o gerenciamento.Sandbox e testesRode tudo localmente sem risco.