xFlow para plataformas de payout

Uma API de pagamento em massa por Pix serve a plataformas que repassam dinheiro para muita gente: entregadores, motoristas, sellers, afiliados, clientes de cashback, ganhadores de prêmios. Na xFlow Payments, cada pagamento é um saque por API, o POST /api/v1/transfers, que tira o valor do saldo da sua conta e envia por Pix para uma chave ou um QR Code. Não existe endpoint que receba uma lista: a massa é uma fila no seu sistema, com um saque e uma Idempotency-Key por favorecido. Os campos e as respostas do saque estão em API de saque Pix.

O que pesa para quem paga muita gente

• Ciclos com hora marcada. O repasse semanal dos entregadores ou o fechamento mensal dos afiliados concentra centenas de pagamentos numa janela curta.
• Pagamento em dobro. Um job que roda duas vezes ou um retry depois de uma queda de rede não pode pagar a mesma pessoa de novo.
• Chave errada. Um favorecido com chave inválida não pode travar o ciclo inteiro.
• Saldo no meio do caminho. O ciclo precisa caber no saldo, com as taxas.
• Quem pagou o quê. No fim do ciclo, cada valor devido tem de estar ligado a um pagamento e a um status.

Como a xFlow atende cada ponto

Saque ou split: qual usar no repasse

Repassar dinheiro a terceiros tem dois caminhos na xFlow, e a escolha depende de quem recebe.

Um marketplace pode usar os dois: split para os sellers com conta na xFlow e saque para quem só informou uma chave. O desenho com split está em xFlow para marketplaces.

O desenho que aguenta volume

1. Um registro por valor devido. Cada corrida, comissão ou prêmio vira uma linha no seu sistema, com id próprio. Esse id gera a Idempotency-Key do saque, como repasse-8841. Assim, a chave nunca muda entre tentativas, e reusar a mesma chave com outro corpo dá 409 idempotency_conflict, o que denuncia erro na geração de chaves. O motivo está em idempotência em API de pagamento.
2. Chave validada no cadastro. Peça a chave Pix quando o favorecido entra na plataforma, não na hora de pagar. Confira o formato pelo tipo: 11 dígitos de CPF, 14 de CNPJ, e-mail, telefone ou chave aleatória no formato UUID. São os tipos do DICT. A documentação da xFlow não traz consulta do titular da chave antes do saque, então a sua checagem é de formato e de cadastro.
3. Prefira chave a QR Code em escala. Nem todo provedor aceita saque por QR: quando não aceita, a resposta é 422 transfer_failed e nada é debitado. A chave evita esse desvio num ciclo grande.
4. Saldo conferido antes. Some o ciclo, inclua as taxas e compare com o available. No saque por chave, a taxa sai do próprio amount; no saque por QR, sai por cima.
5. Envio controlado. O limite de requisições é por conta. Mande os saques em sequência ou com poucos em paralelo, acompanhe x-ratelimit-remaining e, no 429, espere o retry-after. A fila pronta, com retry e gravação de resultado, está em pagamento Pix em lote.
6. Status pelo webhook, confirmação pela consulta. A documentação não detalha o data dos eventos withdrawal.*. Use o evento como gatilho e confirme com GET /api/v1/transfers/{id}.

Conciliação do ciclo

No fim de cada ciclo, cada valor devido precisa ter um id de saque e um status: requested, processing, completed ou rejected. Para conferir o ciclo inteiro, liste com GET /api/v1/transfers?from=...&to=... e siga o cursor starting_after enquanto has_more for true. Saque rejected traz failure_reason e volta para a fila como pagamento novo, depois de corrigido. Guarde o request_id de cada chamada: é com ele que o suporte localiza um pagamento específico. O raciocínio de ligar cada movimento ao seu registro está em conciliação de pagamentos.

Controles que uma plataforma de payout precisa ter

• Alçada fora da API. A API paga o que o seu sistema mandar. Quem monta o ciclo não deveria ser quem libera. Com o saque automático desligado, a aprovação vira uma etapa a mais.
• Allowlist de IP. Limite as chamadas ao IP dos servidores que pagam. Fora da lista, a API responde 401, mesmo com a credencial certa.
• Segredo só no servidor. O sk_live_ fica num cofre ou numa variável de ambiente. Se vazar, revogue no painel: a revogação é imediata.
• Primeiro ciclo pequeno. O saque não roda no sandbox. Valide a fila com a API simulada nos seus testes e comece a produção com poucos favorecidos.

Antes de começar

O saque pela API precisa estar habilitado na conta: sem isso, a resposta é 403 api_withdrawal_disabled. Conta em análise recebe 403 account_inactive. O saque usa o saldo disponível da sua conta na xFlow, onde entra o líquido das cobranças Pix pagas. Se a sua operação paga muita gente, fale com a equipe para revisar a configuração de saque, a aprovação e o volume esperado antes do primeiro ciclo. A referência completa está na documentação da API.