Documentação da API

Introdução #

A API da SafiPay é HTTP com JSON. Com ela o seu sistema gera cobranças Pix com QR Code, acompanha pagamentos, consulta o saldo, envia transferências Pix e saca em cripto para uma carteira.

Convenções

• Envie o corpo em JSON com o header Content-Type: application/json.
• Valores são em reais, como número com ponto decimal: 150.00 é R$ 150,00. Nas respostas os números vêm sem zeros à direita (150, 2.5).
• Datas seguem ISO 8601 em UTC, como 2026-09-12T17:03:21.000Z.
• Sucesso responde { "success": true, "data": { … } }. Erro responde { "error": "mensagem" } com o status HTTP correspondente. Alguns erros trazem também code, como IP_NOT_ALLOWED ou AMOUNT_BELOW_MINIMUM, para você tratar no código sem depender do texto.
• IDs de transação começam com sfp_ (cobranças) ou sfp_out_ (transferências).

Mudanças recentes

Estas regras passaram a valer para todas as integrações. Confira se o seu sistema já atende a cada uma:

• Credenciais só em header. ci e cs na URL são recusados com 400 e CREDENTIALS_IN_QUERY. Veja Autenticação.
• Só chave de API em /api/gateway/*. A sessão do painel não vale nessas rotas: sem ci e cs, a resposta é 401 com API_KEY_REQUIRED.
• Idempotency-Key recomendada em pix-create e pix-out: repetir a mesma chave devolve a resposta original, sem criar nada de novo. Com caractere fora do formato, 400 com IDEMPOTENCY_KEY_INVALID. Veja Idempotência.
• Valores com até 2 casas decimais. amount precisa ser número com ponto decimal. "100abc", vírgula e 3 casas são recusados com INVALID_AMOUNT.
• Copia e cola precisa ter valor. Em pix-out, código sem valor definido é recusado (BRCODE_DYNAMIC_NOT_ALLOWED), e o valor do código precisa ser igual a amount (BRCODE_AMOUNT_MISMATCH). Veja Transferência Pix.
• Códigos de erro estáveis. Trate os erros pelo campo code. A lista completa está em Códigos de erro.
• Taxa conforme a verificação da conta, com valor mínimo de cobrança por conta (AMOUNT_BELOW_MINIMUM). Veja Taxas.
• Saque cripto pela API. crypto-withdraw envia USDT (rede BEP20) para uma carteira a partir do saldo em reais, com cotação e taxas em crypto-quote. Veja Saque cripto.

Autenticação #

Toda requisição leva as credenciais de uma chave de API em dois headers:

Os nomes X-Client-Id e X-Client-Secret também são aceitos. Crie e revogue chaves em API Keys. O Client Secret aparece uma única vez, na criação, porque a SafiPay guarda só um hash dele. Uma chave revogada para de funcionar na hora.

• Só em header. Credenciais na URL, como ?ci=…&cs=…, são recusadas com 400 e "code": "CREDENTIALS_IN_QUERY", sem executar a operação. Endereços ficam gravados em logs e proxies: se o Client Secret já apareceu numa URL, troque a chave.
• Só chave de API. Os endpoints /api/gateway/* não aceitam a sessão do painel. Sem ci e cs, a resposta é 401 com "code": "API_KEY_REQUIRED", mesmo com login ativo no navegador.

Os exemplos desta página leem as credenciais das variáveis de ambiente SAFIPAY_CLIENT_ID e SAFIPAY_CLIENT_SECRET. Para testar a sua chave, consulte o saldo:

IPs permitidos

Cada chave pode ter uma lista de IPs permitidos, em API Keys (Configurar › IPs permitidos). Com a lista vazia, que é o padrão, a chave aceita chamadas de qualquer IP. Com pelo menos um item, só os IPs da lista conseguem usá-la.

• Aceita IPv4 (177.71.200.14), IPv6 (2804:14c:5b73::1) e faixas CIDR (189.40.88.0/24, 2804:14c:5b73:8a10::/64), até 50 itens por chave.
• Vale o IP público de onde a chamada chega à SafiPay. Se o seu servidor sai para a internet por proxy, NAT ou balanceador, libere o IP de saída, não o IP interno.
• A regra vale para todos os endpoints chamados com a chave. O painel e o checkout não passam por ela.

Uma chamada de IP fora da lista é recusada com 403 e o código IP_NOT_ALLOWED, sem gerar cobrança nem mexer no saldo. As credenciais são conferidas antes do IP: com ci ou cs errados, a resposta continua 401. A mensagem traz o IP que a SafiPay recebeu (IPv4 aparece como IPv4, mesmo vindo por IPv6), o que ajuda a descobrir qual liberar:

Erros de autenticação

Idempotência #

Conexões caem. Para você repetir uma requisição sem gerar cobrança ou transferência em dobro, pix-create, pix-out e crypto-withdraw são idempotentes quando recebem uma chave por operação.

Como funciona

As chaves valem por conta e por endpoint durante 48 horas, contadas da primeira requisição. Depois disso a chave é ignorada e repetir cria uma operação nova; em pix-out e crypto-withdraw, a chave de uma transferência já feita continua recusada com 409 e IDEMPOTENCY_KEY_ALREADY_USED. O corpo é comparado como JSON serializado: mesmos campos, mesmos valores e na mesma ordem.

Repetir com segurança

• Não recebeu resposta (timeout, queda de rede): repita com a mesma chave e o mesmo corpo. Se a primeira chegou a ser processada, você recebe a resposta original.
• Recebeu um erro e corrigiu os dados: o corpo mudou, então use uma chave nova.
• Quer tentar de novo o mesmo pedido depois de um erro (por exemplo, 502): use uma chave nova, porque a resposta de erro também fica guardada.

Taxas #

A taxa depende da verificação da conta. Enquanto a conta não é verificada, vale a taxa padrão de conta não verificada. Depois da aprovação em Verificação, passam a valer as taxas da sua conta. A regra é a mesma para cobranças pela API, checkout hospedado, cobranças do painel e transferências.

O saque cripto tem taxa própria, igual para qualquer conta: veja Saque cripto › Taxas.

O que usar no seu sistema

• fee e netAmount da resposta são a fonte da verdade. Grave os valores devolvidos por pix-create, pix-status, pix-out e pelo webhook. Não recalcule a taxa: ela muda quando a conta é verificada.
• A taxa de cada operação é definida quando ela é criada. Uma cobrança gerada antes da aprovação mantém a taxa com que foi criada, mesmo que seja paga depois.
• Cobranças acima de R$ 1.000,00 (até R$ 5.000,00) pagam 10% + R$ 1,00, com a conta verificada ou não. Até R$ 1.000,00 vale a taxa da conta.
• Cada conta tem um valor mínimo de cobrança: o menor valor que deixa pelo menos R$ 0,01 depois da taxa, nunca abaixo de R$ 1,00. Com a taxa de conta não verificada, o mínimo é R$ 1,13.

Valor abaixo do mínimo

Uma cobrança abaixo do mínimo da conta é recusada com 400 e "code": "AMOUNT_BELOW_MINIMUM". O campo minAmount traz o mínimo atual, em reais. Nada é criado.

Criar cobrança Pix #

Gera uma cobrança Pix com QR Code e código copia e cola. A cobrança nasce com status pending e expira em 30 minutos (veja expiresAt).

Corpo

Campos de texto passam por limpeza antes de gravar: tags HTML são removidas e o que passar do limite é cortado.

Taxa

A taxa sai do valor recebido e depende da verificação da conta (veja Taxas). A conta é fee = amount × percentual ÷ 100, arredondado ao centavo, + valor fixo, e netAmount = amount − fee. Use sempre fee e netAmount da resposta: são os valores que valem para a cobrança.

Erros

Consultar cobrança #

Devolve o status atual da cobrança. Se ela ainda estiver pending, a SafiPay confere o pagamento antes de responder. Se o pagamento já tiver entrado, o saldo é creditado e o webhook pix.paid é disparado nesse momento. A conferência tem um limite por conta (algumas por minuto, no máximo uma a cada 5 segundos por cobrança): acima dele a resposta traz o último status conhecido, sem erro. Até 120 consultas por minuto por conta; acima disso, 429 com RATE_LIMITED e Retry-After. Para acompanhar pagamentos, prefira o webhook.

Parâmetros de consulta

O endpoint também aceita o ID de uma transferência (sfp_out_…). Nesse caso o status vem do registro da transferência na SafiPay. Num saque cripto, a resposta traz também "type": "pix_out", "method": "crypto" e o objeto crypto (moeda, rede, endereço mascarado e estimativa).

Erros

Saldo #

Saldo da conta e totais de movimentação, em reais. balance é o que está disponível agora: já desconta as taxas e o que está reservado por transferências em andamento, porque valor e taxa da transferência saem do saldo no momento do pedido.

Parâmetros de consulta

Sem from e to, os totais cobrem todo o histórico da conta; com eles, só o período. Para setembro inteiro, use from=2026-09-01 e to=2026-10-01. balance e blockedBalance não dependem do período: são sempre o valor do momento. Data em formato inválido responde 400.

balance e currency continuam iguais aos de antes. Integrações que só leem esses dois campos não precisam mudar nada.

Transferência Pix #

Envia um Pix a partir do seu saldo, para uma chave Pix ou pagando um código copia e cola.

Sem mode, a SafiPay usa brcode quando o corpo tem brCode e key nos outros casos.

Corpo

Tipos de chave

No modo copia e cola, o código precisa começar com 0002 e terminar com o CRC (6304 + 4 caracteres), que é conferido. Quebras de linha e caracteres invisíveis colados junto são removidos.

Taxa, saldo e limites

• Cada transferência tem uma taxa fixa, que depende da verificação da conta (veja Taxas). O saldo precisa cobrir valor + taxa, e os dois saem do saldo no momento do pedido. fee e totalDebited da resposta são os valores debitados.
• A sua conta pode ter limite por transferência e limite diário (veja em Configurações). O limite diário soma o valor das transferências pendentes e concluídas desde 00:00, no horário de Brasília. A taxa e as transferências que falharam não entram na conta.
• Até 10 transferências por minuto e 60 por hora pela API, e no máximo 20 pedidos de transferência por hora por conta, somando painel, API e saque cripto. Acima disso, 429 com RATE_LIMITED e o header Retry-After.

Respostas

Erros

Os valores nas mensagens de limite e saldo são exemplos: a mensagem real traz os números da sua conta.

Saque cripto #

Saca do seu saldo em cripto, direto para uma carteira. Você informa o valor em reais: o saldo é debitado em reais, o valor é convertido para USDT e enviado na rede escolhida. As mesmas regras valem para o saque cripto feito no painel, em Transferir.

Moedas e redes

• Hoje a única opção é USDT na rede BEP20. Outra rede (TRC20, ERC20, Polygon) ou outra moeda é recusada com 400 e CRYPTO_NETWORK_INVALID.
• Endereço com letras maiúsculas e minúsculas misturadas precisa conferir com o checksum do endereço (EIP-55); um caractere trocado é recusado com CRYPTO_ADDRESS_INVALID. Endereço todo em minúsculas também é aceito.
• Espaços, quebras de linha e caracteres invisíveis colados junto com o endereço são removidos. O endereço 0x000…000 é recusado.

Corpo

Envie Idempotency-Key como em pix-out (veja Idempotência): repetir a mesma chave e o mesmo corpo devolve a resposta original sem enviar de novo.

Taxas

• Taxa SafiPay: R$ 2,00 por saque cripto, debitada do saldo junto com o valor. Vem em fee. A taxa de transferência Pix não é cobrada no saque cripto.
• Taxa de conversão: 5% sobre o valor convertido, paga de dentro do valor da transferência.
• Taxa da rede: R$ 3,00, paga de dentro do valor da transferência.
• Convertido = valor − taxa de conversão − taxa da rede. Como os 5% incidem sobre o convertido, e não sobre o valor inteiro, a taxa de conversão de uma transferência de R$ 100,00 é R$ 4,62, não R$ 5,00. Vem em convertedAmount.
• Total debitado = valor + taxa SafiPay. Vem em totalDebited.
• Valor estimado recebido = convertido ÷ cotação, arredondado para baixo, em USDT. É uma estimativa: o valor final usa a cotação do momento do processamento.

As taxas da conversão e da rede podem mudar. Consulte crypto-quote antes de enviar e grave fee, totalDebited e crypto da resposta em vez de recalcular.

Saldo e limites

• O saldo precisa cobrir valor + taxa SafiPay; os dois saem do saldo no momento do pedido.
• Valor de R$ 24,00 a R$ 3.000,00 por saque, e até o limite por transferência da sua conta (padrão R$ 1.000,00, veja em Configurações).
• O limite diário da conta vale para Pix e cripto juntos: soma o valor das transferências pendentes e concluídas desde 00:00, no horário de Brasília.
• Até 3 saques cripto por minuto e 20 por hora por conta, somando todas as chaves, dentro do limite de 20 pedidos de transferência por hora da conta (Pix e cripto, painel e API). Acima disso, 429 com RATE_LIMITED e o header Retry-After.
• Com as transferências pausadas pela SafiPay, o pedido é recusado com 503 e WITHDRAWALS_PAUSED, sem debitar.

Respostas

crypto.address vem sempre mascarado nas respostas, na consulta e no webhook. crypto.estimatedAmount e crypto.rate podem vir null quando não há cotação disponível no momento do pedido.

Cotação e taxas

GET /api/gateway/crypto-quote devolve as redes aceitas, os limites, as taxas e a estimativa para um valor, calculada pela SafiPay. Não debita nada. Até 30 consultas por minuto por conta.

maxAmount já considera o limite por transferência da sua conta. Sem cotação no momento, rate, quotedAt e estimate.estimatedAmount vêm null: a conversão usa a cotação do momento do processamento.

Status e webhook

O saque cripto é uma transferência ("type": "pix_out", ID sfp_out_…): segue os status de transferência, aparece no Extrato e é consultado em pix-status. Os webhooks são os mesmos da transferência Pix, pixout.paid e pixout.failed, com data.method igual a crypto e o objeto data.crypto.

Erros

Os valores nas mensagens de limite e saldo são exemplos: a mensagem real traz os números da sua conta.

Webhooks #

Com uma URL cadastrada, a SafiPay faz um POST no seu servidor quando uma transação muda de status. A URL da conta fica em Webhooks. Cada chave de API pode ter URL e segredo próprios, em API Keys.

Configuração

• A URL precisa ser HTTPS, num domínio público e sem usuário e senha. URLs que apontam ou resolvem para localhost, rede privada ou endereços reservados são recusadas ao salvar e conferidas de novo a cada entrega. A regra vale para a URL da conta e para a de cada chave.
• Trocar ou remover uma URL, da conta ou de uma chave, exige a senha da conta.
• O segredo da conta, com 64 caracteres hexadecimais, fica em Webhooks. O segredo de uma chave começa com whsec_ e é gerado quando você cadastra a primeira URL da chave; você vê e troca em API Keys, confirmando com a senha.

Conta ou chave: para onde vai o aviso

• Vale para cobranças e transferências, no envio automático, nos reenvios automático e manual e na rotina de conciliação.
• Com uma URL por chave, cada sistema recebe só os avisos das transações criadas com a chave dele. Valide a assinatura com o segredo da mesma chave.
• Transações criadas com uma chave que depois foi revogada continuam avisando a URL dessa chave, com o segredo dela.
• O teste de uma chave, em API Keys, usa a URL e o segredo da chave. Sem URL própria, vai para o webhook da conta.

Eventos

pix.expired e pix.failed são enviados quando a opção Enviar cobranças expiradas e falhas está ligada em Webhooks. Contas criadas antes dessa opção começam com ela desligada, para não surpreender integrações que tratam qualquer aviso como pagamento; contas novas começam com ela ligada. Desligada, esses eventos só chegam quando você reenvia manualmente o webhook de uma cobrança nesse status.

Uma cobrança expirada ainda pode ser paga, se o pagamento for confirmado depois. Nesse caso chegam os dois avisos, primeiro pix.expired e depois pix.paid: não cancele um pedido de forma definitiva só pelo pix.expired.

Corpo

No test.ping, data.clientId indica a chave testada, quando o teste é feito por uma chave em API Keys. O corpo chega compacto, sem quebras de linha; os exemplos estão formatados só para leitura.

Headers

As duas assinaturas usam o mesmo segredo: o da chave, quando o aviso vai para a URL da chave, ou o da conta. Cada tentativa, inclusive os reenvios, tem um t novo e por isso uma assinatura V2 nova; o corpo é sempre o mesmo.

Resposta esperada e reenvio

• Responda com qualquer status 2xx em até 10 segundos. O corpo da sua resposta é ignorado.
• Redirecionamentos (3xx) não são seguidos e contam como falha. Cadastre a URL final.
• Outros status, erro de conexão, certificado inválido ou tempo esgotado contam como falha.
• Eventos automáticos que falham entram na fila de reenvio: até 6 tentativas no total, com intervalos mínimos de 1 min, 5 min, 30 min, 2 h e 12 h. A fila é processada por uma rotina agendada, então o reenvio pode demorar mais que o intervalo.
• O reenvio usa o mesmo corpo da primeira tentativa, com assinatura e t novos. Se a transação mudou de status desde a falha, o evento antigo não é reenviado. Quando uma tentativa é entregue, as pendentes do mesmo evento são canceladas.
• O teste e o reenvio manual fazem uma tentativa só.

Todas as tentativas, com status HTTP, duração e próxima tentativa, aparecem no histórico da página Webhooks.

Validar a assinatura

Valide a V2 em todo aviso, antes de converter o corpo para objeto:

1. Leia X-SafiPay-Signature-V2 e separe t e v1.
2. Recuse se t estiver a mais de 300 segundos do seu relógio, para mais ou para menos. Assim um aviso copiado não pode ser reenviado depois.
3. Calcule o HMAC-SHA256 de t, um ponto e os bytes do corpo exatamente como chegaram, com o segredo certo: o da chave ou o da conta.
4. Compare o resultado em hexadecimal com v1 numa comparação de tempo constante. Recuse o que não bater.

Link de pagamento #

Toda cobrança criada pela API ganha uma página pública de pagamento. O endereço vem em paymentLink, na resposta de pix-create e de pix-status:

Use quando não quiser montar a tela de pagamento: mande o link por WhatsApp ou e-mail, ou redirecione o cliente para ele. Se o seu site já mostra o QR Code, não precisa usar.

O que o cliente vê

• A página não gera outra cobrança. Para cobrar de novo depois que expirar, crie outra com pix-create e envie o novo link.
• Ela não mostra dados do pagador, taxa nem IDs internos. O token tem 32 caracteres hexadecimais aleatórios e só abre esta página.
• Pagar pela página é o mesmo que pagar o QR Code: a cobrança aparece no Extrato e dispara pix.paid no webhook, como qualquer outra.
• paymentLink pode vir null se o recurso ainda não estiver ativo na sua conta. Nesse caso, mostre o QR Code e o copia e cola.

Checkout hospedado #

Para vender sem integrar a API, crie um produto em Produtos. Cada produto ganha um link público de pagamento:

• O comprador abre o link, informa nome, e-mail e, conforme a configuração do produto, CPF/CNPJ e telefone. Paga com Pix e vê a confirmação na mesma página.
• O preço vai do mínimo da conta até R$ 5.000,00, com a mesma taxa de uma cobrança pela API (veja Taxas).
• Cada pedido gera uma cobrança Pix comum: aparece no Extrato com o nome do produto na descrição e dispara pix.paid no seu webhook quando é pago, no mesmo formato da API.
• Você escolhe o tema da página, a mensagem de confirmação e, se quiser, um link HTTPS para onde levar o comprador depois do pagamento.

Status das transações #

Cobranças sem pagamento confirmado 1 hora depois de criadas, com expiresAt já vencido, passam a expired automaticamente, sem esperar a rotina de conciliação: uma consulta a pix-status nesse ponto já responde expired. Se o pagamento for confirmado depois, a cobrança muda para paid e credita normalmente. Por isso, trate pix.paid mesmo para pedidos que você já deu como vencidos.

Erros #

Erros vêm com o status HTTP e o corpo { "error": "mensagem" }. As mensagens são em português e podem ser mostradas ao seu time. Para decidir no código, use o status HTTP. As mensagens de cada endpoint estão na seção dele.

Códigos de erro

Quando existe, o campo code identifica o erro sem depender do texto da mensagem. Trate por ele.

Boas práticas #