Referência

Referência da API

Todos os endpoints da API pública v1 num só lugar. Base URL de produção: https://api.verdin.com.br — em desenvolvimento, http://localhost:3900. Autentique com Authorization: Bearer vrd_live_...

Respostas em snake_case, valores monetários sempre em centavos e datas em ISO 8601 (UTC). Listas seguem o formato { object: "list", data, has_more }. Erros seguem este formato.

Cobranças

Criar cobrança

POST/api/v1/charges

Corpo: amount (centavos, obrigatório), description (obrigatório), customer, metadata, expires_in_minutes. Retorna 201 com o objeto charge. Detalhes.

Recuperar cobrança

GET/api/v1/charges/:id

Retorna o objeto charge ou 404 not_found.

Listar cobranças

GET/api/v1/charges

Query: status, limit (máx 100), starting_after. Retorna { object: "list", data, has_more }.

QR Code da cobrança

GET/api/v1/charges/:id/qrcode

Retorna a imagem PNG do BR Code. Detalhes.

Objeto charge

charge

{
  "id": "clx...",
  "object": "charge",
  "status": "pending",
  "amount": 4990,
  "fee": 74,
  "net": 4916,
  "currency": "BRL",
  "description": "Plano Pro — mensal",
  "payment_method": "pix",
  "customer": { "name": "...", "email": "...", "document": null },
  "pix": { "txid": "...", "brcode": "...", "qrcode_url": "..." },
  "payment_url": "https://api.verdin.com.br/pay/clx...",
  "metadata": null,
  "paid_at": null,
  "expires_at": "2026-07-04T13:00:00.000Z",
  "created_at": "2026-07-04T12:00:00.000Z"
}

Cartões

Emitir cartão

POST/api/v1/cards

Corpo: holder_name (obrigatório), monthly_limit (centavos). Retorna 201 com o objeto card. Detalhes.

Listar cartões

GET/api/v1/cards

Retorna { object: "list", data } (sem cursor, até 100).

Recuperar cartão

GET/api/v1/cards/:id

Retorna o objeto card ou 404.

Congelar / descongelar / cancelar

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

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

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

Todas retornam o objeto card atualizado.

Transações do cartão

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

Query: limit (máx 100). Retorna { object: "list", data, has_more }. Detalhes.

Objeto card

card

{
  "id": "clxcard...",
  "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
}

Objeto card_transaction

card_transaction

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

Saldo

Consultar saldo

GET/api/v1/balance

Retorna o saldo disponível da conta (em centavos) e a moeda:

200 OK

{
  "available": 12990,
  "currency": "BRL"
}

Webhooks

Eventos charge.paid e charge.expired, entregues via POST no seu endpoint com o cabeçalho verdin-signature (HMAC-SHA256). 3 tentativas (0s/5s/25s), timeout de 8s. Visão geral · Verificação da assinatura.