API pública

Base URL: https://app.slimpay.com.br/api/v1. Cobranças, saldo, saques e webhooks.

Cobranças PIX

A cobrança é o recurso central da API: representa um valor que você espera receber.

Criar uma cobrança

POST/v1/charges

Requer o escopo charges:write. Responde 201 Created com o objeto da cobrança.

Campo	Tipo	Descrição
`amount`obrigatório	integer	Valor em centavos. Mínimo de 100 (R$ 1,00). O limite máximo é definido pelo seu perfil de risco.
`description`obrigatório	string	Texto exibido no aplicativo do banco do pagador. Até 140 caracteres.
`expires_in`	integer	Validade em segundos, de 60 a 2592000 (30 dias). Padrão de 1800 (30 minutos).
`reference_id`	string	Seu identificador do pedido. Aparece nas listagens e no extrato.
`customer.name`obrigatório	string	Nome do pagador (obrigatório para gerar o PIX).
`customer.tax_id`obrigatório	string	CPF (11) ou CNPJ (14), apenas dígitos.
`customer.email`	string	E-mail do pagador (opcional).
`metadata`	object	Até 20 pares chave-valor de texto que devolvemos intactos. Não use para dados sensíveis.

cURL

curl https://app.slimpay.com.br/api/v1/charges \
  -H "Authorization: Bearer ax_sua_chave" \
  -H "Idempotency-Key: pedido-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 14990,
    "description": "Pedido #1042",
    "expires_in": 1800,
    "reference_id": "1042",
    "customer": {
      "name": "Maria Silva",
      "tax_id": "12345678909",
      "email": "maria@exemplo.com"
    },
    "metadata": { "cart_id": "cart_88213" }
  }'

O objeto cobrança

201 Created

{
  "id": "chg_01j9x2m4k8p3q7r5t1v6w8y0",
  "status": "awaiting_payment",
  "amount": 14990,
  "fee_amount": 373,
  "net_amount": 14617,
  "description": "Pedido #1042",
  "reference_id": "1042",
  "brcode": "00020126580014br.gov.bcb.pix...",
  "qrcode_url": "https://app.slimpay.com.br/api/v1/charges/chg_.../qrcode.png",
  "customer": {
    "name": "Maria Silva",
    "tax_id": "***.***.789-09",
    "email": "maria@exemplo.com"
  },
  "metadata": { "cart_id": "cart_88213" },
  "paid_at": null,
  "expires_at": "2026-07-25T15:30:00Z",
  "created_at": "2026-07-25T14:30:00Z"
}

fee_amount é a taxa aplicada e net_amount é o que efetivamente entra no seu saldo. Ambos são calculados no momento da criação e não mudam depois — veja Taxas e liquidação.

O CPF do pagador volta mascarado. O valor completo fica cifrado em repouso e não é exposto pela API.

Ciclo de vida

status	Significado
awaiting_payment	Cobrança criada e válida. Aguardando o PIX do pagador.
paid	Pagamento confirmado. O valor líquido entrou no saldo a liberar.
expired	Passou de expires_at sem pagamento. Não pode mais ser paga.
canceled	Cancelada por você antes do pagamento.
failed	O provedor não conseguiu gerar ou liquidar a cobrança.

Os estados paid, expired, canceled e failed são finais.

Consultar uma cobrança

GET/v1/charges/:id

Aceita também o seu reference_id, no formato /v1/charges/ref_1042. Útil quando você não guardou o id da SlimPay.

Listar cobranças

GET/v1/charges

Aceita os filtros de paginação mais status e reference_id. A ordenação é da mais recente para a mais antiga.

cURL

curl "https://app.slimpay.com.br/api/v1/charges?status=paid&limit=25" \
  -H "Authorization: Bearer ax_sua_chave"

Cancelar uma cobrança

DELETE/v1/charges/:id

Só funciona enquanto o status é awaiting_payment. Cancelar invalida o código PIX imediatamente. Cobranças já pagas não podem ser canceladas.

Renderizar o QR Code

Você tem duas opções. Use brcode para gerar a imagem no seu front-end e oferecer o copia e cola, ou aponte uma tag img direto para qrcode_url, que é público e não exige autenticação.

Sempre ofereça o copia e cola junto do QR: em compras pelo celular, o cliente não tem uma segunda tela para escanear.