Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.safefypay.com.br/llms.txt

Use this file to discover all available pages before exploring further.

A Safefy oferece dois modos de autenticação. Escolha o que melhor se adapta à sua integração:
v2 (Direto, recomendado)v1 (Legacy)
Como funcionaEnvia X-Api-Key + X-Api-Secret em cada requisiçãoGera token JWT via /v1/auth/token e envia no header Authorization
Passo extra de autenticaçãoNãoSim
Limite de rate limit de tokenNão se aplica10 tokens/hora por credencial
Renovação de tokenNão precisaNecessário a cada hora
Recomendado paraTodas as novas integraçõesIntegrações existentes (manter como está)
As permissões da credencial (leitura/escrita por módulo, incluindo saques) estão detalhadas em Permissões da credencial.

​
Autenticação v2 (Direto, recomendado)

Envie suas credenciais diretamente em cada requisição via dois headers. Nenhum passo de geração de token é necessário. 
curl https://api-payment.safefypay.com.br/v1/transactions \
  -H "X-Api-Key: pk_sandbox_abc123..." \
  -H "X-Api-Secret: sk_sandbox_xyz789..."
Este é o modo recomendado para novas integrações. Sem tokens, sem expiração, sem lógica de renovação.

​
Usando o SDK Node.js (v2)

import { SafefyPaymentSDK } from "safefy-sdk-node";

const safefy = new SafefyPaymentSDK({
  publicKey: process.env.SAFEFY_PUBLIC_KEY!,
  secretKey: process.env.SAFEFY_SECRET_KEY!,
  authMode: "v2", // <- sem geração de token
});

// Pode chamar diretamente, sem chamar authenticate() antes
const transactions = await safefy.transactions.list();

​
Autenticação v1 (OAuth2, legacy)

O modo v1 ainda é suportado, mas novas integrações devem utilizar o v2 acima.

​
Como funciona

​
Limite de geração de token (importante)

Para proteger sua integração, existe um limite de 10 tokens por hora para cada credencial. Em termos simples: se sua aplicação ficar pedindo token toda hora, ela pode ser bloqueada temporariamente com erro 429.
Você não deve gerar um novo token a cada requisição. Gere 1 token, salve e reutilize até ele expirar.

​
Obtendo o token

curl -X POST https://api-payment.safefypay.com.br/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grantType": "client_credentials",
    "publicKey": "pk_sandbox_abc123...",
    "secretKey": "sk_sandbox_xyz789..."
  }'
Resposta: 
{
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresIn": 3600,
    "environment": "Sandbox"
  }
}

​
Usando o token

Inclua o token no header Authorization de todas as requisições: 
curl https://api-payment.safefypay.com.br/v1/transactions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
O token expira em 1 hora (3600 segundos). Renove-o antes da expiração para evitar interrupções.

​
Como evitar bloqueio de forma simples

Pense no token como um “ingresso” válido por 1 hora:
  1. Gere o token uma vez.
  2. Salve o accessToken e a data/hora de expiração.
  3. Antes de pedir novo token, verifique se já existe um salvo e ainda válido.
  4. Se ainda estiver válido, use o mesmo token.
  5. Só gere outro quando estiver expirado (ou muito perto de expirar).
Exemplo simples de lógica: 
se existe token salvo E agora < dataExpiracao:
  usar token salvo
senao:
  gerar novo token
  salvar token + dataExpiracao
Uma prática segura é renovar alguns minutos antes da expiração (ex.: 2 a 5 minutos) para evitar falha por diferença de relógio entre servidores.

​
Boas práticas de segurança

Nunca exponha a secretKey

Mantenha a secretKey apenas no backend. Nunca a inclua em código frontend ou repositórios públicos.

Use variáveis de ambiente

Armazene suas credenciais em variáveis de ambiente ou serviços de secrets (AWS Secrets Manager, Vault, etc).

Renove antes de expirar

Implemente logica para renovar o token antes dos 3600 segundos expirarem.

Configure IPs permitidos

No painel Safefy, restrinja o uso das credenciais apenas aos IPs do seu servidor.

​
Erros comuns

CodigoErroSolução
401Credenciais inválidasVerifique publicKey e secretKey
403IP não autorizadoAdicione o IP nas configurações da credencial
429Limite de tokens excedido (auth_rate_limit_exceeded)Reutilize o token já salvo até expirar e respeite o Retry-After

Testar autenticacao

Experimente o endpoint de autenticação no playground.