Cartões

Emitir cartão

A Verdin emite cartões virtuais para a sua conta no estilo Stripe Issuing: cada compra autorizada debita o seu saldo Verdin. Emita, gerencie o status e defina limite mensal — tudo por API.

Como o saldo é debitado

Toda compra aprovada no cartão sai do seu saldo Verdin (o mesmo que você recebe das vendas por PIX) e gera um lançamento no extrato. Não há fatura: é débito imediato, como uma conta de pagamentos.

Emitir um cartão

POST/api/v1/cards

Campo	Tipo	Descrição
`holder_name`	stringobrigatório	Nome do portador impresso no cartão.
`monthly_limit`	integeropcional	Limite de gastos por mês em centavos. Padrão `500000` (R$ 5.000,00). Faixa: `10000` a `100000000`.

cURL

curl https://api.verdin.com.br/api/v1/cards \
  -H "Authorization: Bearer vrd_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "holder_name": "Ana Souza",
    "monthly_limit": 300000
  }'

Node.js

const res = await fetch("https://api.verdin.com.br/api/v1/cards", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VERDIN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    holder_name: "Ana Souza",
    monthly_limit: 300000, // R$ 3.000,00 por mês, em centavos
  }),
});

const card = await res.json();

Resposta

Sucesso retorna 201 com o objeto card. Por segurança (PCI), a API nunca retorna o número completo (PAN) nem o CVV — apenas last4. Os dados sensíveis só são revelados no painel, sob demanda.

201 Created

{
  "id": "clxcard1a2b3c4d5e6f7g8h9",
  "object": "card",
  "type": "virtual",
  "status": "active",
  "holder_name": "Ana Souza",
  "brand": "verdin",
  "last4": "4242",
  "exp_month": 7,
  "exp_year": 2030,
  "monthly_limit": 300000,
  "spent_this_month": 0,
  "currency": "BRL",
  "created_at": "2026-07-04T12:00:00.000Z",
  "canceled_at": null
}

Campo	Tipo	Descrição
`type`	stringopcional	virtual (físico é roadmap).
`status`	stringopcional	`active`, `frozen` ou `canceled`.
`brand / last4`	stringopcional	Bandeira (verdin) e os 4 últimos dígitos.
`monthly_limit / spent_this_month`	integeropcional	Limite e quanto já foi gasto no mês — em centavos.
`canceled_at`	stringopcional	Data ISO do cancelamento, ou null se o cartão estiver ativo/congelado.

Listar e recuperar

GET/api/v1/cards

Retorna todos os seus cartões ({ object: "list", data }, até 100, sem cursor). Para um cartão específico, use GET /api/v1/cards/:id — 404 not_found se não existir ou não for seu.

cURL

curl https://api.verdin.com.br/api/v1/cards \
  -H "Authorization: Bearer vrd_live_..."

Congelar, descongelar e cancelar

Controle o estado do cartão com três ações. Todas retornam o objeto card atualizado:

POST/api/v1/cards/:id/freeze

POST/api/v1/cards/:id/unfreeze

POST/api/v1/cards/:id/cancel

Um cartão frozen recusa toda compra com card_frozen até ser descongelado. O cancel é definitivo: compras passam a ser recusadas com card_canceled e o cartão não volta a ativar.

Congelar

curl -X POST https://api.verdin.com.br/api/v1/cards/clxcard.../freeze \
  -H "Authorization: Bearer vrd_live_..."

Cartão físico — em breve

Hoje a emissão é 100% virtual. O cartão físico está no roadmap: quando disponível, o campo type poderá ser physical e o painel mostrará a opção de solicitar a via física.

Autorização e transaçõesEntenda aprovações e recusas.Referência da APITodos os endpoints resumidos.