Calling API endpoints

Overview

Our API design follows a few simple rules that provides 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 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

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 specification.

Status codes

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

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 so we can fix it.

Note: For more details on error types, see our 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.
• /sdk/: For client-side operations (web or mobile apps) using public identifiers. See SDK API reference.
• /terminals/: For managing payment terminals. See Terminals API reference.

Packages and client generation

At the root of each namesapce, we provide a WebFunction 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.