{"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":"request-and-response-structure","__idx":0},"children":["Request and response structure"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"request-headers","__idx":1},"children":["Request headers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Include the following headers on every 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":"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":"th","attributes":{"align":"left","data-label":"Notes"},"children":["Notes"]}]}]},{"$$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 (when sending a body)"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["All request bodies must be JSON"]}]},{"$$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"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Retrieved via email"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"request-body-conventions","__idx":2},"children":["Request body 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":["expiry_month"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardholder_name"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Monetary amounts"]}," are integers in the smallest currency unit. For US dollars (USD), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1999"]}," equals 19.99 US dollars."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Dates"]}," use ISO 8601 UTC format: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2026-01-15T14:30:00Z"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Placeholders"]}," in examples use ALL-CAPS with hyphens: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["YOUR-API-KEY"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["YOUR-EMAIL"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"response-envelope","__idx":3},"children":["Response envelope"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every successful response includes the resource data plus a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["correlation_id"]}," for tracing."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"TRANSACTION-01JMRSPCK7XVNP3KS8F2W4T6Y\",\n  \"object\": \"transaction\",\n  \"type\": \"card_sale\",\n  \"transaction_state\": \"authorized\",\n  \"response_status\": \"Approved\",\n  \"response_code\": \"00\",\n  \"response_message\": \"The API request is approved.\",\n  \"amount\": 1999,\n  \"correlation_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n}\n","lang":"json"},"children":[]},{"$$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":"Field"},"children":["Field"]},{"$$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":["id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Unique resource identifier, prefixed by type (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRANSACTION-"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BATCH-"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["object"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Resource type string"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["correlation_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["UUID for request tracing; include this when contacting support"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"pagination","__idx":4},"children":["Pagination"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["List endpoints support offset-based pagination using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["skip"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["take"]}," query parameters."]},{"$$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":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Default"},"children":["Default"]},{"$$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":["skip"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["0"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Number of records to skip"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["take"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["20"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Number of records to return"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example","__idx":5},"children":["Example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl -X GET \\\n  \"https://api.dev.paradisegateway.net/v1/transactions?skip=0&take=25\" \\\n  -H \"APIKEY: YOUR-API-KEY\"\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To retrieve the next page, increment ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["skip"]}," by the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["take"]}," value."]},{"$$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":"Request"},"children":["Request"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"skip"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["skip"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"take"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["take"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Records returned"},"children":["Records returned"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Page 1"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["0"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["25"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["1–25"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Page 2"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["25"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["25"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["26–50"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Page 3"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["50"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["25"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["51–75"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"sorting","__idx":6},"children":["Sorting"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["List endpoints support sorting with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sort_column"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sort_order"]}," parameters."]},{"$$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":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Default"},"children":["Default"]},{"$$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":["sort_column"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Varies by endpoint"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Field name to sort by"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sort_order"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["desc"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Sort direction: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["asc"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["desc"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-in-sorting","__idx":7},"children":["Example in sorting"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl -X GET \\\n  \"https://api.dev.paradisegateway.net/v1/transactions?sort_column=transaction_date&sort_order=asc\" \\\n  -H \"APIKEY: YOUR-API-KEY\"\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"filtering-and-search","__idx":8},"children":["Filtering and search"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["List endpoints support text-based filtering with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["search_text"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["term"]}," parameters."]},{"$$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":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Type"},"children":["Type"]},{"$$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":["search_text"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Free-text search across relevant fields"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["term"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Term-based filter"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-in-filtering","__idx":9},"children":["Example in filtering"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl -X GET \\\n  \"https://api.dev.paradisegateway.net/v1/transactions?search_text=Doe&take=10\" \\\n  -H \"APIKEY: YOUR-API-KEY\"\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"combining-parameters","__idx":10},"children":["Combining parameters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can combine pagination, sorting, and filtering in a single request."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl -X GET \\\n  \"https://api.dev.paradisegateway.net/v1/transactions?skip=0&take=10&sort_column=transaction_date&sort_order=desc&search_text=Doe\" \\\n  -H \"APIKEY: YOUR-API-KEY\"\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"list-response-structure-in-pagination","__idx":11},"children":["List response structure in pagination"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["List endpoints return an array of resources. The response structure follows this pattern."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"data\": [\n    {\n      \"id\": \"TRANSACTION-01JMRSPCK7XVNP3KS8F2W4T6Y\",\n      \"object\": \"transaction\",\n      \"type\": \"card_sale\",\n      \"amount\": 1999\n    },\n    {\n      \"id\": \"TRANSACTION-02KNSTQDL8YWOP4LT9G3X5U7Z\",\n      \"object\": \"transaction\",\n      \"type\": \"card_sale\",\n      \"amount\": 4500\n    }\n  ],\n  \"correlation_id\": \"b2c3d4e5-f6a7-8901-bcde-f12345678901\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"further-reading","__idx":12},"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/restful-design"},"children":["About RESTful design"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/concepts/api-fundamentals/error-handling"},"children":["Error handling"]}]}]}]},"headings":[{"value":"Request and response structure","id":"request-and-response-structure","depth":1},{"value":"Request headers","id":"request-headers","depth":2},{"value":"Request body conventions","id":"request-body-conventions","depth":2},{"value":"Response envelope","id":"response-envelope","depth":2},{"value":"Pagination","id":"pagination","depth":2},{"value":"Example","id":"example","depth":3},{"value":"Sorting","id":"sorting","depth":2},{"value":"Example in sorting","id":"example-in-sorting","depth":3},{"value":"Filtering and search","id":"filtering-and-search","depth":2},{"value":"Example in filtering","id":"example-in-filtering","depth":3},{"value":"Combining parameters","id":"combining-parameters","depth":2},{"value":"List response structure in pagination","id":"list-response-structure-in-pagination","depth":2},{"value":"Further reading","id":"further-reading","depth":2}],"frontmatter":{"title":"Request and response structure","shortTitle":"Request/response structure","intro":"Every {% $env.PUBLIC_BRAND_NAME %} API request follows a consistent structure. This reference covers required headers, pagination, filtering, sorting, and the standard response envelope.","type":"reference","seo":{"title":""}},"lastModified":"2026-06-05T02:46:44.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/concepts/api-fundamentals/request-response-structure","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}