xFlow para plataformas de checkout

Uma plataforma de checkout que oferece Pix precisa de três coisas da API: gerar o código no momento em que o comprador clica em pagar, saber com segurança quando ele pagou e não perder a venda se um provedor falhar. A API Pix da xFlow entrega as três numa integração REST: a cobrança volta pronta para a tela, a confirmação chega por webhook assinado e, por trás da mesma chamada, estão 11 adquirentes com roteamento por regras e retentativa automática.

O que o checkout exige do Pix

• Código pronto para a tela. O comprador não pode esperar a sua plataforma montar imagem de QR Code.
• Baixa automática. O pedido precisa mudar para pago sem ninguém conferir extrato.
• Venda que não para. Num lançamento ou numa campanha, um provedor instável vira carrinho perdido.
• Clique duplo e reenvio. Um botão clicado duas vezes não pode gerar dois Pix.
• Receita da plataforma. A sua taxa precisa sair de cada venda, sem conta a fazer no fim do mês.

Como a xFlow atende cada ponto

O fluxo do botão "Pagar com Pix"

1. O comprador escolhe Pix e informa nome, e-mail e CPF ou CNPJ. Os três campos são obrigatórios na cobrança (customer.name, customer.email e customer.document).
2. O servidor da plataforma chama POST /api/v1/charges com o valor em centavos, o external_reference igual ao id do pedido e uma Idempotency-Key ligada ao pedido.
3. A regra de roteamento escolhe a adquirente. Se ela não responder, a retentativa automática gera a cobrança na próxima da cadeia.
4. A tela mostra o QR Code e um botão para copiar o código.
5. O comprador paga. A xFlow confere o pagamento na adquirente e envia transaction.paid.
6. O servidor valida a assinatura, confere livemode e o valor e libera o pedido. A tela do comprador, que consulta o seu servidor, muda para pago.

curl -X POST https://app.xflowpayments.com/api/v1/charges \
  -u "pk_live_...:sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: checkout-pedido-98231" \
  -d '{
    "amountCents": 14990,
    "customer": { "name": "Cliente", "email": "cliente@exemplo.com", "document": "00000000000" },
    "description": "Pedido #98231",
    "external_reference": "pedido-98231",
    "splits": [
      { "recipient_id": "id-da-conta-do-lojista", "type": "PERCENTAGE", "percent": 90 }
    ]
  }'

O guia de webhook Pix traz o handler pronto para validar a assinatura.

Split: a taxa da plataforma na própria cobrança

No exemplo acima, a cobrança é criada na conta da plataforma e 90% do líquido vão para a conta do lojista. O que sobra fica com a plataforma. As regras do split de pagamento:

• PERCENTAGE usa percent, uma porcentagem do líquido. FIXED usa amount, em centavos.
• A soma dos percentuais não passa de 100.
• O recebedor precisa ser uma conta ativa da xFlow, diferente da conta que cria a cobrança.
• Split inválido retorna 400. No ambiente de teste, split também retorna 400.

O desenho com muitos lojistas (quem é titular de cada conta e como os lojistas entram na xFlow) é combinado com a equipe antes de começar.

Cuidados na tela de pagamento

• Cobrança expirada. A cobrança pode passar a expired, e não existe webhook de expiração. Confira o status antes de mostrar um QR salvo e gere outra com uma Idempotency-Key nova. O passo a passo está em cobrança Pix expirada.
• Limites de valor. Cada conta tem valor mínimo e máximo por cobrança. Fora da faixa, a resposta é 400 validation e nada é criado.
• Falha geral. Se nenhuma adquirente gerar a cobrança, a resposta é 502 charge_failed. Mostre um botão de tentar de novo e repita com a mesma Idempotency-Key.
• Picos de acesso. O limite de requisições é por conta. Acompanhe x-ratelimit-remaining e, no 429, espere o retry-after.
• Segredo no servidor. A chamada à API sai do seu back-end. O sk_live_ nunca vai para o navegador do comprador.

O que a API não faz hoje

A API trabalha com Pix: cobrança, estorno total e saque. Cartão e checkout hospedado ainda não estão disponíveis na API, então a tela de pagamento é da sua plataforma. O estorno é sempre do valor total, uma vez por cobrança, até 90 dias depois do pagamento.

Comece pelo ambiente de teste

Crie uma chave de teste em Desenvolvedores > Chaves de API, mesmo antes da aprovação do cadastro. Com ela, a cobrança não chama nenhuma adquirente e o copia e cola não é pagável. Simule o pagamento com POST /api/v1/test/charges/{id}/pay e receba o transaction.paid com livemode: false. O roteiro completo está em API Pix sandbox.