About best practices for integration

Your API key authenticates every request to the Reefpay API. Treat it with the same care as a password.

• Store keys in environment variables or a secrets manager. Never hard-code keys in source files.
• Do not expose keys in client-side code. API calls should originate from your server, not from a browser or mobile app.
• Do not commit keys to version control. Add configuration files containing keys to your .gitignore.
• Rotate keys periodically. If you suspect a key has been compromised, request a new key immediately through Reefpay.

Transient errors (network timeouts, 5xx responses, 429 Too Many Requests) are normal in distributed systems. A well-designed retry strategy recovers gracefully.

1. Set a maximum number of retries (for example, 3).
2. Wait before each retry using exponential backoff: delay = base * 2^attempt (for example, 1 second, 2 seconds, 4 seconds).
3. Add random jitter (±25%) to prevent multiple clients from retrying simultaneously.
4. Always include an Idempotency-Key header so retries do not create duplicate resources.

Every error response from Reefpay includes structured fields that help you diagnose and handle the issue.

• Check response_code and response_status on transaction responses to determine whether a payment was approved, declined, or errored.
• Log the correlation_id returned in every response. Include it when contacting support so the team can trace the request across systems.
• Map processor-specific error codes to person-friendly messages. Do not display raw processor codes to persons.

For the full list of response codes and statuses, see About error handling.

Comprehensive logging is critical for debugging, reconciliation, and audit trails.

• Request timestamp, HTTP method, and endpoint
• Request headers (redact the APIKEY value)
• Request body (redact sensitive fields like pan, cvv, account_number)
• Response status code and body
• correlation_id from the response
• Elapsed time

• Full card numbers or bank account numbers
• CVV values
• API keys

Catch errors early by validating data before making API calls.

• Verify that amount is a positive integer representing the smallest currency unit.
• Validate card numbers with a Luhn check.
• Confirm that expiry.month and expiry.year represent a future date.
• Ensure required fields (pan, cardholder_name, cvv, zip) are present and non-empty.

Always develop and test against the sandbox environment before going to production. The sandbox accepts test card numbers and simulates processor responses without moving real funds.

For sandbox configuration details, see Sandbox vs. production.

• About error handling