{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"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-restful-design","__idx":0},"children":["About RESTful design"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resources-and-urls","__idx":1},"children":["Resources and URLs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every entity in the API is a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["resource"]}," identified by a URL. Resource URLs follow a consistent pattern."]},{"$$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":"Pattern"},"children":["Pattern"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Example"},"children":["Example"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]}]}]},{"$$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":["/v1/{resource}"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/transactions"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Collection of resources"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/{resource}/{id}"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/transactions/TRANSACTION-01J..."]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Single resource by ID"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/{resource}/{id}/{action}"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/transactions/TRANSACTION-01J.../capture"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Action on a resource"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All URLs are:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Lowercase"]}," with hyphens separating words (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_tokens"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Versioned"]}," with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/"]}," prefix"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Plural"]}," for collection endpoints"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"http-methods","__idx":2},"children":["HTTP methods"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each HTTP method maps to a specific operation on a resource."]},{"$$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":"Method"},"children":["Method"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Purpose"},"children":["Purpose"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Example"},"children":["Example"]}]}]},{"$$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":["GET"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Retrieve a resource or list of resources"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/transactions"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Create a new resource or trigger an action"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/transactions"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Update an existing resource"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT /v1/clients/CLIENT-ID"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Remove a resource"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE /v1/payment_tokens/TOKEN-ID"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"safe-and-idempotent-methods","__idx":3},"children":["Safe and idempotent methods"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Safe methods"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]},") do not modify resources. You can call them repeatedly without side effects."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Idempotent methods"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE"]},") produce the same result whether called once or multiple times."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}]}," is not idempotent."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"json-payloads","__idx":4},"children":["JSON payloads"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All request and response bodies use JSON (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/json"]},")."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"request-example","__idx":5},"children":["Request example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"sale\",\n  \"amount\": 1999,\n  \"payment_method\": {\n    \"type\": \"card\",\n    \"pan\": \"4111111111111234\",\n    \"expiry\": {\n      \"month\": \"03\",\n      \"year\": \"2028\"\n    },\n    \"first_name\": \"John\",\n    \"last_name\": \"Doe\",\n    \"cvv\": \"456\",\n    \"address_line1\": \"123 Main St\",\n    \"zip\": \"10001\"\n  },\n  \"metadata\": {},\n  \"recurring\": false,\n  \"purchase_description\": \"Dog food\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"response-example","__idx":6},"children":["Response example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"approved\": true,\n  \"transaction_id\": \"TRANSACTION-01JMRSPCK7XVNP3KS8F2W4T6Y\",\n  \"response_code\": \"00\",\n  \"reference_id\": \"1234567890\",\n  \"auth_code\": \"592817\",\n  \"response_description\": \"The API request is approved.\",\n  \"requested_amount\": 1999,\n  \"card_holder_name\": \"John Doe\",\n  \"type\": \"sale\",\n  \"transaction_state\": \"authorized\",\n  \"response_status\": \"Approved\",\n  \"response_code\": \"00\",\n  \"amount\": 1999,\n  \"correlation_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"metadata\": {},\n  \"recurring\": false,\n  \"purchase_description\": \"Dog food\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"conventions","__idx":7},"children":["Conventions"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Field names"]}," use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["snake_case"]}," (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction_state"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expiry"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Monetary amounts"]}," are integers in the smallest currency unit. For US dollars, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1999"]}," equals 19.99 US dollars (USD)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Dates and times"]}," use ISO 8601 UTC format (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2026-01-15T14:30:00Z"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["IDs"]}," are prefixed strings that indicate the resource type (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRANSACTION-"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BATCH-"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAYMENT_TOKEN-"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Every response"]}," includes a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["correlation_id"]}," field (UUID) for request tracing and support inquiries."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"http-status-codes","__idx":8},"children":["HTTP status codes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The API uses standard HTTP status codes to indicate the result of a request."]},{"$$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":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Meaning"},"children":["Meaning"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"When returned"},"children":["When returned"]}]}]},{"$$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":["OK"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Request succeeded"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Created"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Resource created successfully"]}]},{"$$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":["Bad request"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Invalid request body or parameters"]}]},{"$$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":["Unauthorized"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Missing or invalid API key"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Forbidden"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Insufficient permissions"]}]},{"$$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":["Not found"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Resource does not exist"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Conflict"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Resource already exists or state conflict"]}]},{"$$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":["Too many requests"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Rate limit exceeded"]}]},{"$$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":["Internal server error"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Unexpected server error"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For detailed error handling guidance, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/concepts/api-fundamentals/error-handling"},"children":["Error handling"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"content-negotiation","__idx":9},"children":["Content negotiation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All requests must include the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Content-Type: application/json"]}," header when sending a body. Responses always return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/json"]},"."]},{"$$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":"Header"},"children":["Header"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Value"},"children":["Value"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Required"},"children":["Required"]}]}]},{"$$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":["Content-Type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/json"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Yes (for requests with a body)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["APIKEY"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Your API key"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Yes (all endpoints except ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/auth/keys"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Idempotency-Key"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["UUID"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Recommended on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," requests"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"further-reading","__idx":10},"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/intro"},"children":["About ","Reefpay"," APIs"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/concepts/api-fundamentals/request-response-structure"},"children":["Request and response structure"]}," "]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/concepts/api-fundamentals/error-handling"},"children":["Error handling"]}]}]}]},"headings":[{"value":"About RESTful design","id":"about-restful-design","depth":1},{"value":"Resources and URLs","id":"resources-and-urls","depth":2},{"value":"HTTP methods","id":"http-methods","depth":2},{"value":"Safe and idempotent methods","id":"safe-and-idempotent-methods","depth":3},{"value":"JSON payloads","id":"json-payloads","depth":2},{"value":"Request example","id":"request-example","depth":3},{"value":"Response example","id":"response-example","depth":3},{"value":"Conventions","id":"conventions","depth":3},{"value":"HTTP status codes","id":"http-status-codes","depth":2},{"value":"Content negotiation","id":"content-negotiation","depth":2},{"value":"Further reading","id":"further-reading","depth":2}],"frontmatter":{"title":"About RESTful design","shortTitle":"RESTful design","intro":"The {% $env.PUBLIC_BRAND_NAME %} API follows RESTful conventions. Resources have predictable URLs, standard HTTP methods indicate the action, and all data travels as JSON.","type":"overview","seo":{"title":""}},"lastModified":"2026-06-05T02:46:44.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/concepts/api-fundamentals/restful-design","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}