# 

## Request headers

Include the following headers on every request.

| Header | Value | Required | Notes |
|  --- | --- | --- | --- |
| `Content-Type` | `application/json` | Yes (when sending a body) | All request bodies must be JSON |
| `APIKEY` | Your API key | Yes | Retrieved via email |


## Request body conventions

* **Field names** use `snake_case` (for example, `expiry_month`, `cardholder_name`).
* **Monetary amounts** are integers in the smallest currency unit. For US dollars (USD), `1999` equals 19.99 US dollars.
* **Dates** use ISO 8601 UTC format: `2026-01-15T14:30:00Z`.
* **Placeholders** in examples use ALL-CAPS with hyphens: `YOUR-API-KEY`, `YOUR-EMAIL`.


## Response envelope

Every successful response includes the resource data plus a `correlation_id` for tracing.

```json
{
  "id": "TRANSACTION-01JMRSPCK7XVNP3KS8F2W4T6Y",
  "object": "transaction",
  "type": "card_sale",
  "transaction_state": "authorized",
  "response_status": "Approved",
  "response_code": "00",
  "response_message": "The API request is approved.",
  "amount": 1999,
  "correlation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

| Field | Description |
|  --- | --- |
| `id` | Unique resource identifier, prefixed by type (for example, `TRANSACTION-`, `BATCH-`) |
| `object` | Resource type string |
| `correlation_id` | UUID for request tracing; include this when contacting support |


## Pagination

List endpoints support offset-based pagination using `skip` and `take` query parameters.

| Parameter | Type | Default | Description |
|  --- | --- | --- | --- |
| `skip` | string | `0` | Number of records to skip |
| `take` | string | `20` | Number of records to return |


### Example

```shell
curl -X GET \
  "https://api.dev.paradisegateway.net/v1/transactions?skip=0&take=25" \
  -H "APIKEY: YOUR-API-KEY"
```

To retrieve the next page, increment `skip` by the `take` value.

| Request | `skip` | `take` | Records returned |
|  --- | --- | --- | --- |
| Page 1 | `0` | `25` | 1–25 |
| Page 2 | `25` | `25` | 26–50 |
| Page 3 | `50` | `25` | 51–75 |


## Sorting

List endpoints support sorting with `sort_column` and `sort_order` parameters.

| Parameter | Type | Default | Description |
|  --- | --- | --- | --- |
| `sort_column` | string | Varies by endpoint | Field name to sort by |
| `sort_order` | string | `desc` | Sort direction: `asc` or `desc` |


### Example in sorting

```shell
curl -X GET \
  "https://api.dev.paradisegateway.net/v1/transactions?sort_column=transaction_date&sort_order=asc" \
  -H "APIKEY: YOUR-API-KEY"
```

## Filtering and search

List endpoints support text-based filtering with `search_text` and `term` parameters.

| Parameter | Type | Description |
|  --- | --- | --- |
| `search_text` | string | Free-text search across relevant fields |
| `term` | string | Term-based filter |


### Example in filtering

```shell
curl -X GET \
  "https://api.dev.paradisegateway.net/v1/transactions?search_text=Doe&take=10" \
  -H "APIKEY: YOUR-API-KEY"
```

## Combining parameters

You can combine pagination, sorting, and filtering in a single request.

```shell
curl -X GET \
  "https://api.dev.paradisegateway.net/v1/transactions?skip=0&take=10&sort_column=transaction_date&sort_order=desc&search_text=Doe" \
  -H "APIKEY: YOUR-API-KEY"
```

## List response structure in pagination

List endpoints return an array of resources. The response structure follows this pattern.

```json
{
  "data": [
    {
      "id": "TRANSACTION-01JMRSPCK7XVNP3KS8F2W4T6Y",
      "object": "transaction",
      "type": "card_sale",
      "amount": 1999
    },
    {
      "id": "TRANSACTION-02KNSTQDL8YWOP4LT9G3X5U7Z",
      "object": "transaction",
      "type": "card_sale",
      "amount": 4500
    }
  ],
  "correlation_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}
```

## Further reading

* [About RESTful design](/docs/concepts/api-fundamentals/restful-design)
* [Error handling](/docs/concepts/api-fundamentals/error-handling)