xFlow para fintechs

Uma fintech que movimenta Pix precisa de uma API previsível: entrada e saída de dinheiro, notificações confiáveis, proteção contra duplicidade e um provedor que não seja ponto único de falha. A xFlow Payments entrega isso numa API Pix REST, ligada a 11 adquirentes, com roteamento por regras e retentativa automática.

As dores de quem constrói uma fintech

• Ponto único de falha. Com um provedor Pix só, uma queda para o produto inteiro.
• Duplicidade. Retry mal tratado vira cobrança em dobro ou, pior, saque em dobro.
• Notificação confiável. O sistema precisa saber, com segurança, que o dinheiro entrou ou saiu.
• Conciliação. Cada movimentação precisa bater com o extrato e com o cliente final.
• Depuração. Quando algo dá errado, o time precisa achar a chamada sem abrir chamado.

Recursos da xFlow que resolvem

O ciclo do dinheiro pela API

Fluxo de exemplo: depósito e saque de um cliente

1. O cliente da sua fintech quer colocar dinheiro na conta. Você chama POST /api/v1/charges com um Idempotency-Key e um external_reference que identifica o cliente.
2. A xFlow escolhe a adquirente pela regra de roteamento e devolve o QR Code e o copia e cola.
3. O cliente paga. A xFlow confere o pagamento na adquirente e envia transaction.paid.
4. O seu sistema valida a assinatura do webhook, confere o livemode e credita o cliente.
5. Mais tarde, o cliente pede um saque. Você chama POST /api/v1/transfers com a chave Pix dele e um novo Idempotency-Key.
6. O webhook withdrawal.completed confirma o envio. Se vier withdrawal.failed, você devolve o valor ao cliente no seu controle.

curl -X POST https://app.xflowpayments.com/api/v1/charges \
  -u "pk_live_...:sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deposito-cliente-77-0003" \
  -d '{"amountCents":25000,"customer":{"name":"Cliente","email":"cliente@exemplo.com","document":"00000000000"},"external_reference":"cliente-77"}'

O guia de webhook Pix mostra como validar a assinatura, e o de API de saque Pix cobre o saque por chave e por QR Code.

Controles que uma fintech costuma exigir

• Allowlist de IP. As chamadas podem ser limitadas aos IPs dos seus servidores. Fora da lista, a API responde 401, mesmo com a credencial correta.
• Segredo exibido uma vez. O segredo da chave aparece só na criação, e a revogação no painel tem efeito imediato.
• Saque com aprovação. Com o saque automático desligado, cada saque pela API nasce pendente de aprovação (pending_approval: true). Se o saque via API estiver desabilitado para a conta, a resposta é 403 api_withdrawal_disabled.
• Limites de valor. Cada conta tem um valor mínimo e um máximo por cobrança, em Empresa > Limites e taxas.
• Limite de requisições. O limite é por conta, e toda resposta autenticada traz os cabeçalhos x-ratelimit-*.
• Pagamento conferido. Cada Pix é conferido na adquirente antes de virar saldo.

A página de segurança explica cada controle em detalhe.

Comece pelo ambiente de teste

Crie uma chave de teste em Desenvolvedores > Chaves de API. Ela pode ser criada antes da aprovação do cadastro. Com ela, as cobranças ficam num ambiente separado, não chamam nenhuma adquirente e não aparecem no saldo. Simule o pagamento com POST /api/v1/test/charges/{id}/pay e receba o transaction.paid com livemode: false. Split e saque não estão disponíveis no teste. A central do desenvolvedor reúne os guias.

O que a API não faz hoje

A API trabalha com Pix. Cartão e checkout hospedado ainda não estão disponíveis na API. O estorno é sempre total e uma vez por cobrança.