Skip to main content

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.

Safefy uses OAuth2 Client Credentials for authentication. You must obtain a JWT token before making any other request.
Credential permissions (module-level read/write, including cashouts) are detailed in Credential permissions.

​
How it works

​
Getting the 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..."
  }'
Response: 
{
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresIn": 3600,
    "environment": "Sandbox"
  }
}

​
Using the token

Include the token in the Authorization header for all requests: 
curl https://api-payment.safefypay.com.br/v1/transactions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
The token expires in 1 hour (3600 seconds). Refresh it before expiration to avoid interruptions.

​
Rate limiting

Token generation is limited to 10 requests per hour per credential pair (publicKey + secretKey). If you exceed this limit, the API returns 429 Too Many Requests with the error code auth_rate_limit_exceeded.
Do not generate a new token on every API call. Cache the token and reuse it for its full 1-hour lifetime. Excessive token generation will trigger the rate limit and block your integration.

​
Token caching

Implement token caching to avoid unnecessary requests and stay well within the rate limit: 
1. Check if savedToken exists
2. If yes  check if (expiresAt - 5 minutes) > now
3. If still valid  reuse savedToken   no API call needed
4. If expired or not found  call POST /v1/auth/token
5. Save new token + calculated expiresAt  use it
Treat the token as expired 25 minutes before its actual expiry (expiresIn - 300 seconds). This protects against clock skew between your server and Safefy’s servers.

​
Security best practices

Never expose the secretKey

Keep the secretKey only on the backend. Never include it in frontend code or public repositories.

Use environment variables

Store credentials in environment variables or secret managers (AWS Secrets Manager, Vault, etc).

Refresh before expiration

Implement logic to refresh the token before the 3600 seconds expire.

Restrict allowed IPs

In the Safefy dashboard, restrict credential usage to your server IPs.

​
Common errors

CodeErrorSolution
401Invalid credentialsCheck publicKey and secretKey
403Unauthorized IPAdd the IP in the credential settings
429Rate limit exceededWait for the time indicated in Retry-After

Test authentication

Try the authentication endpoint in the playground.