API pública

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

Estornos

Como devolver dinheiro ao pagador e o que isso faz com o seu saldo.

Como funciona

Um estorno devolve ao pagador, na mesma chave PIX que pagou, parte ou todo o valor de uma cobrança. Você pode estornar quantas vezes quiser até somar o valor total da cobrança.

O débito acontece no instante em que o provedor aceita o pedido — não quando o dinheiro cai na conta do pagador. Isso evita que um saldo já comprometido seja sacado enquanto a devolução está a caminho.

Estorno parcial depende da sua conta

Algumas contas operam por um provedor que devolve apenas o valor integral da cobrança. Nessas contas, um pedido com amount menor que o bruto é recusado com 403 e a mensagem diz qual é o valor aceito — nada é debitado. Se o seu integrador precisa saber disso de antemão, fale com o suporte.

O que sai do seu saldo

Duas parcelas, sempre explícitas na resposta:

amount — o valor devolvido ao pagador.
fee_amount — a taxa de estorno do seu plano.

A soma é total_debited. Ela sai primeiro do saldo disponível e, se não bastar, do saldo a liberar. A reserva não é usada.

A taxa do recebimento não volta

A taxa cobrada quando a cobrança foi paga remunerou um pagamento que de fato aconteceu e não é restituída no estorno. Consulte as suas taxas em Taxas e liquidação.

Criar um estorno

POST/v1/refunds

201Created

Requer o escopo refunds:write e o cabeçalho Idempotency-Key. Base URL: https://app.slimpay.com.br/api/v1.

Campo	Tipo	Descrição
`charge_id`obrigatório	string	Cobrança a estornar. Precisa estar paga e ter sido processada pelo provedor ativo.
`amount`	integer	Valor em centavos. Omitido, devolve tudo o que ainda resta da cobrança. Em algumas contas só o valor integral é aceito — veja abaixo.
`reason`	string	Anotação interna de até 140 caracteres, exibida no painel.

cURL

curl https://app.slimpay.com.br/api/v1/refunds \
  -H "Authorization: Bearer sp_sua_chave" \
  -H "Idempotency-Key: estorno-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "charge_id": "chg_01j9x2m4k8p3q7r5t1v6w8y0",
    "amount": 5000,
    "reason": "Pedido cancelado pelo cliente"
  }'

201 Created

{
  "id": "ref_01j9xb3n7k2p5q8r1t4v6x9z",
  "status": "processing",
  "amount": 5000,
  "fee_amount": 100,
  "total_debited": 5100,
  "charge_id": "chg_01j9x2m4k8p3q7r5t1v6w8y0",
  "reference_id": "1042",
  "reason": "Pedido cancelado pelo cliente",
  "failure_reason": null,
  "completed_at": null,
  "created_at": "2026-07-25T15:02:44Z"
}

Status

processing — aceito pelo provedor, a caminho do pagador. O saldo já foi debitado.
completed — o pagador recebeu o dinheiro de volta.
failed — recusado antes de qualquer débito. Nada saiu do seu saldo; o motivo vem em failure_reason.

Acompanhe pelos eventos refund.created, refund.completed, refund.failed e charge.refunded. Veja Webhooks.

Consultar e listar

GET/v1/refunds/:id

200OK

200 OK

{
  "id": "ref_01j9xb3n7k2p5q8r1t4v6x9z",
  "status": "processing",
  "amount": 5000,
  "fee_amount": 100,
  "total_debited": 5100,
  "charge_id": "chg_01j9x2m4k8p3q7r5t1v6w8y0",
  "reference_id": "1042",
  "reason": "Pedido cancelado pelo cliente",
  "failure_reason": null,
  "completed_at": null,
  "created_at": "2026-07-25T15:02:44Z"
}

GET/v1/refunds

200OK

Requer o escopo refunds:read. A listagem aceita status, charge_id, created_after, created_before, limit e cursor.

200 OK

{
  "data": [
    {
      "id": "ref_01j9xb3n7k2p5q8r1t4v6x9z",
      "status": "completed",
      "amount": 5000,
      "fee_amount": 100,
      "total_debited": 5100,
      "charge_id": "chg_01j9x2m4k8p3q7r5t1v6w8y0",
      "completed_at": "2026-07-25T15:03:12Z",
      "created_at": "2026-07-25T15:02:44Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Estornos feitos fora da API

Devoluções abertas no painel do provedor, ou impostas por um MED, também aparecem aqui: reconciliamos pelo postback e lançamos o débito equivalente, para que o seu saldo acompanhe o dinheiro que realmente saiu.