xFlow para SaaS e ERPs

Um SaaS ou um ERP que quer Pix dentro do produto precisa de uma API que crie a cobrança a partir do sistema, avise quando o dinheiro entrou e entregue os dados para conciliar sem planilha. A API Pix da xFlow faz isso por REST, com valores em centavos, webhooks assinados e identificadores que ligam cada Pix ao título que o gerou.

Dois jeitos de colocar Pix num software

Na xFlow, a credencial identifica a empresa: cada cobrança é criada para a conta dona da chave. Por isso, um software que cobra em nome dos clientes tem dois caminhos. Ou cada empresa cliente tem a própria conta e a própria credencial, guardada pelo seu sistema como segredo, ou a cobrança nasce numa conta e o split de pagamento credita cada recebedor. O modelo certo para o seu produto é combinado com a equipe antes de começar.

Mensalidade: uma cobrança por ciclo

A API não tem cobrança recorrente automática. Para mensalidade, o seu sistema gera uma cobrança Pix a cada ciclo e envia o código ao cliente. Use o id da fatura como external_reference e como base da Idempotency-Key. Assim, um job que roda duas vezes no mesmo dia não cria duas cobranças.

curl -X POST https://app.xflowpayments.com/api/v1/charges \
  -u "pk_live_...:sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: fatura-2026-11-cliente-381" \
  -d '{
    "amountCents": 29900,
    "customer": { "name": "Empresa Cliente", "email": "financeiro@cliente.com.br", "document": "00000000000000" },
    "description": "Mensalidade novembro/2026",
    "external_reference": "fatura-2026-11-cliente-381"
  }'

A resposta traz pix.copyPaste e pix.qrCodeBase64, prontos para o e-mail de cobrança ou para a área do cliente.

Baixa e conciliação dentro do sistema

• Baixa por webhook. O evento transaction.paid chega assinado com HMAC-SHA256, com external_reference, amount, net (líquido) e fee (taxa). O guia de webhook Pix mostra a validação.
• Dados para o extrato. A cobrança paga traz payer, com nome, CPF ou CNPJ e banco de quem de fato pagou, e pix.endToEnd, o End-to-end ID da liquidação.
• Sincronização em lote. GET /api/v1/charges aceita status, from, to e external_reference, com paginação por cursor (starting_after e has_more). Um job noturno recupera qualquer baixa que o webhook não entregou.
• Taxas e saldo. GET /api/v1/company devolve as taxas da conta e GET /api/v1/balance o saldo disponível e reservado, em centavos.

O passo a passo de fechar cada Pix com o extrato está em conciliação de pagamentos.

Contas a pagar e devoluções

O mesmo sistema que cobra pode pagar. POST /api/v1/transfers envia um saque Pix por chave ou por QR Code, com Idempotency-Key para não pagar duas vezes. Para desfazer uma venda, POST /api/v1/charges/{id}/refund devolve o valor total ao pagador, uma vez por cobrança, até 90 dias depois do pagamento. Detalhes em API de saque Pix.

Webhooks configurados pelo próprio software

Além do painel, os endpoints de webhook podem ser criados pela API, com POST /api/v1/webhooks. Isso permite que o seu software ative as notificações sozinho durante a configuração de uma conta. A URL precisa ser https:// e pública, cada conta tem até 20 endpoints e o segredo de assinatura aparece uma única vez, na resposta da criação.

Integração e suporte

• Teste antes da aprovação. A chave de teste pode ser criada com o cadastro ainda em análise. O pagamento é simulado com POST /api/v1/test/charges/{id}/pay.
• Logs da API. Toda resposta traz um request_id. Em Integrações > Logs da API, cada chamada aparece com status, duração e código de erro, por 30 dias.
• 11 adquirentes atrás da API. Se a adquirente escolhida não responder, a cobrança é gerada na próxima da cadeia, sem mudança no seu código.

A API trabalha com Pix. Cartão e checkout hospedado ainda não estão disponíveis na API. Para começar, veja a central de Desenvolvedores.