API de a plataforma

Como começar

1. 1

   Gere sua chave

   No app, em Mais → Credenciais de API. A chave aparece uma única vez: guarde na hora.

2. 2

   Teste com valores pequenos

   Não há sandbox: sk_test_ e sk_live_ movem dinheiro real na sua conta. O prefixo é só um rótulo para organizar as chaves. Para experimentar, use valores baixos.

3. 3

   Confira com GET /v1/me

   Antes de qualquer integração, veja se a chave responde e quais escopos ela carrega.

Autenticação

Envie a chave no header Authorization. Ela identifica a conta: não há parâmetro de conta em nenhuma rota, e uma chave nunca alcança dados de outra.

curl /v1/me \
  -H "Authorization: Bearer sk_test_sua_chave_aqui"

Tentativas de autenticação com chave inválida são limitadas por IP de origem. A resposta não muda por causa disso: sempre 401, nunca um código diferente.

Toda chave pode restringir por IP, em Credenciais. Sem lista configurada (o padrão), não há restrição nenhuma.

Endpoints

{
  "environment": "test",
  "scopes": ["balance:read", "transactions:read"],
  "account": { "id": "8d1e6211-..." },
  "tenant": { "slug": "sua-marca" },
  "permissions": {
    "balance": true,
    "transactions": true,
    "transfers": false
  }
}

{
  "available": "8589.10",
  "held": "0.00",
  "spendable": "8589.10"
}

{
  "items": [
    {
      "id": "6b346bc2-...",
      "type": "INTERNAL_TRANSFER",
      "direction": "OUT",
      "amount": "150.00",
      "description": "Pagamento de fornecedor",
      "createdAt": "2026-09-06T04:12:00.000Z"
    }
  ],
  "total": 42
}

{
  "id": "6b346bc2-...",
  "status": "SETTLED",
  "amount": "150.00",
  "fee": "0.50",
  "counterparty": { "name": "Padaria Central" },
  "settledAt": "2026-09-06T04:12:00.000Z"
}

{
  "description": "Mensalidade de setembro",
  "amount": "99.90",
  "singleUse": false,
  "expiresInHours": 720,
  "requirePayerName": true
}

{
  "id": "4f21c8de-...",
  "slug": "k3n8vq2p",
  "url": "https://seu-banco.com/pagar/k3n8vq2p",
  "description": "Mensalidade de setembro",
  "amount": "99.90",
  "amountOpen": false,
  "singleUse": false,
  "status": "open"
}

{
  "items": [
    {
      "id": "4f21c8de-...",
      "slug": "k3n8vq2p",
      "url": "https://seu-banco.com/pagar/k3n8vq2p",
      "description": "Mensalidade de setembro",
      "amount": "99.90",
      "singleUse": false,
      "uses": 12,
      "status": "open",
      "received": "1198.80",
      "payments": 12
    }
  ]
}

{
  "id": "4f21c8de-...",
  "status": "cancelled"
}

{
  "to": "padaria",
  "amount": "150.00",
  "description": "Pagamento do pedido 8842"
}

{
  "id": "6b346bc2-...",
  "status": "SETTLED",
  "amount": "150.00",
  "fee": "0.50",
  "to": { "id": "c24b7e31-...", "name": "Padaria Central" },
  "replayed": false
}

{
  "amount": "49.90",
  "description": "Pedido #1234",
  "expiresIn": 3600,
  "payer": {
    "name": "Maria Silva",
    "email": "maria@exemplo.com",
    "document": "12345678901"
  },
  "externalReference": "pedido-1234",
  "split": [
    { "destination": "anunciante@exemplo.com", "percentage": "10" }
  ]
}

{
  "id": "e636775c-...",
  "status": "open",
  "amount": "49.90",
  "description": "Pedido #1234",
  "qrCode": "00020101021226830014br.gov.bcb.pix...",
  "copyPaste": "00020101021226830014br.gov.bcb.pix...",
  "expiresAt": "2026-09-10T00:35:19.836Z",
  "externalReference": "pedido-1234",
  "split": [
    { "destinationSellerId": "7ec3...", "percentage": "10" }
  ]
}

{
  "id": "e636775c-...",
  "status": "paid",
  "amount": "49.90",
  "description": "Pedido #1234",
  "paidAt": "2026-09-09T21:14:02.000Z",
  "expiresAt": "2026-09-10T00:35:19.836Z"
}

{
  "amount": "150.00",
  "pixKey": "maria@exemplo.com",
  "pixKeyType": "EMAIL",
  "description": "Pagamento fornecedor"
}

{
  "id": "8f1a...",
  "status": "processing",
  "amount": "150.00",
  "fee": "1.20",
  "total": "151.20",
  "pixKey": "ma****@exemplo.com",
  "providerReference": "E1890...",
  "endToEndId": "E1890..."
}

{
  "adminConfigured": false,
  "adminPercentage": "0.000000",
  "availablePercentage": "90.000000",
  "rules": [
    { "id": "1e04...", "destination": "Maria Fornecedora", "percentage": "10.000000" }
  ]
}

{
  "lines": [
    { "destination": "maria@exemplo.com", "percentage": "10" }
  ]
}

{
  "rules": [
    { "id": "1e04...", "destination": "Maria Fornecedora", "percentage": "10.000000" }
  ]
}

{
  "sellerId": "8d6d608e-...",
  "name": "Maria Fornecedora"
}

Idempotência

Toda transferência exige o header Idempotency-Key. Reenviar a mesma requisição com a mesma chave devolve a operação original com replayed: true, em vez de transferir de novo.

Isso existe porque um timeout de rede não diz se a operação aconteceu. Gere um identificador por intenção de pagamento — não por tentativa — e reenvie o mesmo em cada retry.

curl -X POST /v1/transfers \
  -H "Authorization: Bearer sk_test_sua_chave" \
  -H "Idempotency-Key: pedido-8842" \
  -H "Content-Type: application/json" \
  -d '{"to":"padaria","amount":"150.00"}'

Erros

Todo erro traz error (código estável) e message (texto para humano). Trate pelo código, não pelo texto.

Estados de uma cobrança Pix

Só paid significa dinheiro na conta. Libere o pedido nesse estado, nunca antes.

Webhooks

Em vez de perguntar de tempos em tempos se a cobrança foi paga, cadastre uma URL no painel e receba o aviso no momento em que acontece. Cada envio é assinado — confira a assinatura antes de confiar no conteúdo.

Eventos

O que chega

POST https://seu-sistema.com/webhooks
content-type: application/json
x-webhook-id: 9f2c1a44-...
x-webhook-event: charge.paid
x-webhook-timestamp: 1789002842
x-webhook-signature: 7b52009b64fd0a2a49e6d8a939753077792b0554...

{
  "id": "9f2c1a44-...",
  "type": "charge.paid",
  "createdAt": "2026-09-09T21:14:02.000Z",
  "data": {
    "chargeId": "e636775c-...",
    "sellerId": "c34b87db-...",
    "amount": "4990"
  }
}

O valor em data.amount vem em centavos. O identificador da cobrança é data.chargeId — o mesmo id devolvido ao criar.

Conferindo a assinatura

A assinatura é o HMAC-SHA256 de {timestamp}.{corpo}, em hexadecimal, com o segredo do destino, mostrado ao cadastrar a URL e recuperável depois em Credenciais, no botão Ver segredo ao lado do destino. O timestamp entra no cálculo para que uma entrega capturada não possa ser reenviada depois — recuse o que chegar com mais de 5 minutos.

import { createHmac, timingSafeEqual } from "node:crypto";

// corpo CRU, exatamente como chegou — reserializar muda os bytes
// e a assinatura deixa de bater.
function confere(corpoBruto, headers, segredo) {
  const assinatura = headers["x-webhook-signature"];
  const timestamp = Number(headers["x-webhook-timestamp"]);

  // Entrega velha é entrega repetida: recuse.
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;

  const esperado = createHmac("sha256", segredo)
    .update(`${timestamp}.${corpoBruto}`)
    .digest("hex");

  const a = Buffer.from(assinatura);
  const b = Buffer.from(esperado);
  // Comparação em tempo constante: "===" vaza, pelo tempo, quantos
  // caracteres iniciais estavam certos.
  return a.length === b.length && timingSafeEqual(a, b);
}

Boas práticas

• Responda 200 rápido. Processe depois, em fila. Demorar faz o envio ser considerado falho e reenviado.
• Espere repetição. O mesmo evento pode chegar duas vezes — uma reentrega após falha de rede, por exemplo. Guarde o x-webhook-id já processado e ignore repetidos, ou o pedido é liberado duas vezes.
• Não confie no valor recebido para creditar. Antes de liberar o pedido, confirme com GET /v1/pix/charges/{id}. O webhook diz o que olhar; a consulta diz o que é verdade.
• Use HTTPS. URLs em HTTP não são aceitas.

Valores e datas

• Dinheiro vai e volta como string decimal com duas casas: "150.00". Nunca como número — ponto flutuante perde centavo, e centavo perdido em dinheiro é erro contábil.
• Datas em ISO 8601, UTC: 2026-09-06T04:12:00.000Z.
• Identificadores são UUID. Não presuma ordem nem sequência entre eles.