Aqui você encontra guias práticos para integrar Pix por API e manter a operação de pé. Os artigos explicam como gerar QR Code e copia e cola, confirmar pagamentos com webhook, testar no sandbox, evitar cobranças duplicadas e fazer estornos e saques. Todo exemplo de código segue a documentação real da API Pix da xFlow, com valores em centavos e as respostas que a API devolve.
Também tratamos de arquitetura: como a orquestração de pagamentos distribui cobranças entre 11 adquirentes e o que muda entre a API Pix do Banco Central e a API de um gateway.
Se você vai começar a integrar agora, a página Desenvolvedores reúne chaves, sandbox, logs e todos os guias técnicos.
BlogAPI de saque PixNa API da xFlow, o saque Pix (Pix out) é um POST /api/v1/transfers com amount em centavos e a chave do destinatário (pix_key e pix_key_type) ou um qr_code copia e cola. O saque nasce com status requested, pode exigir aprovação (pending_approval) e é acompanhado pelos webhooks withdrawal.* ou por GET /api/v1/transfers/{id}. Não funciona com chave de teste.BlogAPI Pix do Bacen x API de gateway: qual usarA API Pix do Bacen é uma especificação padronizada pelo Banco Central que cada prestador de serviços de pagamento implementa para os próprios clientes. Uma API de gateway, como a da xFlow, fica uma camada acima: uma credencial e uma integração que passam por várias adquirentes.BlogAPI Pix em C#Para integrar a API Pix em C#, registre um HttpClient tipado com Basic auth (pk_live_ como usuário, sk_live_ como senha), envie POST /api/v1/charges, mostre o pix.qrCodeBase64 e o pix.copyPaste da resposta e confirme o pagamento pelo webhook transaction.paid, validando o HMACSHA256 do corpo cru com CryptographicOperations.FixedTimeEquals. Antes da produção, teste com chaves pk_test_.BlogAPI Pix em GoPara integrar a API Pix em Go, envie POST /api/v1/charges com net/http e req.SetBasicAuth (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 o HMAC-SHA256 do corpo cru com crypto/hmac e hmac.Equal. Antes da produção, teste com chaves pk_test_.BlogAPI Pix em JavaPara integrar a API Pix em Java, envie POST /api/v1/charges com o java.net.http.HttpClient 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 o HMAC-SHA256 do corpo cru com javax.crypto.Mac e MessageDigest.isEqual. Antes da produção, teste com chaves pk_test_.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.BlogAPI Pix em PHPPara integrar a API Pix em PHP, envie POST /api/v1/charges com cURL usando Basic auth (CURLOPT_USERPWD com pk_live_:sk_live_), exiba o pix.qrCodeBase64 e o pix.copyPaste da resposta e confirme o pagamento pelo webhook transaction.paid, validando o HMAC-SHA256 do corpo cru com hash_hmac e hash_equals. No sandbox, use chaves pk_test_ e simule o pagamento.BlogAPI Pix em PythonPara integrar a API Pix em Python, envie POST /api/v1/charges com requests e auth=(pk_live_, sk_live_), mostre o pix.qrCodeBase64 e o pix.copyPaste da resposta e confirme o pagamento pelo webhook transaction.paid, validando o HMAC-SHA256 do corpo cru com hmac.compare_digest. No sandbox, use chaves pk_test_ e simule o pagamento.BlogAPI Pix no DjangoPara integrar a API Pix no Django, crie a cobrança numa view com POST /api/v1/charges e Basic auth (pk_live_ como usuário, sk_live_ como senha), mostre o pix.qrCodeBase64 e o pix.copyPaste no template e receba o webhook transaction.paid numa view com @csrf_exempt, validando o HMAC-SHA256 de request.body com hmac.compare_digest. Antes da produção, teste com chaves pk_test_.BlogAPI Pix no FastAPIPara integrar a API Pix no FastAPI, use um httpx.AsyncClient com auth=(pk_live_, sk_live_) para enviar POST /api/v1/charges, devolva o pix.qrCodeBase64 e o pix.copyPaste ao front-end e receba o webhook transaction.paid lendo await request.body(), validando o HMAC-SHA256 com hmac.compare_digest e deixando o processamento para BackgroundTasks. Teste antes com chaves pk_test_.BlogAPI Pix no FlutterPara integrar a API Pix no Flutter, o app nunca chama a API com a chave secreta: ele pede a cobrança ao seu backend, que envia POST /api/v1/charges com Basic auth e devolve só o pix.copyPaste. O app desenha o QR Code com um pacote como o qr_flutter, oferece o botão de copiar e acompanha o status pelo seu backend, que recebe o webhook transaction.paid assinado.BlogAPI Pix no LaravelPara integrar a API Pix no Laravel, chame POST /api/v1/charges com Http::withBasicAuth (pk_live_ como usuário, sk_live_ como senha), mostre o pix.qrCodeBase64 e o pix.copyPaste no Blade e receba o webhook transaction.paid numa rota fora da verificação de CSRF, validando o HMAC-SHA256 de $request->getContent() com hash_equals. Antes da produção, teste com chaves pk_test_.BlogAPI Pix no NestJSPara integrar a API Pix no NestJS, crie um service que chama POST /api/v1/charges com fetch e Basic auth (pk_live_ como usuário, sk_live_ como senha), devolva o pix.qrCodeBase64 e o pix.copyPaste ao cliente e receba o webhook transaction.paid num controller, com rawBody: true no NestFactory.create, validando o HMAC-SHA256 de req.rawBody com crypto.timingSafeEqual. Teste antes com chaves pk_test_.BlogAPI Pix no Next.jsPara integrar a API Pix no Next.js, crie a cobrança no servidor, numa Server Action ou num Route Handler, com POST /api/v1/charges e Basic auth (pk_live_ como usuário, sk_live_ como senha), mostre o pix.qrCodeBase64 e o pix.copyPaste no componente e confirme o pagamento em app/api/webhook/route.ts, validando o HMAC-SHA256 de await request.text(). O segredo nunca vai para o navegador.BlogAPI Pix no Ruby on RailsPara integrar a API Pix no Ruby on Rails, envie POST /api/v1/charges com Net::HTTP e basic_auth (pk_live_ como usuário, sk_live_ como senha), mostre o pix.qrCodeBase64 e o pix.copyPaste na view e receba o webhook transaction.paid num controller com skip_forgery_protection, validando o HMAC-SHA256 de request.raw_post com ActiveSupport::SecurityUtils.secure_compare. Teste antes com chaves pk_test_.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.BlogChecklist de integração Pix para produçãoAntes de colocar a integração Pix em produção, confirme: credenciais de produção guardadas só no servidor, Idempotency-Key em toda cobrança e saque, webhook com assinatura validada e handler idempotente, conciliação pelo End-to-end ID, tratamento de limites e erros, fluxo de estorno e monitoramento. Abaixo, a lista para marcar item a item.BlogCobrança Pix expiradaNa API da xFlow, cobrança Pix expirada é a que passou ao status expired: expirou sem pagamento. Não há webhook de expiração, então você detecta pela consulta ou pela listagem com status=expired e, se o cliente ainda quiser pagar, cria uma cobrança nova para o mesmo pedido, com outra Idempotency-Key.BlogComo gerar o QR Code a partir do Pix copia e colaPara gerar o QR Code a partir do Pix copia e cola, passe o texto exato, sem alterar nenhum caractere, a uma biblioteca de QR Code e desenhe módulos escuros sobre fundo claro, com margem de 4 módulos. Na xFlow, a cobrança já traz a imagem pronta em pix.qrCodeBase64; gerar no front-end só compensa quando você precisa de outro formato ou tamanho.BlogComo migrar a API Pix do banco para um gatewayPara migrar a API Pix do banco para um gateway, mapeie cada operação (cobrança, webhook, devolução e conciliação) para o equivalente na nova API, rode as duas integrações em paralelo e mude o tráfego aos poucos, por configuração, até desligar a antiga. Na xFlow, o mapa sai de /cob, /webhook e /devolucao para /charges, /webhooks e /refund.BlogComo saber se o Pix foi pago pela APIPara saber se um Pix foi pago pela API da xFlow, assine o webhook transaction.paid e, como reserva, consulte GET /api/v1/charges/{id} até o status sair de pending. Só libere o pedido com status paid, assinatura válida, livemode: true e valor igual ao do pedido.BlogComo testar webhook localmentePara testar webhook localmente, exponha a porta do seu servidor com um túnel HTTPS público, cadastre essa URL como endpoint usando a chave de teste e simule o pagamento com POST /api/v1/test/charges/{id}/pay. Para repetir um evento sem chamar a API, assine o corpo com o segredo e envie com curl.BlogConciliação de pagamentos com várias adquirentesConciliar pagamentos é conferir se cada valor recebido bate com um pedido e com o extrato. Com várias adquirentes, cada uma devolve dados de um jeito. Na xFlow, toda cobrança volta no mesmo formato, com End-to-end ID, dados de quem pagou, a referência do seu pedido, valor, líquido e taxa.BlogCRC16 do Pix: como calcular e validarO CRC16 do Pix são os 4 últimos caracteres do BR Code. Ele é calculado com o algoritmo CRC-16/CCITT-FALSE (polinômio 0x1021, valor inicial 0xFFFF) sobre todo o código até o 6304, inclusive, e escrito em 4 dígitos hexadecimais.BlogErros da API PixNa API Pix da xFlow, todo erro volta em JSON com error (o código), message e request_id. O status HTTP diz a família do problema: 400 corpo inválido, 401 credencial, 403 conta ou modo, 404 recurso inexistente, 409 idempotência, 422 recusa de negócio, 429 limite e 502 falha no provedor. O request_id localiza a chamada em Integrações > Logs da API.BlogEstorno Pix por APINa API da xFlow, o estorno Pix é um POST /api/v1/charges/{id}/refund que devolve ao pagador o valor total de uma cobrança paga, uma vez por cobrança e até 90 dias após o pagamento. A devolução é assíncrona: a resposta 202 diz que o PSP aceitou o pedido, e a conclusão chega pelo webhook transaction.refunded.BlogEstrutura do Pix copia e cola: o BR Code campo a campoO Pix copia e cola é um BR Code: uma sequência de campos no formato ID (2 dígitos), tamanho (2 dígitos) e valor. Ele traz a versão (00), a conta Pix com o identificador br.gov.bcb.pix e a chave ou uma URL (26), moeda, país, nome e cidade do recebedor, o txid (62-05) e, no fim, o CRC16 (63).BlogFailover de pagamentos: como sobreviver à queda de uma adquirenteFailover de pagamentos é trocar de provedor automaticamente quando o principal deixa de responder. No Pix, isso significa gerar a cobrança em outra adquirente sem o pagador perceber. Na xFlow, a cobrança vai para a próxima adquirente da cadeia, e o seu sistema faz retry seguro com Idempotency-Key.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.BlogOrquestração de pagamentos x gateway: qual a diferençaUm gateway de pagamento liga o seu sistema a um processador e transmite cada transação. A orquestração de pagamentos fica um nível acima: decide entre vários processadores, troca de caminho quando um falha e entrega tudo num formato só. A xFlow faz os dois papéis no Pix.BlogOrquestração de Pix com vários PSPsOrquestrar Pix com vários PSPs é ter uma camada que gera cada cobrança no provedor certo, troca de provedor quando um não responde e padroniza confirmação, estorno, saque e conciliação. Na xFlow, essa camada conecta a sua operação a 11 adquirentes por uma API só.BlogPagamento Pix em lote por APINa API da xFlow não existe um endpoint de lote: cada pagamento é um POST /api/v1/transfers. O lote é uma fila no seu sistema que envia um saque Pix por item, com Idempotency-Key própria, respeita o limite de requisições e confere cada resultado por webhook ou consulta.BlogParticipante do Pix ou API: como a sua empresa acessa o PixNo Pix, participante direto é a instituição que tem Conta PI no Banco Central e conexão direta ao SPI, o sistema que liquida os pagamentos. Participante indireto não tem Conta PI: liquida por meio de um participante direto, que o registra no SPI e atua como seu liquidante.BlogPix copia e cola por API: como gerar o códigoPara gerar um Pix copia e cola por API na xFlow, crie uma cobrança com POST /api/v1/charges: a resposta traz o código em pix.copyPaste, um payload no padrão BR Code, e o QR Code da mesma cobrança em pix.qrCodeBase64.BlogQR Code Pix dinâmico por API: estático x dinâmicoPara gerar um QR Code Pix por cobrança via API na xFlow, chame POST /api/v1/charges: cada cobrança volta com um QR Code próprio em PNG (pix.qrCodeBase64), o copia e cola (pix.copyPaste), o valor do pedido e um status que muda até o pagamento.BlogSegurança na integração da API PixUma integração segura com a API Pix guarda o segredo só no servidor, limita as chamadas por IP, troca as credenciais sem parar a operação, valida a assinatura HMAC de todo webhook e registra o request_id de cada chamada. Abaixo, cada controle da xFlow e o que fica do seu lado.BlogSplit de pagamento para marketplace: como montar no PixNum marketplace, o split de pagamento separa a parte de cada vendedor e a comissão da plataforma na própria cobrança. Na xFlow, você envia o campo splits ao criar a cobrança Pix, por porcentagem do líquido ou valor fixo, e cada vendedor é creditado no próprio saldo quando o pagamento é confirmado.BlogSplit de pagamento x split payment da reforma tributáriaO split payment da reforma tributária é o recolhimento de IBS e CBS no momento da liquidação financeira, feito pelos prestadores de serviços de pagamento, previsto na Lei Complementar 214/2025. O split de pagamento é comercial: divide o valor de uma venda entre recebedores. São coisas diferentes, com o mesmo nome.BlogWebhook Pix não chega: como descobrir o motivoQuando o webhook Pix não chega, confira nesta ordem: se o endpoint está ativo e inscrito no evento certo, se a URL é HTTPS, pública e alcançável, se firewall ou proxy bloqueiam o POST, se o handler responde 2xx rápido e se a assinatura falha por corpo reprocessado. Enquanto investiga, consulte a cobrança pela API para não deixar pedidos parados.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.