About RESTful design

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

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

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

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