Segurança

A xFlow Payments protege a sua operação em quatro frentes: confere cada pagamento na adquirente antes de lançar o valor no saldo, controla quem pode usar a API, assina as notificações que envia ao seu sistema e registra cada chamada para você consultar depois. Abaixo está o que cada controle faz e o que fica do seu lado.

Pagamento conferido antes de cair no saldo

Quando a adquirente avisa que um Pix foi pago, a xFlow não lança o valor direto. Primeiro, confere o pagamento na própria adquirente. Só depois disso a cobrança passa a paid, o valor líquido entra no saldo e o webhook transaction.paid é enviado. Um aviso de pagamento sem confirmação na adquirente não vira saldo.

Durante um estorno pendente, o valor líquido da cobrança fica retido do saldo disponível e não pode ser sacado. Se a adquirente recusar o estorno, o valor volta ao saldo.

Credenciais da API

• Chave pública e segredo. A API usa HTTP Basic, com a chave pública (pk_live_) como usuário e o segredo (sk_live_) como senha.
• Segredo exibido uma única vez. A chave pública fica sempre visível no painel. O segredo aparece só na criação. Guarde-o num cofre de segredos do seu servidor.
• Nunca no navegador. O segredo não deve ir para o código do front-end nem para repositórios versionados.
• Revogação imediata. Uma credencial comprometida é revogada no painel, em Desenvolvedores > Chaves de API, e para de funcionar na hora.
• Allowlist de IP. Opcional, no painel. Com ela configurada, chamadas de IPs fora da lista recebem 401, mesmo com a credencial correta.

Ambiente de teste separado

As chaves de teste (pk_test_ e sk_test_) usam os mesmos endpoints, mas num ambiente separado. Cobranças de teste não chamam nenhuma adquirente, não aparecem no saldo, nos dashboards nem no extrato, e o copia e cola devolvido não pode ser pago. Toda resposta e todo webhook de teste trazem livemode: false, para o seu sistema não confundir teste com produção. Saques não estão disponíveis com chave de teste.

Webhooks assinados

Cada webhook traz o cabeçalho x-webhook-signature, com o HMAC-SHA256 do corpo cru, calculado com o segredo do endpoint. O segredo do endpoint também aparece uma única vez, na criação. A URL do endpoint precisa ser https:// e pública: endereços internos são recusados. O guia de webhook Pix tem o código de validação.

Proteção contra duplicidade

O cabeçalho Idempotency-Key vale para cobranças e saques. Se o seu sistema repetir um pedido com a mesma chave e o mesmo corpo, a API devolve o mesmo recurso em vez de gerar outro Pix ou debitar o saldo de novo. Com a mesma chave e um corpo diferente, a resposta é 409 idempotency_conflict. O pedido de estorno repetido na mesma cobrança também devolve o mesmo estorno.

Saques com controle

• Confirmação extra. Saques pedem uma confirmação extra: no painel, o pedido de saque exige o código da verificação em duas etapas.
• Aprovação. Com o saque automático desligado na conta, cada saque pela API nasce pendente de aprovação (pending_approval: true).
• Saque pela API pode ser desligado. Se o saque via API estiver desabilitado para a conta, a API responde 403 api_withdrawal_disabled.

Registro de cada chamada

Toda resposta da API traz um request_id, no corpo e no cabeçalho x-request-id. Em Integrações > Logs da API, cada requisição autenticada aparece com status, duração e código de erro, por 30 dias. O suporte localiza qualquer chamada por esse identificador.

Limites por conta

A API tem limite de requisições por conta. Toda resposta autenticada traz x-ratelimit-limit, x-ratelimit-remaining e x-ratelimit-reset, e acima do limite a resposta é 429. Cada conta também tem um valor mínimo e um máximo por cobrança, visíveis em Empresa > Limites e taxas.

Dados de cartão

A xFlow não guarda dados de cartão. Hoje a API Pix trabalha com Pix: cobrança, estorno total e saque.

O que fica do seu lado

1. Guardar o segredo da chave fora do navegador e fora do repositório.
2. Configurar a allowlist de IP com os endereços dos seus servidores.
3. Validar a assinatura de todo webhook antes de processar.
4. Filtrar livemode antes de dar baixa num pedido real.
5. Enviar um Idempotency-Key único por cobrança e por saque.
6. Revogar na hora qualquer credencial que possa ter vazado.

Os detalhes técnicos estão na documentação e na central do desenvolvedor. Para falar com a equipe, use os canais da página de contato.