# 

## Resources and URLs

Every entity in the API is a **resource** identified by a URL. Resource URLs follow a consistent pattern.

| Pattern | Example | Description |
|  --- | --- | --- |
| `/v1/{resource}` | `/v1/transactions` | Collection of resources |
| `/v1/{resource}/{id}` | `/v1/transactions/TRANSACTION-01J...` | Single resource by ID |
| `/v1/{resource}/{id}/{action}` | `/v1/transactions/TRANSACTION-01J.../capture` | Action on a resource |


All URLs are:

* **Lowercase** with hyphens separating words (for example, `payment_tokens`)
* **Versioned** with a `/v1/` prefix
* **Plural** for collection endpoints


## HTTP methods

Each HTTP method maps to a specific operation on a resource.

| Method | Purpose | Example |
|  --- | --- | --- |
| `GET` | Retrieve a resource or list of resources | `GET /v1/transactions` |
| `POST` | Create a new resource or trigger an action | `POST /v1/transactions` |
| `PUT` | Update an existing resource | `PUT /v1/clients/CLIENT-ID` |
| `DELETE` | Remove a resource | `DELETE /v1/payment_tokens/TOKEN-ID` |


### Safe and idempotent methods

* **Safe methods** (`GET`) do not modify resources. You can call them repeatedly without side effects.
* **Idempotent methods** (`GET`, `PUT`, `DELETE`) produce the same result whether called once or multiple times.
* **`POST`** is not idempotent.


## JSON payloads

All request and response bodies use JSON (`application/json`).

### Request example

```json
{
  "type": "sale",
  "amount": 1999,
  "payment_method": {
    "type": "card",
    "pan": "4111111111111234",
    "expiry": {
      "month": "03",
      "year": "2028"
    },
    "first_name": "John",
    "last_name": "Doe",
    "cvv": "456",
    "address_line1": "123 Main St",
    "zip": "10001"
  },
  "metadata": {},
  "recurring": false,
  "purchase_description": "Dog food"
}
```

### Response example

```json
{
  "approved": true,
  "transaction_id": "TRANSACTION-01JMRSPCK7XVNP3KS8F2W4T6Y",
  "response_code": "00",
  "reference_id": "1234567890",
  "auth_code": "592817",
  "response_description": "The API request is approved.",
  "requested_amount": 1999,
  "card_holder_name": "John Doe",
  "type": "sale",
  "transaction_state": "authorized",
  "response_status": "Approved",
  "response_code": "00",
  "amount": 1999,
  "correlation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "metadata": {},
  "recurring": false,
  "purchase_description": "Dog food"
}
```

### Conventions

* **Field names** use `snake_case` (for example, `transaction_state`, `expiry`).
* **Monetary amounts** are integers in the smallest currency unit. For US dollars, `1999` equals 19.99 US dollars (USD).
* **Dates and times** use ISO 8601 UTC format (for example, `2026-01-15T14:30:00Z`).
* **IDs** are prefixed strings that indicate the resource type (for example, `TRANSACTION-`, `BATCH-`, `PAYMENT_TOKEN-`).
* **Every response** includes a `correlation_id` field (UUID) for request tracing and support inquiries.


## HTTP status codes

The API uses standard HTTP status codes to indicate the result of a request.

| Code | Meaning | When returned |
|  --- | --- | --- |
| `200` | OK | Request succeeded |
| `201` | Created | Resource created successfully |
| `400` | Bad request | Invalid request body or parameters |
| `401` | Unauthorized | Missing or invalid API key |
| `403` | Forbidden | Insufficient permissions |
| `404` | Not found | Resource does not exist |
| `409` | Conflict | Resource already exists or state conflict |
| `429` | Too many requests | Rate limit exceeded |
| `500` | Internal server error | Unexpected server error |


For detailed error handling guidance, see [Error handling](/docs/concepts/api-fundamentals/error-handling).

## Content negotiation

All requests must include the `Content-Type: application/json` header when sending a body. Responses always return `application/json`.

| Header | Value | Required |
|  --- | --- | --- |
| `Content-Type` | `application/json` | Yes (for requests with a body) |
| `APIKEY` | Your API key | Yes (all endpoints except `/v1/auth/keys`) |
| `Idempotency-Key` | UUID | Recommended on `POST` requests |


## Further reading

* [About Reefpay APIs](/docs/concepts/api-fundamentals/intro)
* [Request and response structure](/docs/concepts/api-fundamentals/request-response-structure)
* [Error handling](/docs/concepts/api-fundamentals/error-handling)