Pagamentos

Criar cobrança PIX

Uma cobrança representa um pedido de pagamento por PIX. Ao criá-la, a Verdin devolve o BR Code (copia-e-cola) e a URL do QR Code para você apresentar ao pagador.

POST/api/v1/charges

Corpo da requisição

Campo	Tipo	Descrição
`amount`	integerobrigatório	Valor da cobrança em centavos (ex.: `4990` = R$ 49,90). Inteiro entre `100` (R$ 1,00) e `5000000` (R$ 50.000,00).
`description`	stringobrigatório	Descrição do que está sendo cobrado. Aparece no checkout.
`customer`	objectopcional	Dados do pagador. Contém `name`, `email` e `document` (opcional). Se informado com nome e e-mail, o cliente é salvo/atualizado na sua base.
`metadata`	objectopcional	Objeto JSON livre com dados seus (ex.: id do pedido). Retorna intacto e vem nos webhooks.
`expires_in_minutes`	integeropcional	Tempo de validade da cobrança em minutos. Padrão: `60`. Após expirar, o status vira `expired`.

amount é sempre em centavos

Para cobrar R$ 49,90, envie 4990 — nunca 49.90. Valores não inteiros ou fora da faixa retornam invalid_amount (400).

Exemplo de requisição

cURL

curl https://api.verdin.com.br/api/v1/charges \
  -H "Authorization: Bearer vrd_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4990,
    "description": "Plano Pro — mensal",
    "customer": {
      "name": "Ana Souza",
      "email": "ana@exemplo.com",
      "document": "123.456.789-09"
    },
    "metadata": { "pedido_id": "A-1042" },
    "expires_in_minutes": 30
  }'

Node.js

const res = await fetch("https://api.verdin.com.br/api/v1/charges", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VERDIN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 4990, // R$ 49,90 em centavos
    description: "Plano Pro — mensal",
    customer: { name: "Ana Souza", email: "ana@exemplo.com" },
    metadata: { pedido_id: "A-1042" },
    expires_in_minutes: 30,
  }),
});

const charge = await res.json();
// mostre charge.pix.brcode ao pagador, ou redirecione para charge.payment_url

Resposta

Sucesso retorna 201 com o objeto charge. Os campos amount, fee e net estão todos em centavos.

201 Created

{
  "id": "clx7a1b2c3d4e5f6g7h8i9j0k",
  "object": "charge",
  "status": "pending",
  "amount": 4990,
  "fee": 74,
  "net": 4916,
  "currency": "BRL",
  "description": "Plano Pro — mensal",
  "payment_method": "pix",
  "customer": {
    "name": "Ana Souza",
    "email": "ana@exemplo.com",
    "document": "123.456.789-09"
  },
  "pix": {
    "txid": "VRD7A1B2C3D4E5F6G7H8I9J0",
    "brcode": "00020126360014BR.GOV.BCB.PIX...6304AB1F",
    "qrcode_url": "https://api.verdin.com.br/api/v1/charges/clx7a1b2c3d4e5f6g7h8i9j0k/qrcode"
  },
  "payment_url": "https://api.verdin.com.br/pay/clx7a1b2c3d4e5f6g7h8i9j0k",
  "metadata": { "pedido_id": "A-1042" },
  "paid_at": null,
  "expires_at": "2026-07-04T12:30:00.000Z",
  "created_at": "2026-07-04T12:00:00.000Z"
}

Campos da resposta

Campo	Tipo	Descrição
`id`	stringopcional	Identificador único da cobrança.
`status`	stringopcional	`pending`, `paid`, `expired` ou `canceled`.
`amount / fee / net`	integeropcional	Bruto, taxa Verdin e líquido — em centavos.
`pix.brcode`	stringopcional	Código PIX copia-e-cola (BR Code) para o pagador.
`pix.qrcode_url`	stringopcional	URL que retorna o QR Code em PNG. Veja QR Code.
`payment_url`	stringopcional	Página de pagamento hospedada pela Verdin — pode redirecionar o pagador para cá.
`paid_at / expires_at / created_at`	stringopcional	Datas em ISO 8601 (UTC). paid_at é null enquanto não paga.

Consultar e listarAcompanhe o status das cobranças.WebhooksReceba charge.paid em tempo real.