API de saque Pix

Para fazer um saque Pix pela API, você envia POST /api/v1/transfers com o valor em centavos e o destino: uma chave Pix ou um código copia e cola de QR Code. A documentação chama esse recurso de "Solicitar saque (Pix out)". É ele que tira o saldo disponível da sua conta e transfere por Pix para quem você indicar. O acompanhamento é feito por webhook ou por consulta. Tudo abaixo segue a documentação da API e vale para a base https://app.xflowpayments.com/api/v1. Para o contexto completo da integração, veja o guia da API Pix.

Antes do primeiro saque

Quatro pontos evitam erro na primeira chamada:

1. Só com chave de produção. Com chave de teste (pk_test_), a resposta é 403 test_mode_unsupported. O fluxo de cobrança dá para testar no sandbox da API Pix; o de saque, não.
2. Saque via API habilitado. Se estiver desabilitado para a sua conta, a resposta é 403 api_withdrawal_disabled.
3. Conta ativa. Conta em análise ou bloqueada recebe 403 account_inactive.
4. Saldo disponível. Consulte antes com GET /api/v1/balance, que responde { "available": ..., "reserved": ..., "currency": "BRL" } em centavos. As taxas de saque da conta aparecem em GET /api/v1/company, nos campos withdrawalPercent e withdrawalFixedCents.

Saque por chave Pix

curl -X POST https://app.xflowpayments.com/api/v1/transfers \
  -u "pk_live_...:sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: saque-1234" \
  -d '{
    "amount": 500,
    "pix_key": "12345678909",
    "pix_key_type": "CPF",
    "message": "Repasse de outubro"
  }'

Os tipos de chave são os mesmos do diretório de chaves do Pix, o DICT. No saque por chave, a taxa sai do próprio amount. A resposta 201 mostra a conta:

{
  "data": {
    "id": "b8d1eaa3-...",
    "status": "requested",
    "amount": 500,
    "net_amount": 465,
    "fee": 35,
    "pix_key": "12345678909",
    "pix_key_type": "cpf",
    "pending_approval": true,
    "failure_reason": null,
    "created_at": "2026-07-20T00:00:00.000Z"
  }
}

Repare que, no exemplo da documentação, pix_key_type volta em minúsculas (cpf). Se o seu código compara esse campo, compare sem diferenciar maiúsculas.

Saque por QR Code

No lugar de pix_key e pix_key_type, envie qr_code com o copia e cola do QR (um payload BR Code):

curl -X POST https://app.xflowpayments.com/api/v1/transfers \
  -u "pk_live_...:sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: saque-qr-1234" \
  -d '{ "qr_code": "00020126580014br.gov.bcb.pix0136...6304ABCD" }'

As regras documentadas:

• QR de valor fixo: amount é opcional. Se você informar, tem que bater com o valor do QR.
• QR de valor variável: amount é obrigatório.
• Não misture qr_code com pix_key/pix_key_type.
• Taxa por cima: o destinatário recebe o valor do QR, e o saldo sai por valor mais taxa.
• Nem todo provedor aceita QR. Quando não aceita, a resposta é 422 transfer_failed e nada é debitado.
• No retorno, pix_key traz o código do QR e pix_key_type vem como qrcode.

Idempotência: um saque por pedido

Envie Idempotency-Key única por saque. Se a rede falhar e você repetir a chamada com a mesma chave, a API devolve o mesmo saque em vez de debitar o saldo de novo. Reusar a chave com um corpo diferente retorna 409 idempotency_conflict. Em saque, isso é o que separa um retry seguro de um pagamento em dobro. O assunto completo está em idempotência em API de pagamento.

Aprovação e status do saque

O comportamento depende da configuração de saque automático da conta:

• Saque automático desligado: o saque nasce pendente de aprovação, com pending_approval: true.
• Saque automático ligado: o saque é processado na hora.

O campo status do saque assume estes valores:

Para consultar um saque, use GET /api/v1/transfers/{id}. Para listar, use GET /api/v1/transfers?status=completed&from=2026-10-01&to=2026-10-31, com a mesma paginação por cursor das cobranças: enquanto a resposta trouxer has_more: true, repita a chamada com starting_after igual ao id do último item.

Webhooks de saque

Assine os eventos em Integrações > Webhooks ou por POST /api/v1/webhooks:

• withdrawal.processing: saque processando.
• withdrawal.completed: saque concluído.
• withdrawal.failed: saque falhou.

Cada entrega chega com o header x-webhook-event e a assinatura x-webhook-signature (HMAC-SHA256 do corpo cru com o segredo do endpoint), e o corpo segue o formato { event, data, createdAt }. A documentação detalha o data dos eventos de cobrança, mas não o dos eventos de saque. Por isso, ao receber um withdrawal.*, confirme o estado atual com GET /api/v1/transfers/{id}, usando o id que você guardou na criação. Responda 2xx: sem isso, a entrega é reenviada até 3 vezes. A validação da assinatura está explicada em webhook Pix.

Erros do saque Pix

Guarde o request_id de cada resposta. Ele identifica a chamada em Integrações > Logs da API e no suporte. A lista geral está em erros da API Pix.

Saque e estorno não são a mesma coisa

O saque transfere o seu saldo para uma chave ou QR que você escolhe. O estorno devolve o valor de uma cobrança paga para quem pagou, usando POST /api/v1/charges/{id}/refund. Se o objetivo é desfazer uma venda, o caminho é o estorno Pix por API.

Saque pela API ou pelo painel

O mesmo saque pode ser pedido à mão no painel, em Recebimentos > Solicitar saque. A API faz sentido quando o saque nasce no seu sistema: um repasse a parceiro no fim do dia, por exemplo, com a Idempotency-Key ligada ao id do repasse. Assim, um job que roda duas vezes não paga duas vezes, e cada saque fica rastreável pelo id e pelo request_id.