{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition","img"]},"type":"markdown"},"seo":{"title":"Reefpay Docs","description":"Reefpay is the groundbreaking payment gateway that lets you integrate with the future of payments.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"about-best-practices-for-integration","__idx":0},"children":["About best practices for integration"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"secure-your-api-keys","__idx":1},"children":["Secure your API keys"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your API key authenticates every request to the ","Reefpay"," API. Treat it with the same care as a password."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Store keys in environment variables or a secrets manager."]}," Never hard-code keys in source files."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Do not expose keys in client-side code."]}," API calls should originate from your server, not from a browser or mobile app."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Do not commit keys to version control."]}," Add configuration files containing keys to your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".gitignore"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Rotate keys periodically."]}," If you suspect a key has been compromised, request a new key immediately through ","Reefpay","."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"danger","name":"Compromised keys"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you believe your API key has been exposed, rotate it immediately and audit recent transactions for unauthorized activity."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"implement-retry-logic-with-exponential-backoff","__idx":2},"children":["Implement retry logic with exponential backoff"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Transient errors (network timeouts, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5xx"]}," responses, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429 Too Many Requests"]},") are normal in distributed systems. A well-designed retry strategy recovers gracefully."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"recommended-approach","__idx":3},"children":["Recommended approach"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Set a maximum number of retries (for example, 3)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Wait before each retry using exponential backoff: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["delay = base * 2^attempt"]}," (for example, 1 second, 2 seconds, 4 seconds)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add random jitter (±25%) to prevent multiple clients from retrying simultaneously."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Always include an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Idempotency-Key"]}," header so retries do not create duplicate resources."]}]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"https://files.modern-mermaid.live/images/1776270029568-mermaid-diagram-1776270029556.png","alt":"Retry with exponential backoff","framed":false,"withLightbox":true,"className":"retry-with-exponential-backoff","width":"auto","height":"auto"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"which-errors-to-retry","__idx":4},"children":["Which errors to retry"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Status code"},"children":["Status code"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Retry?"},"children":["Retry?"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Reason"},"children":["Reason"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Success"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Bad request — fix the payload"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Unauthorized — check API key"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Not found — check endpoint or resource ID"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Rate limited — back off and retry"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Server error — transient"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["502"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["503"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["504"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Gateway / availability — transient"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handle-errors-gracefully","__idx":5},"children":["Handle errors gracefully"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every error response from ","Reefpay"," includes structured fields that help you diagnose and handle the issue."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response_code"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response_status"]}]}," on transaction responses to determine whether a payment was approved, declined, or errored."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Log the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["correlation_id"]}]}," returned in every response. Include it when contacting support so the team can trace the request across systems."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Map processor-specific error codes"]}," to person-friendly messages. Do not display raw processor codes to persons."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the full list of response codes and statuses, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/concepts/api-fundamentals/error-handling"},"children":["About error handling"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"log-every-request-and-response","__idx":6},"children":["Log every request and response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Comprehensive logging is critical for debugging, reconciliation, and audit trails."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-to-log","__idx":7},"children":["What to log"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Request timestamp, HTTP method, and endpoint"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Request headers (redact the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["APIKEY"]}," value)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Request body (redact sensitive fields like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pan"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cvv"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["account_number"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Response status code and body"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["correlation_id"]}," from the response"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Elapsed time"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-not-to-log","__idx":8},"children":["What not to log"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Full card numbers or bank account numbers"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["CVV values"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["API keys"]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"PCI compliance"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Logging raw card numbers or CVV values violates PCI-DSS requirements. Always redact sensitive payment data before writing to logs."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"validate-inputs-before-sending","__idx":9},"children":["Validate inputs before sending"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Catch errors early by validating data before making API calls."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify that ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}," is a positive integer representing the smallest currency unit."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Validate card numbers with a Luhn check."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Confirm that ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expiry.month"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expiry.year"]}," represent a future date."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ensure required fields (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pan"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardholder_name"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cvv"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["zip"]},") are present and non-empty."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"use-the-sandbox-environment-for-testing","__idx":10},"children":["Use the sandbox environment for testing"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For sandbox configuration details, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/get-started/sandbox-vs-production"},"children":["Sandbox vs. production"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"further-reading","__idx":11},"children":["Further reading"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/concepts/api-fundamentals/error-handling"},"children":["About error handling"]}]}]}]},"headings":[{"value":"About best practices for integration","id":"about-best-practices-for-integration","depth":1},{"value":"Secure your API keys","id":"secure-your-api-keys","depth":2},{"value":"Implement retry logic with exponential backoff","id":"implement-retry-logic-with-exponential-backoff","depth":2},{"value":"Recommended approach","id":"recommended-approach","depth":3},{"value":"Which errors to retry","id":"which-errors-to-retry","depth":3},{"value":"Handle errors gracefully","id":"handle-errors-gracefully","depth":2},{"value":"Log every request and response","id":"log-every-request-and-response","depth":2},{"value":"What to log","id":"what-to-log","depth":3},{"value":"What not to log","id":"what-not-to-log","depth":3},{"value":"Validate inputs before sending","id":"validate-inputs-before-sending","depth":2},{"value":"Use the sandbox environment for testing","id":"use-the-sandbox-environment-for-testing","depth":2},{"value":"Further reading","id":"further-reading","depth":2}],"frontmatter":{"title":"About best practices for integration","shortTitle":"Integration best practices","intro":"Follow these practices when integrating with the {% $env.PUBLIC_BRAND_NAME %} API to build a secure, resilient, and maintainable payment integration.","type":"overview","seo":{"title":""}},"lastModified":"2026-06-05T02:46:44.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/get-started/integration-best-practices","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}