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.

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": "[e-mail]",
    "walletAddress": "0x1234...abcd",
    "blockchain": "BSC_MAINNET",
    "reference": "unique-ref-123",
    "token": "USDT",
    "fiatCurrency": "NGN",
    "fiatAmount": 50000
  }'

Success response

All successful responses follow this structure:

{
  "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:

{
  "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)
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:

{
  "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.