Criar Saque

Envia um saque Pix para uma chave Pix ou um código Pix Copia e Cola (BR Code). Método: POST /api/v1/wallet/withdrawals Autenticação: Obrigatória — inclua o header Authorization: Bearer sk_live_sua_api_key. Requer o escopo withdrawal.create.

Este endpoint move dinheiro. Use sempre do seu backend, nunca do navegador ou de um aplicativo público.

Parâmetros do corpo

number

required

Valor em reais que o destinatário vai receber. É obrigatório também com brCode de valor fixo: nesse caso, o servidor decodifica novamente o código e usa o valor nele definido. Para código estático sem valor, amount define o pagamento. A taxa é somada ao valor debitado da carteira. Consulte GET /wallet/withdrawals/quote para os limites da loja.

string

Chave Pix de destino: CPF, CNPJ, e-mail, telefone com DDI 55 ou chave aleatória. Envie pixKey ou brCode, nunca ambos.

string

Código Pix Copia e Cola completo (BR Code/EMV). Use no lugar de pixKey para pagar uma cobrança Pix diretamente com o saldo da loja. Envie brCode ou pixKey, nunca ambos.

string

TOTP atual exigido para saque com sessão; uma API key ativa com escopo withdrawal.create dispensa este campo.

string

Alternativa no corpo ao header Idempotency-Key. O header tem prioridade.

Exemplo: saque por chave Pix

curl -X POST 'https://api.bukiopay.com/api/v1/wallet/withdrawals' \
  --header 'Authorization: Bearer sk_live_sua_api_key' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: saque_pedido_12345' \
  --data '{
    "amount": 100,
    "pixKey": "usuario@exemplo.com"
  }'

Saque por Pix Copia e Cola

Antes do saque, confira o código com POST /api/v1/wallet/withdrawals/pix-code/preview usando a mesma API key (escopo withdrawal.create). A prévia não reserva saldo nem transfere dinheiro.

curl -X POST 'https://api.bukiopay.com/api/v1/wallet/withdrawals/pix-code/preview' \
  --header 'Authorization: Bearer sk_live_sua_api_key' \
  --header 'Content-Type: application/json' \
  --data '{"brCode":"00020101021226...codigo-EMV-completo...6304ABCD"}'

A resposta traz preview.type (static ou dynamic), preview.amount, preview.requiresAmount, preview.merchantName e preview.recipientReference. Confira o valor e o destinatário com o usuário. Em código estático sem valor, preview.amount é null e requiresAmount é true. Para solicitar o saque, envie o BR Code completo em brCode e também amount. Se o código já contém valor, use o valor exibido na prévia; a API consultará e usará o valor do código. Se o código estático não contém valor, amount define quanto o destinatário recebe. Não envie pixKey junto.

curl -X POST 'https://api.bukiopay.com/api/v1/wallet/withdrawals' \
  --header 'Authorization: Bearer sk_live_sua_api_key' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: saque_codigo_pix_12345' \
  --data '{"amount":49.90,"brCode":"00020101021226...codigo-EMV-completo...6304ABCD"}'

Substitua o texto abreviado por um código Pix real e completo: a API valida o formato e o CRC. O saque por brCode está disponível quando o gateway de saída da loja é PurinCash ou processamento manual; em outra configuração, a API retorna 400. Códigos inválidos, fora do limite, já pagos ou expirados são rejeitados. O valor mínimo recebido é R$ 2,00; consulte o máximo e a taxa da loja em GET /api/v1/wallet/withdrawals/quote.

Resposta

Status 201 Created.

{
  "message": "Saque Pix enviado para processamento.",
  "withdrawal": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "processing",
    "amount": 100,
    "feeAmount": 1,
    "totalAmount": 101,
    "currency": "BRL",
    "externalReference": "SAQ-API-6BA7B810",
    "createdAt": "2026-08-06T12:05:00.000Z",
    "processedAt": null
  }
}

number

O que o destinatário recebe.

number

O que foi debitado da sua carteira, já com a taxa.

string

pending, processing, approved ou rejected.

Idempotência

Envie o header Idempotency-Key para poder repetir a requisição sem risco de enviar o dinheiro duas vezes. Use de 8 a 128 caracteres, com letras, números e . _ : -.

Situação	Resposta
Primeira solicitação aceita	`201 Created`
Repetição da mesma chave	`200 OK` com `Idempotency-Replayed: true`
Mesma chave com dados diferentes	`409 Conflict`
Chave cujo registro não existe mais	`410 Gone`

Se você não enviar a chave, a API gera uma e devolve no header Idempotency-Key da resposta.

Confirmação pendente

Se a resposta for 502 com code: "WithdrawalConfirmationPending", o saque pode ter sido enviado e fica em processing.

Nunca repita o saque com uma chave nova nesse caso: você corre o risco de pagar duas vezes. Mantenha a mesma Idempotency-Key e acompanhe o status.

Em falha definitiva, o code é WithdrawalProcessingFailed e o valor volta ao seu saldo. Quando o serviço está indisponível, o code é WithdrawalUnavailable.

Acompanhar

Assine o webhook transfer.completed para saber da conclusão, ou consulte GET /api/v1/wallet/activity?view=withdrawals.

Introdução à API

Cobranças PIX

Saques

Webhooks

Pedidos

Produtos

Categorias

Cupons

Loja

Parâmetros do corpo

Exemplo: saque por chave Pix

Saque por Pix Copia e Cola

Resposta

Idempotência

Confirmação pendente

Acompanhar

​Parâmetros do corpo

​Exemplo: saque por chave Pix

​Saque por Pix Copia e Cola

​Resposta

​Idempotência

​Confirmação pendente

​Acompanhar

Parâmetros do corpo

Exemplo: saque por chave Pix

Saque por Pix Copia e Cola

Resposta

Idempotência

Confirmação pendente

Acompanhar