Pular para o conteúdo
xFlow Payments
EntrarCriar conta

Desenvolvedores

A documentação da API de pagamentos Pix da xFlow é aberta e fica em app.xflowpayments.com/docs, com uma versão em texto para assistentes de IA no llms.txt. Esta página reúne o caminho para integrar: chaves, sandbox, webhooks, logs e guias técnicos.

Atualizado em · Equipe xFlow Payments · 5 min de leitura

A documentação da API de pagamentos Pix da xFlow é aberta e fica em app.xflowpayments.com/docs. Ela cobre autenticação, modo de teste, cobranças, split, saldo, saques, estornos, webhooks e erros, com exemplos em cURL e Node.js. Uma versão em texto puro, feita para assistentes de IA e agentes, está em llms.txt. Esta página mostra por onde começar e onde está cada coisa.

O que a API cobre hoje

A API é REST, com base https://app.xflowpayments.com/api/v1, JSON em UTF-8, datas em ISO 8601 (UTC) e valores sempre em centavos, como inteiros.

  • Cobrança Pix com QR Code em imagem e código copia e cola.
  • Consulta e listagem de cobranças, com filtros e paginação por cursor.
  • Estorno total da cobrança paga, até 90 dias após o pagamento.
  • Saque Pix por chave ou por QR Code.
  • Split do líquido entre contas da xFlow, por porcentagem ou valor fixo.
  • Saldo e dados da conta, incluindo as suas taxas.
  • Webhooks assinados com HMAC-SHA256, gerenciáveis pelo painel ou pela API.

Cartão e checkout hospedado ainda não estão disponíveis na API. A visão de produto completa está na página API Pix.

Mapa da documentação

Tema O que você encontra Link
Autenticação HTTP Basic com chave pública e segredo docs#autenticacao
Primeiros passos O fluxo em 5 passos, da chave ao saldo docs#primeiros-passos
Modo de teste Chaves pk_test_ e simulação de pagamento docs#modo-de-teste
Criar cobrança Parâmetros, idempotência e limites de valor docs#criar-cobranca
Ciclo de status Do pending ao paid, expired ou refunded docs#status
Split Regras de divisão entre contas docs#split
Saques Por chave Pix ou por QR Code docs#solicitar-saque
Estorno Regras, retenção do saldo e recusas docs#estorno
Webhooks Eventos, assinatura e gestão via API docs#webhooks
Erros Códigos, significado e o que fazer docs#erros

Primeiros passos

  1. Crie a sua conta em app.xflowpayments.com/cadastro.
  2. No painel, vá em Desenvolvedores > Chaves de API e gere uma chave de teste.
  3. Crie uma cobrança com POST /api/v1/charges.
  4. Exiba o pix.qrCodeBase64 e o pix.copyPaste ao pagador.
  5. Aguarde a confirmação pelo webhook transaction.paid ou consulte o status.
  6. Com a cobrança paid, o líquido entra no seu saldo.

O teste mais rápido possível é uma consulta de saldo:

bash
curl https://app.xflowpayments.com/api/v1/balance -u "pk_test_...:sk_test_..."

Chaves de API

Cada credencial tem duas partes. A chave pública (pk_live_ ou pk_test_) fica sempre visível no painel. O segredo (sk_live_ ou sk_test_) aparece uma única vez, na criação. Você autentica com HTTP Basic: usuário é a chave pública, senha é o segredo.

  • Guarde o segredo em variável de ambiente ou cofre. Nunca no navegador, nunca no repositório.
  • Revogue credenciais comprometidas no painel. A revogação é imediata.
  • Restrinja por IP, se quiser. Com a allowlist configurada em Chaves de API, requisições de fora da lista recebem 401, mesmo com a credencial correta.
  • Integrações antigas com Authorization: Bearer sk_live_... (só o segredo) continuam funcionando.

Sandbox

As chaves de teste usam os mesmos endpoints e formatos, num ambiente separado: nenhum provedor Pix é chamado, nada aparece no saldo e toda resposta traz livemode: false. O pagamento é simulado com POST /api/v1/test/charges/{id}/pay, que dispara o webhook de teste. Split e saque não funcionam em teste. O guia completo está em API Pix sandbox.

Webhooks

Cadastre endpoints em Integrações > Webhooks ou pela API (/api/v1/webhooks). Cada entrega é um POST com os headers x-webhook-event e x-webhook-signature, reenviado até 3 vezes se você não responder 2xx. A URL precisa ser https:// e pública, com até 20 endpoints por conta. Eventos, validação da assinatura e boas práticas estão no guia de webhook Pix.

Logs da API e request_id

Toda resposta, de sucesso ou de erro, traz um request_id (req_...) no corpo e no header x-request-id. No painel, em Integrações > Logs da API, cada requisição autenticada aparece com status, duração e código de erro. A retenção é de 30 dias. Guarde o request_id nos seus logs: com ele, você e o suporte acham qualquer chamada.

Limites de requisição

O limite é por conta. Toda resposta autenticada traz x-ratelimit-limit, x-ratelimit-remaining e x-ratelimit-reset (o momento da renovação, em epoch). Ao passar do limite, a API responde 429 rate_limited com o header retry-after, que diz quantos segundos esperar. Espere esse tempo e tente de novo com backoff. Para retries que não duplicam cobrança, use o header Idempotency-Key, explicado em idempotência em API de pagamento.

Status dos serviços

A situação da API pública, dos webhooks e do painel fica numa página pública de status. Vale consultar antes de investigar um erro inesperado.

Guias técnicos

Integração:

Sem código e com IA:

Ferramentas gratuitas:

Cobrança e confirmação:

Saída de dinheiro:

Arquitetura:

Glossário:

Suporte durante a integração

Você fala com uma pessoa pelo WhatsApp +55 18 97609-6447 ou pelo e-mail contato@xflowpayments.com, do começo ao fim da integração. Ao relatar um problema numa chamada, envie o request_id: ele leva direto à requisição nos logs.

Perguntas frequentes

Onde fica a documentação da API da xFlow?

Em app.xflowpayments.com/docs, aberta, sem login. A mesma referência existe em texto puro, otimizada para modelos de linguagem, em app.xflowpayments.com/llms.txt.

Preciso de conta aprovada para começar a integrar?

Não para testar. A chave de teste (pk_test_ e sk_test_) pode ser criada antes da aprovação do cadastro. Para cobrar de verdade, a conta precisa estar ativa.

Como encontro uma requisição específica para depurar?

Toda resposta traz um request_id no corpo e no header x-request-id. No painel, em Integrações > Logs da API, cada requisição autenticada aparece com status, duração e código de erro, com retenção de 30 dias.

Como falo com o suporte técnico?

Pelo WhatsApp +55 18 97609-6447 ou pelo e-mail contato@xflowpayments.com. Se for sobre uma chamada específica, informe o request_id.

Continue lendo

SoluçãoAPI PixA API Pix da xFlow Payments é uma API REST para criar cobranças Pix com QR Code e copia e cola, estornar, sacar e receber webhooks assinados. Uma única integração conecta a sua operação a 11 adquirentes, com roteamento por regras e retentativa automática.BlogAPI Pix sandbox: como testar sem mover dinheiroO sandbox da API Pix da xFlow funciona com chaves pk_test_ e sk_test_: mesmos endpoints, mesmas respostas com livemode: false, nenhum dinheiro real e um endpoint para simular o pagamento que dispara o webhook transaction.paid.BlogWebhook Pix: eventos, assinatura HMAC e boas práticasWebhook Pix é o aviso que a API envia para a sua URL quando algo acontece com uma cobrança ou um saque, como o pagamento confirmado. Na xFlow, cada aviso é um POST JSON assinado com HMAC-SHA256, reenviado até 3 vezes até você responder 2xx.BlogIdempotência em API de pagamento: retry sem duplicarIdempotência é a garantia de que repetir a mesma requisição não repete o efeito. Na API da xFlow, você envia o header Idempotency-Key ao criar cobranças e saques: num retry com a mesma chave, a API devolve a mesma cobrança ou o mesmo saque, sem gerar outro Pix nem debitar o saldo de novo.BlogAPI Pix em Node.jsPara integrar a API Pix em Node.js, chame POST /api/v1/charges com fetch e Basic auth (pk_live_ como usuário, sk_live_ como senha), mostre o pix.qrCodeBase64 e o pix.copyPaste da resposta e confirme o pagamento pelo webhook transaction.paid, validando a assinatura HMAC-SHA256 do corpo cru. Antes da produção, teste com chaves pk_test_ e simule o pagamento.