Skip to main content
Saques Pix permitem transferir saldo de uma carteira para uma chave Pix de destino. A API oferece cotacao previa, criacao com idempotencia e consulta sincronizada com a provedora, tudo sem necessidade de webhook.
Requer escopo payouts:create para criar e payouts:read para consultar e cotar.

Requisitos

Antes de solicitar um saque, confirme que:
  • A conta esta ativa, habilitada e com KYC aprovado.
  • O servidor esta com PAYOUTS_ENABLED=true.
  • A carteira possui saldo disponivel.
  • A provedora esta configurada.
  • Ao usar sessao, e necessaria confirmacao adicional recente.

Cotação

Antes de criar, use GET /v1/payouts/quote para conferir o valor debitado, a tarifa e o valor que o destinatario recebera.
integer
required
Valor em centavos de BRL. Minimo 1000 (R$ 10,00).
string
true para descontar a tarifa do valor informado; false para cobrar a tarifa a parte. Padrao: false.
curl

Exemplo: deductFee = false

Solicita-se amountCents=1000. A tarifa de 45 centavos e cobrada a parte.

Exemplo: deductFee = true

Solicita-se amountCents=1045. A tarifa de 45 centavos e descontada do valor.
Com deductFee=true, o destinatario deve receber pelo menos 1000 centavos. Por exemplo, amountCents=1000 com desconto e invalido porque entregaria apenas 955 centavos.

Solicitar saque

Envie POST /v1/payouts com Idempotency-Key obrigatorio.
integer
required
Valor em centavos (minimo 1000).
string
required
UUID da carteira.
object
required
Chave Pix do destinatario.
string
required
Tipo da chave: cpf, cnpj, email, phone ou random.
string
required
Valor da chave Pix.
string
required
Nome do beneficiario.
boolean
Descontar tarifa do valor. Padrao: false.

Status de um saque

Reserva de saldo

A reserva ocorre antes da chamada externa a provedora:
  • completed consome a reserva definitivamente.
  • failed libera a reserva.
  • unknown mantem a reserva ate confirmacao.
Somente completed confirma a entrega do dinheiro. processing e unknown nao garantem conclusao.

Consultar saque

Use GET /v1/payouts/{id} para sincronizar a situacao com a provedora, mesmo sem webhook.
curl

Tarifa

A tarifa fixa de saque e de 45 centavos por operacao. Consulte a cotacao para ver o impacto exato antes de solicitar.

Idempotencia

Sempre envie Idempotency-Key ao criar. Em caso de falha de comunicacao, repita com a mesma chave, mesmo corpo e mesma credencial. Nao crie outra chave para resolver um resultado incerto.