https://xflowpayments.com/blog/ Blog da xFlow Payments: guias de API Pix, webhooks, QR Code, sandbox, idempotência e orquestração entre adquirentes, com exemplos de código fiéis à API real. pt-BR https://xflowpayments.com/blog/api-de-saque-pix/ https://xflowpayments.com/blog/api-de-saque-pix/ Sun, 25 Oct 2026 15:00:00 GMT Na 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. https://xflowpayments.com/blog/api-pix-banco-central-x-gateway/ https://xflowpayments.com/blog/api-pix-banco-central-x-gateway/ Sun, 25 Oct 2026 15:00:00 GMT A 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. https://xflowpayments.com/blog/api-pix-csharp/ https://xflowpayments.com/blog/api-pix-csharp/ Sun, 25 Oct 2026 15:00:00 GMT 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_. https://xflowpayments.com/blog/api-pix-go/ https://xflowpayments.com/blog/api-pix-go/ Sun, 25 Oct 2026 15:00:00 GMT Para 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_. https://xflowpayments.com/blog/api-pix-java/ https://xflowpayments.com/blog/api-pix-java/ Sun, 25 Oct 2026 15:00:00 GMT Para 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_. https://xflowpayments.com/blog/api-pix-node-js/ https://xflowpayments.com/blog/api-pix-node-js/ Sun, 25 Oct 2026 15:00:00 GMT Para 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. https://xflowpayments.com/blog/api-pix-php/ https://xflowpayments.com/blog/api-pix-php/ Sun, 25 Oct 2026 15:00:00 GMT Para 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. https://xflowpayments.com/blog/api-pix-python/ https://xflowpayments.com/blog/api-pix-python/ Sun, 25 Oct 2026 15:00:00 GMT Para 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. https://xflowpayments.com/blog/api-pix-django/ https://xflowpayments.com/blog/api-pix-django/ Sun, 25 Oct 2026 15:00:00 GMT Para 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_. https://xflowpayments.com/blog/api-pix-fastapi/ https://xflowpayments.com/blog/api-pix-fastapi/ Sun, 25 Oct 2026 15:00:00 GMT Para 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_. https://xflowpayments.com/blog/api-pix-flutter/ https://xflowpayments.com/blog/api-pix-flutter/ Sun, 25 Oct 2026 15:00:00 GMT Para 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. https://xflowpayments.com/blog/api-pix-laravel/ https://xflowpayments.com/blog/api-pix-laravel/ Sun, 25 Oct 2026 15:00:00 GMT Para 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_. https://xflowpayments.com/blog/api-pix-nestjs/ https://xflowpayments.com/blog/api-pix-nestjs/ Sun, 25 Oct 2026 15:00:00 GMT Para 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_. https://xflowpayments.com/blog/api-pix-nextjs/ https://xflowpayments.com/blog/api-pix-nextjs/ Sun, 25 Oct 2026 15:00:00 GMT Para 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. https://xflowpayments.com/blog/api-pix-ruby-on-rails/ https://xflowpayments.com/blog/api-pix-ruby-on-rails/ Sun, 25 Oct 2026 15:00:00 GMT Para 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_. https://xflowpayments.com/blog/api-pix-sandbox/ https://xflowpayments.com/blog/api-pix-sandbox/ Sun, 25 Oct 2026 15:00:00 GMT O 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. https://xflowpayments.com/blog/checklist-integracao-pix-producao/ https://xflowpayments.com/blog/checklist-integracao-pix-producao/ Sun, 25 Oct 2026 15:00:00 GMT Antes 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. https://xflowpayments.com/blog/cobranca-pix-expirada/ https://xflowpayments.com/blog/cobranca-pix-expirada/ Sun, 25 Oct 2026 15:00:00 GMT Na 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. https://xflowpayments.com/blog/gerar-qr-code-pix-a-partir-do-copia-e-cola/ https://xflowpayments.com/blog/gerar-qr-code-pix-a-partir-do-copia-e-cola/ Sun, 25 Oct 2026 15:00:00 GMT Para 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. https://xflowpayments.com/blog/migrar-api-pix-de-banco-para-gateway/ https://xflowpayments.com/blog/migrar-api-pix-de-banco-para-gateway/ Sun, 25 Oct 2026 15:00:00 GMT Para 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. https://xflowpayments.com/blog/verificar-pagamento-pix-api/ https://xflowpayments.com/blog/verificar-pagamento-pix-api/ Sun, 25 Oct 2026 15:00:00 GMT Para 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. https://xflowpayments.com/blog/testar-webhook-localmente/ https://xflowpayments.com/blog/testar-webhook-localmente/ Sun, 25 Oct 2026 15:00:00 GMT Para 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. https://xflowpayments.com/blog/conciliacao-de-pagamentos/ https://xflowpayments.com/blog/conciliacao-de-pagamentos/ Sun, 25 Oct 2026 15:00:00 GMT Conciliar 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. https://xflowpayments.com/blog/crc16-pix/ https://xflowpayments.com/blog/crc16-pix/ Sun, 25 Oct 2026 15:00:00 GMT O 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. https://xflowpayments.com/blog/erros-api-pix/ https://xflowpayments.com/blog/erros-api-pix/ Sun, 25 Oct 2026 15:00:00 GMT Na 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. https://xflowpayments.com/blog/estorno-pix-api/ https://xflowpayments.com/blog/estorno-pix-api/ Sun, 25 Oct 2026 15:00:00 GMT Na 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. https://xflowpayments.com/blog/estrutura-do-pix-copia-e-cola/ https://xflowpayments.com/blog/estrutura-do-pix-copia-e-cola/ Sun, 25 Oct 2026 15:00:00 GMT O 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). https://xflowpayments.com/blog/failover-de-pagamentos/ https://xflowpayments.com/blog/failover-de-pagamentos/ Sun, 25 Oct 2026 15:00:00 GMT Failover 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. https://xflowpayments.com/blog/idempotencia-api-de-pagamento/ https://xflowpayments.com/blog/idempotencia-api-de-pagamento/ Sun, 25 Oct 2026 15:00:00 GMT Idempotê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. https://xflowpayments.com/blog/orquestracao-de-pagamentos-x-gateway/ https://xflowpayments.com/blog/orquestracao-de-pagamentos-x-gateway/ Sun, 25 Oct 2026 15:00:00 GMT Um 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. https://xflowpayments.com/blog/orquestracao-de-pix-com-varios-psps/ https://xflowpayments.com/blog/orquestracao-de-pix-com-varios-psps/ Sun, 25 Oct 2026 15:00:00 GMT Orquestrar 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ó. https://xflowpayments.com/blog/pagamento-pix-em-lote/ https://xflowpayments.com/blog/pagamento-pix-em-lote/ Sun, 25 Oct 2026 15:00:00 GMT Na 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. https://xflowpayments.com/blog/participante-direto-e-indireto-do-pix/ https://xflowpayments.com/blog/participante-direto-e-indireto-do-pix/ Sun, 25 Oct 2026 15:00:00 GMT No 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. https://xflowpayments.com/blog/pix-copia-e-cola-api/ https://xflowpayments.com/blog/pix-copia-e-cola-api/ Sun, 25 Oct 2026 15:00:00 GMT Para 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. https://xflowpayments.com/blog/qr-code-pix-dinamico-api/ https://xflowpayments.com/blog/qr-code-pix-dinamico-api/ Sun, 25 Oct 2026 15:00:00 GMT Para 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. https://xflowpayments.com/blog/seguranca-api-pix/ https://xflowpayments.com/blog/seguranca-api-pix/ Sun, 25 Oct 2026 15:00:00 GMT Uma 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. https://xflowpayments.com/blog/split-de-pagamento-marketplace/ https://xflowpayments.com/blog/split-de-pagamento-marketplace/ Sun, 25 Oct 2026 15:00:00 GMT Num 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. https://xflowpayments.com/blog/split-de-pagamento-x-split-payment/ https://xflowpayments.com/blog/split-de-pagamento-x-split-payment/ Sun, 25 Oct 2026 15:00:00 GMT O 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. https://xflowpayments.com/blog/webhook-pix-nao-chega/ https://xflowpayments.com/blog/webhook-pix-nao-chega/ Sun, 25 Oct 2026 15:00:00 GMT Quando 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. https://xflowpayments.com/blog/webhook-pix/ https://xflowpayments.com/blog/webhook-pix/ Sun, 25 Oct 2026 15:00:00 GMT Webhook 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.