## Overview

Our API design follows a few simple rules that provide a consistent interface across the entire API surface:

* **POST only:** Every endpoint is accessed via a `POST` request.
* **JSON input:** All request bodies must be a JSON object.
* **JSON output:** All responses are returned as JSON values.
* **Predictable status codes:** We use a minimal set of HTTP status codes to indicate the outcome of your request.

To learn more, read the [WebFunction](https://webfunction.org) specification.

## Request structure

To call a Reservepay endpoint, send a `POST` request with the `Accept: application/json` and `Content-Type: application/json` headers. The request body should be a JSON object containing the arguments for that endpoint.

### Example

```bash
curl -X POST https://api.reservepay.com/merchants/get-balance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## Response structure

Responses are always JSON values. Depending on the endpoint, this could be an object, an array, a string, a number, or a boolean.

## Pagination

Some endpoints return a paginated response. These endpoints follow a standardized structure to make it easy to navigate through large sets of results.

When an endpoint is paginated, the response is a JSON object with three keys:

* `page`: A JSON array containing the items for the current page.
* `next`: A JSON object representing the request for the next page, or `null` if there are no more results.
* `previous`: A JSON object representing the request for the previous page, or `null` if you are on the first page.

### Navigating pages

To navigate, you should not attempt to construct or modify the `next` and `previous` objects. Instead, treat them as opaque tokens. To get the next or previous page, simply send a `POST` request to the same endpoint using the exact JSON object provided in the `next` or `previous` field as the request body.

For more details, see the [WebFunction Pagination](https://webfunction.org/pagination) specification.

## Status codes

We use a small set of HTTP status codes to keep error handling simple:

| Status Code | Meaning |
| :--- | :--- |
| `200 OK` | The request was successful. |
| `400 Bad Request` | Something was wrong with the input. Check the error message for details. |

#### Other status codes

Any other status code means something went wrong on our end. If you see anything besides a `200` or `400`, please let us know at [support@reservepay.com](mailto:support@reservepay.com) so we can fix it.

Note: For more details on error types, see our [Error Handling](/guides/error_handling) guide.

## Namespaces

The API is split into three public namespaces:

* **`merchants/`**: For server-side operations using your secret API key. [See Merchant API reference](/api/merchants).
* **`/sdk/`**: For client-side operations (web or mobile apps) using public identifiers. [See SDK API reference](/api/sdk).
* **`/terminals/`**: For managing payment terminals. [See Terminal API reference](/api/terminals).

## Packages and client generation

At the root of each namespace, we provide a [WebFunction Package](https://webfunction.org/package) definitions that include all the endpoints available in that namespace. You can use them to:

1. Create type-safe API clients for your language.
2. Set up a client dynamically based on your environment.

This makes integration faster and keeps your code in sync with our API.