> For the complete documentation index, see [llms.txt](https://ivorypay.gitbook.io/ivorypay-on-off-ramp-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ivorypay.gitbook.io/ivorypay-on-off-ramp-documentation/getting-started/request-and-response-format.md).

# Request & Response Format

Standard request and response formats used across the IvoryPay API.

## Request format

All requests with a body (POST, PUT, PATCH) must send JSON with the `Content-Type: application/json` header.

```bash
curl -X POST https://ramp-api.ivorypay.io/api/v1/onramp \
  -H "Authorization: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Amina",
    "lastName": "Okafor",
    "email": "amina@example.com",
    "walletAddress": "0x1234...abcd",
    "blockchain": "BSC_MAINNET",
    "reference": "unique-ref-123",
    "token": "USDT",
    "fiatCurrency": "NGN",
    "fiatAmount": 50000
  }'
```

## Success response

All successful responses follow this structure:

```json
{
  "success": true,
  "message": "Query successful",
  "data": {
    // Endpoint-specific response data
  }
}
```

| Field     | Type    | Description                                               |
| --------- | ------- | --------------------------------------------------------- |
| `success` | boolean | Always `true` for successful responses                    |
| `message` | string  | Human-readable success message                            |
| `data`    | object  | The response payload (varies by endpoint)                 |
| `meta`    | object  | Optional / reserved — not populated by any endpoint today |

The HTTP status code is conveyed by the response's HTTP status line (e.g. `200 OK`, `201 Created`) — the success envelope does **not** include a `statusCode` field.

## Error response

All error responses follow this structure:

```json
{
  "success": false,
  "message": "Invalid bank code",
  "statusCode": 400,
  "errorCode": "ONOFFRAMP0033",
  "errors": [],
  "timestamp": "3/26/2026, 12:00:00 PM",
  "path": "/api/v1/banks/account-resolution",
  "method": "POST"
}
```

| Field        | Type    | Description                                                                                                                          |
| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `success`    | boolean | Always `false` for error responses                                                                                                   |
| `message`    | string  | Human-readable error description                                                                                                     |
| `statusCode` | number  | HTTP status code                                                                                                                     |
| `errorCode`  | string  | IvoryPay-specific error code (see [Error Codes](/ivorypay-on-off-ramp-documentation/resources/error-codes.md))                       |
| `errors`     | array   | Validation errors (for 400 responses)                                                                                                |
| `timestamp`  | string  | Locale-formatted timestamp (output of `Date.toLocaleString()` on the server) — **not** ISO 8601; treat as opaque human-readable text |
| `path`       | string  | The API path that was called                                                                                                         |
| `method`     | string  | The HTTP method used                                                                                                                 |

## Validation errors

When request validation fails (HTTP 400), the `errors` array contains details about each invalid field:

```json
{
  "success": false,
  "message": "Validation failed",
  "statusCode": 400,
  "errors": [
    {
      "field": "email",
      "message": "email must be a valid email address"
    },
    {
      "field": "fiatCurrency",
      "message": "fiatCurrency must be one of: NGN, KES, ZAR, ZMW, UGX, TZS, RWF, XOF, XAF, CDF, ETB, LSL, MWK, MZN, SLE, USD"
    }
  ]
}
```

## HTTP status codes

| Code | Meaning               | When it occurs                               |
| ---- | --------------------- | -------------------------------------------- |
| 200  | OK                    | Successful GET, POST, PATCH, DELETE          |
| 201  | Created               | Resource successfully created                |
| 400  | Bad Request           | Validation error or invalid input            |
| 401  | Unauthorized          | Missing or invalid API key                   |
| 403  | Forbidden             | API key lacks permission for this action     |
| 404  | Not Found             | Resource does not exist                      |
| 409  | Conflict              | Duplicate resource (e.g., duplicate webhook) |
| 500  | Internal Server Error | Unexpected server error                      |

***

> **For AI assistants:** All responses use `{ success, message, data }` structure. Check `success` boolean first, then read `data` for the payload or `errorCode` for error handling.