API Reference

All endpoints, fields, and error codes.

Base URL: https://api.cloakd.ai/v1 · All requests require X-API-Key header.

GET/v1/status

Check if the API is operational and verify your API key. Authentication is optional.

Response fields

Field	Type	Description
status	string	"ok", "degraded", or "maintenance"
version	string	Current API version
timestamp	string	Server time (ISO 8601)
authenticated	boolean	Whether the API key is valid
merchant_id	string	Your merchant ID (only when authenticated)

POST/v1/payment60 req/min

Create a new payment. Returns a hosted checkout URL to redirect the customer to.

Request body

Field	Req?	Description
pay_amount	Yes	Amount in your settlement currency (string)
order_id	Yes	Your order/invoice ID (max 255 chars)
order_description	No	Description shown on checkout (max 1000 chars)
callback_url	No	Webhook URL for this payment (overrides default)
success_url	No	Redirect after successful payment
cancel_url	No	Redirect if customer cancels
expiration_minutes	No	Expiration in minutes (5–1440, default 60)
customer_email	No	Customer email for receipts

Response fields (201)

Field	Type	Description
id	string	Unique payment ID — store this alongside your order
token_id	string	Public checkout token (used in checkout_url)
order_id	string	Your order ID (echoed back)
checkout_url	string	Hosted payment page — redirect the customer here
status	string	Initial status: WAITING
pay_amount	string	Amount the customer needs to pay
pay_currency	string	Your settlement coin (USDT, USDC, etc.)
pay_network	string	Your settlement network (ethereum, polygon, etc.)
actually_paid	string\|null	Actual amount paid (null until completed)
actually_paid_currency	string\|null	Coin the customer paid with (null until completed)
created_at	string	ISO 8601 creation timestamp
expires_at	string	ISO 8601 expiration timestamp
settled_at	string\|null	ISO 8601 settlement timestamp (null until settled)

GET/v1/payment/:id120 req/min

Retrieve the current state of a payment. Returns the same fields as POST /v1/payment with updated status values.

GET/v1/payments60 req/min

Paginated list of all payments for your merchant account.

Query parameters

Param	Default	Description
page	1	Page number (1-indexed)
limit	20	Results per page (1–100)
status	-	Filter by status (WAITING, SETTLED, etc.)
order_id	-	Filter by your order ID
from_date	-	Filter from date (ISO 8601)
to_date	-	Filter to date (ISO 8601)

Error codes

Code	Meaning
200	Request successful
201	Payment created
400	Validation error — check your request fields
401	Invalid or missing API key
403	API key lacks required permissions
404	Payment not found or does not belong to your account
409	Idempotency key conflict — request already processed
429	Rate limit exceeded — check X-RateLimit-Reset header
500	Internal server error — contact support
503	API temporarily unavailable

Error response format

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "pay_amount is required",
  "details": {
    "field": "pay_amount",
    "constraint": "isNotEmpty"
  },
  "timestamp": "2026-01-03T10:30:00.000Z",
  "path": "/v1/payment",
  "request_id": "req_abc123def456"
}

Rate limit headers

Every API response includes:

X-RateLimit-LimitMaximum requests per window

X-RateLimit-RemainingRequests remaining in the current window

X-RateLimit-ResetUnix timestamp when the limit resets