API pública

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

Convenções

Regras que valem para todos os endpoints da API.

Valores monetários

Todo valor é um inteiro em centavos. R$ 149,90 é 14990. Nunca enviamos nem aceitamos decimais, porque ponto flutuante não representa dinheiro de forma exata.

Percentuais seguem a mesma lógica e são expressos em basis points, onde 1 bps equivale a 0,01%. Uma taxa de 2,49% aparece como 249.

Datas

Todas as datas são strings ISO 8601 em UTC, como 2026-07-25T14:30:00Z. Converta para o fuso do usuário apenas na apresentação.

Idempotência

Requisições POST exigem o cabeçalho Idempotency-Key. Se a mesma chave chegar novamente, devolvemos a resposta original em vez de criar um segundo recurso — é o que impede uma cobrança duplicada quando a rede falha no meio da chamada.

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",
    "customer": { "name": "Maria Silva", "tax_id": "12345678909" }
  }'

Use um identificador do seu domínio, como o número do pedido. As chaves são guardadas por 24 horas. Reenviar a mesma chave com um corpo diferente retorna 409.

Paginação

As listagens usam cursor, não número de página: o resultado permanece estável mesmo com novos registros entrando durante a leitura.

Campo	Tipo	Descrição
`limit`	integer	Quantidade de itens por página. Entre 1 e 100, padrão 25.
`cursor`	string	Id do último item da página anterior. Use o valor de next_cursor.
`created_after`	string	Filtra por data de criação, em ISO 8601 (UTC).
`created_before`	string	Filtra por data de criação, em ISO 8601 (UTC).

200 OK

{
  "data": [ /* ... */ ],
  "has_more": true,
  "next_cursor": "chg_01j9x2m4k8p3q7r5t1v6w8y0"
}

Erros

Todo erro traz o mesmo formato. Trate pelo campo code, que é estável, e não pela message, que pode mudar.

400 Bad Request

{
  "error": {
    "type": "validation_error",
    "code": "amount_below_minimum",
    "message": "O valor mínimo de uma cobrança é R$ 1,00.",
    "param": "amount",
    "request_id": "req_01j9x2m4k8p3q7r5t1v6w8y0"
  }
}

Guarde o request_id: é a referência que o suporte usa para localizar a chamada.

Status	Tipo	Significado
400	validation_error	Corpo inválido ou campo fora do domínio aceito.
401	unauthorized	Chave ausente, malformada ou revogada.
403	forbidden	Chave sem o escopo necessário, ou conta não aprovada.
404	not_found	Recurso inexistente ou pertencente a outra conta.
409	conflict	Operação incompatível com o estado atual do recurso.
422	insufficient_funds	Saldo disponível menor que o valor solicitado.
429	rate_limited	Limite de requisições excedido.
5xx	internal_error	Falha nossa. Pode ser repetida com a mesma chave de idempotência.

Retentativas

Repita apenas erros 429 e 5xx, sempre com a mesma Idempotency-Key e com espera exponencial. Erros 4xx não se resolvem sozinhos: corrija a requisição.

Em 429, respeite o Retry-After. Nos demais, use algo como 1s, 2s, 4s, 8s com jitter aleatório para evitar que todos os seus servidores voltem no mesmo instante.