Começar
Autenticação
A API Realfy usa par API Key + Secret via headers HTTP. Sem OAuth, sem token de acesso temporário. Você gerencia as keys diretamente no painel.
Como obter
- Acesse realfy.io/signup e crie sua empresa
- Painel → API Keys → Nova chave
- Copie a
keye osecretexibidos (secret só aparece uma vez) - Guarde em variável de ambiente do seu app, nunca em código versionado
Como usar
Adicione os dois headers em toda request:
X-Api-Key: rfy_live_xxxxxxxxxxxxxxxxxxxx
X-Api-Secret: xxxxxxxxxxxxxxxxxxxxxxxx ⚠
Secret nunca no front
Nunca exponha o
X-Api-Secret em código que roda no browser ou no app móvel.
A chamada sempre tem que vir do servidor do seu sistema.
Ambientes
| Ambiente | Prefixo da key | Base URL |
|---|---|---|
| Produção | rfy_live_* | https://api.realfy.io |
| Sandbox (em breve) | rfy_test_* | https://api-sandbox.realfy.io |
Múltiplas keys
Você pode ter várias keys ativas simultaneamente. Útil pra:
- Separar ambientes (staging vs prod do seu app)
- Cada microsserviço ter sua key (auditoria fica clara nos logs)
- Rotação sem downtime (cria a nova, migra os apps, desativa a antiga)
IP allowlist (recomendado pra cash-out)
Você pode restringir quais IPs podem usar a chave pra fazer cash-out
(saque PIX via POST /v1/withdrawals). Lista vazia = sem restrição (default).
Configure no painel da key. Aceita IP único ou CIDR:
203.0.113.42 // IP único
203.0.113.0/24 // toda a sub-rede
2001:db8::1 // IPv6
ⓘ
A restrição de IP só vale pra POST /v1/withdrawals. Cash-in (receber) não
tem restrição porque não há vetor de ataque relevante — alguém pagando pra você não é problema.
Quando algo der errado
HTTP Code O que fazer 401 AUTH_REQUIREDHeaders não enviados 401 INVALID_CREDENTIALSKey ou secret errados 403 IP_NOT_ALLOWEDIP fora da allowlist do cash-out 403 COMPANY_SUSPENDEDSua conta foi suspensa — contate suporte