API Pix

Uma API Pix é o caminho para o seu sistema cobrar e pagar por Pix sem ninguém abrir um painel. O seu código pede a cobrança, recebe o QR Code e o copia e cola, mostra ao cliente e é avisado quando o dinheiro entra. Na xFlow Payments, isso é uma API REST em https://app.xflowpayments.com/api/v1, com JSON em UTF-8, valores em centavos e autenticação HTTP Basic. A mesma integração passa por 11 adquirentes, com roteamento por regras e retentativa automática quando uma delas não responde.

O que a API Pix da xFlow faz

Hoje a API cobre o ciclo inteiro do Pix: entrada, devolução e saída do dinheiro, além das notificações. Todos os caminhos abaixo partem da base /api/v1.

Cobrança Pix com QR Code e copia e cola

Para cobrar, você envia amountCents (o valor em centavos: R$ 19,90 vira 1990) e os dados do cliente em customer: name, email e document (CPF ou CNPJ, só dígitos). Dois campos opcionais ajudam muito no dia a dia. description guarda a sua referência, como "Pedido #1234". external_reference guarda o ID do pedido no seu sistema (até 120 caracteres), volta em toda resposta e webhook da cobrança e pode ser usado como filtro na listagem.

A resposta 201 Created traz a cobrança com status pending e dois campos prontos para o pagador:

• pix.copyPaste: o código Pix copia e cola, um payload no padrão BR Code do Banco Central.
• pix.qrCodeBase64: o QR Code em PNG, no formato data-URL, pronto para colocar no src de uma imagem.

Os dois aparecem na criação e no GET /charges/{id}. A listagem não os inclui. A documentação pede que você trate o código como opaco e repasse sem alterar. Os detalhes estão em como gerar o Pix copia e cola por API e em QR Code Pix dinâmico por API.

Cada conta tem um valor mínimo e um máximo por cobrança, que você vê no painel em Empresa > Limites e taxas. Um valor fora da faixa retorna 400 validation com a mensagem do limite, e nada é criado no provedor.

A cobrança nasce pending e pode passar a paid, expired, canceled, refunded, under_review ou blocked.

Conciliação com o extrato

Quando a cobrança é paga, o GET /charges/{id} passa a trazer os dados de conciliação. O campo customer é o que você informou ao cobrar. O campo payer é quem de fato pagou: nome, CPF ou CNPJ e banco, informados pelo provedor Pix na confirmação. E pix.endToEnd é o End-to-end ID, o identificador único da liquidação do Pix. Com payer e pix.endToEnd você bate cada recebimento com o extrato bancário.

Estorno Pix por API

O POST /charges/{id}/refund devolve o valor ao pagador via Pix. O estorno é total, uma vez por cobrança, só para cobrança paid e até 90 dias após o pagamento. Você pode enviar um reason de até 140 caracteres, que o pagador pode ver.

O estorno é assíncrono. A resposta 202 com status: "pending" quer dizer que o provedor aceitou o pedido, mas o dinheiro ainda não voltou. Enquanto isso, o valor líquido fica retido do seu saldo disponível. A conclusão chega pelo webhook transaction.refunded, e uma recusa chega por transaction.refund_failed, com o valor retido voltando ao saldo. Se a devolução concluir na hora, a resposta já vem 200 com status: "completed". Repetir o pedido na mesma cobrança devolve o mesmo estorno, sem estornar de novo. Veja o passo a passo em estorno Pix por API.

Saque Pix (Pix out)

O POST /transfers envia saldo para uma chave Pix (pix_key e pix_key_type: CPF, CNPJ, EMAIL, PHONE ou EVP) ou paga um QR Code Pix (qr_code). No saque por chave, a taxa sai do próprio amount. No saque por QR Code, o destinatário recebe o valor do QR e a taxa é debitada por cima. Se o saque automático estiver desligado na sua conta, o saque nasce pendente de aprovação (pending_approval: true). Os detalhes estão na API de saque Pix.

Webhooks assinados

Em vez de perguntar o status a cada segundo, você cadastra uma URL e recebe um POST a cada evento: cobrança criada, paga, estornada, estorno recusado, saque processando, concluído ou com falha, além dos eventos de disputa. Cada entrega leva a assinatura x-webhook-signature (HMAC-SHA256 do corpo cru). Tudo sobre eventos, validação e boas práticas está no guia de webhook Pix.

Split entre contas

Ao criar a cobrança, você pode enviar splits para dividir o líquido entre contas da xFlow: PERCENTAGE com percent ou FIXED com amount em centavos. Quando o pagamento confirma, cada recebedor é creditado no saldo dele. Saiba mais em split de pagamento.

Como integrar a API Pix em 5 passos

1. Gere as chaves. Crie a sua conta e, no painel, vá em Desenvolvedores > Chaves de API. Comece por uma chave de teste (pk_test_ e sk_test_), que pode ser criada antes da aprovação do cadastro.
2. Crie a cobrança. Faça um POST /api/v1/charges com o valor e os dados do cliente.
3. Mostre o QR Code e o copia e cola. Use pix.qrCodeBase64 na imagem e pix.copyPaste no botão de copiar.
4. Espere a confirmação. Ouça o webhook transaction.paid ou consulte o status pelo GET.
5. Dê baixa no pedido. Com a cobrança paid, o valor líquido entra no seu saldo.

A chamada de criação fica assim:

curl -X POST https://app.xflowpayments.com/api/v1/charges \
  -u "pk_live_...:sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1234" \
  -d '{
    "amountCents": 1990,
    "customer": {
      "name": "Cliente Exemplo",
      "email": "cliente@exemplo.com",
      "document": "00000000000"
    },
    "description": "Pedido #1234",
    "external_reference": "pedido-1234"
  }'

E a resposta 201:

{
  "id": "clx7a9...",
  "livemode": true,
  "status": "pending",
  "amountCents": 1990,
  "external_reference": "pedido-1234",
  "pix": {
    "copyPaste": "00020101br.gov.bcb.pix...",
    "qrCodeBase64": "data:image/png;base64,iVBORw0..."
  },
  "createdAt": "2026-07-20T00:00:00.000Z",
  "request_id": "req_kJ2m9..."
}

No front-end, o QR Code já vem pronto para exibir:

// charge = resposta do POST /api/v1/charges, repassada pelo seu servidor
document.querySelector("#qr").src = charge.pix.qrCodeBase64;
document.querySelector("#copiar").onclick = () =>
  navigator.clipboard.writeText(charge.pix.copyPaste);

Importante: chame a API sempre do seu servidor. O segredo sk_live_ nunca deve ir para o navegador nem para um repositório versionado.

Quer o mesmo fluxo na sua linguagem? Veja os guias de API Pix com Node.js, PHP, Python, Java, C# e .NET, Go, Laravel, Next.js, Django, FastAPI, NestJS, Ruby on Rails e Flutter, ou baixe os exemplos de código. Sem programar, dá para integrar pelo n8n, Zapier ou Make, e os assistentes de IA podem ler a documentação pelo llms.txt.

Sandbox: teste sem mover dinheiro

Com a chave de teste você usa os mesmos endpoints e recebe os mesmos formatos de resposta, mas tudo fica num ambiente separado. Nenhum provedor Pix é chamado, as cobranças não aparecem no saldo nem nos dashboards e toda resposta traz livemode: false. O pix.copyPaste de teste é um marcador que não pode ser pago.

Para simular o pagamento, chame POST /api/v1/test/charges/{id}/pay com a chave de teste. A cobrança vira paid, a taxa é calculada com as taxas reais da sua conta e o webhook transaction.paid é disparado com livemode: false. Estornos de teste concluem na hora. Split e saque não funcionam em teste. O guia completo está em API Pix sandbox.

Idempotência: repetir sem duplicar

Em pagamentos, uma requisição pode cair por timeout depois de o servidor já ter criado a cobrança. Se o seu sistema tentar de novo sem proteção, nasce um segundo Pix. Para evitar isso, envie o header Idempotency-Key com um valor único por pedido no POST /charges e no POST /transfers. Num retry com a mesma chave, a API devolve a mesma cobrança ou o mesmo saque, sem debitar o saldo de novo. Reusar a chave com um corpo diferente retorna 409 idempotency_conflict. Entenda o porquê e veja exemplos em idempotência em API de pagamento.

Segurança da integração

• Credencial em duas partes. A chave pública (pk_live_) fica sempre visível no painel. O segredo (sk_live_) aparece uma única vez, na criação. Guarde em variável de ambiente ou cofre de segredos.
• Revogação imediata. Se uma credencial vazar, revogue no painel. A revogação vale na hora.
• Allowlist de IP. Em Chaves de API você pode restringir os IPs que usam a sua credencial. Requisições de fora da lista recebem 401, mesmo com a credencial correta.
• Webhooks assinados. Valide o x-webhook-signature com o segredo do endpoint antes de confiar no conteúdo. A URL do endpoint precisa ser https:// e pública.
• Pagamento conferido. A confirmação é revalidada na adquirente antes de o valor cair no saldo.
• Limite de requisições por conta. Toda resposta autenticada traz x-ratelimit-limit, x-ratelimit-remaining e x-ratelimit-reset. Se passar do limite, a API responde 429 rate_limited com o header retry-after, que diz quantos segundos esperar.

Erros e logs da API

Os erros vêm sempre no mesmo formato: { "error": "<codigo>", "message": "...", "request_id": "req_..." }. Os mais comuns na integração:

Toda resposta, de sucesso ou de erro, traz um request_id no corpo e no header x-request-id. Guarde esse valor nos seus logs. 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. Assim você depura a integração sem abrir chamado e, se precisar de suporte, o time encontra a chamada pelo request_id.

Uma integração, 11 adquirentes

Uma API Pix comum liga você a um único provedor. Se ele ficar instável, a sua venda para. Na xFlow, a mesma chamada ao POST /charges passa por uma camada de orquestração conectada a 11 adquirentes integradas.

• Roteamento por regras. Você define qual adquirente recebe cada cobrança, por valor, horário e dia da semana. Veja como funciona em roteamento de pagamentos.
• Retentativa automática. Se uma adquirente não responder, a xFlow tenta de novo e, se precisar, gera a cobrança Pix na próxima da cadeia. A venda continua. Entenda em retentativa automática.
• Cadeia de contingência por regra. A ordem de quem assume em caso de falha é configurável.

O seu código não muda por causa disso: a chamada, o corpo e a resposta são os mesmos. A visão completa está em orquestração de pagamentos e em multiadquirência.

API Pix da xFlow ou API Pix do Banco Central?

O Banco Central padroniza uma especificação chamada API Pix, que os prestadores de serviços de pagamento oferecem aos clientes deles. Ela exige OAuth 2.0 com certificado digital e TLS mútuo, e cada integração vale para o prestador onde você tem conta. A API da xFlow é a de um gateway: uma credencial, HTTP Basic, QR Code já em imagem e várias adquirentes atrás da mesma chamada. Quando cada uma faz sentido está em API Pix do Banco Central x API de gateway.

Por onde começar

A documentação é aberta, com exemplos em cURL e Node.js, em app.xflowpayments.com/docs. Existe também uma versão em texto puro para assistentes de IA, em llms.txt, útil para quem integra com ajuda de um modelo de linguagem. A página Desenvolvedores reúne chaves, sandbox, logs e todos os guias técnicos num só lugar. Durante a integração, você fala com uma pessoa pelo WhatsApp +55 18 97609-6447 ou pelo e-mail contato@xflowpayments.com.