Skip to main content

Security Best Practices

Follow these security guidelines to ensure your integration with the Pagamio API remains secure and compliant.

API Authentication​

Bearer Token Storage​

  • ✅ Store tokens in environment variables or secure vaults
  • ✅ Never hardcode tokens in your source code
  • ✅ Use different tokens for different environments
  • ❌ Don't commit tokens to version control
  • ❌ Don't expose tokens in client-side code or logs

Token Rotation​

  • Generate new tokens every hour using the /auth/token endpoint
  • Implement automatic token refresh before expiration
  • Monitor token usage for unusual patterns
  • Revoke compromised tokens immediately

Secure Communication​

HTTPS Only​

  • All API requests must use HTTPS
  • Never make requests over HTTP
  • Validate SSL/TLS certificates
  • Use TLS 1.2 or higher

IP Whitelisting​

  • Configure allowed IP addresses in the Partner Portal
  • Restrict API access to known server IPs only
  • Update whitelist when infrastructure changes
  • Monitor for unauthorized access attempts

Error Handling​

Safe Error Messages​

  • ❌ Don't expose sensitive data in error messages
  • ❌ Don't reveal system architecture details
  • ✅ Log detailed errors server-side
  • ✅ Return generic messages to clients

Example:

// ❌ Bad - exposes details
"Database connection failed at 10.0.0.5:3306";

// ✅ Good - generic
"Service temporarily unavailable. Please try again.";

Request Validation​

Input Sanitization​

  • Validate all input data before sending to the API
  • Check data types, formats, and ranges
  • Sanitize user input to prevent injection attacks
  • Use allowlists for expected values

Required Fields Only​

  • Only send required and necessary fields
  • Remove empty or null values before sending
  • Keep request payloads minimal
  • Use the additionalInfo field carefully

Logging and Monitoring​

What to Log​

  • ✅ All API requests and responses (excluding sensitive data)
  • ✅ Authentication attempts
  • ✅ Error occurrences
  • ✅ Transaction outcomes

What NOT to Log​

  • ❌ Bearer tokens or credentials
  • ❌ PII (ID numbers, addresses)
  • ❌ Card numbers or CVV codes
  • ❌ Raw passwords

Log Retention​

  • Store logs securely with encryption
  • Implement log rotation policies
  • Retain logs for audit purposes
  • Control access to log files

Network Security​

Firewall Configuration​

  • Configure firewalls to allow only necessary traffic
  • Restrict outbound connections to Pagamio API endpoints only
  • Monitor network traffic for anomalies
  • Implement DDoS protection

Rate Limiting​

  • Respect API rate limits (100 requests/minute)
  • Implement client-side rate limiting
  • Use exponential backoff for retries
  • Cache responses where appropriate

Security Checklist​

Before going to production, ensure:

  • ✅ All credentials stored securely in environment variables
  • ✅ HTTPS enforced for all API calls
  • ✅ Token refresh mechanism implemented
  • ✅ Error handling doesn't expose sensitive info
  • ✅ Input validation implemented
  • ✅ Logging configured (excluding sensitive data)
  • ✅ IP whitelist configured
  • ✅ Rate limiting and retry logic implemented
  • ✅ Security audit completed
  • ✅ PCI and POPIA compliance verified
  • ✅ Monitoring and alerting configured
  • ✅ Incident response plan documented

Incident Response​

If you suspect a security breach:

  1. Immediate Action: Revoke all API tokens
  2. Assess Impact: Review logs for unauthorized access
  3. Notify Pagamio: Contact [email protected] immediately
  4. Generate New Credentials: Create new tokens after investigation
  5. Document: Record incident details and response actions

Regular Security Reviews​

  • Conduct security audits quarterly
  • Review and update access controls
  • Test incident response procedures
  • Stay updated on security advisories from Pagamio
  • Train development team on security practices

Last updated: October 2025