Responses & conventions

Response envelope

Every response contains data, requestId, and error. On success, error is null. On failure, data is null and error contains a numeric code and a message. Save requestId for support without logging keys or card credentials.

{
  "data": { "status": "ok", "mode": "TEST" },
  "requestId": "partner-example-request",
  "error": null
}

Money and pricing

Price and ledger amounts use integer SAR minor units. Partner prices are the final VAT-inclusive gross price, excluding service fees. The server resolves the price again when purchasing; a price check is not a reservation or a locked quote.

faceValue is a decimal string and faceValueCurrency identifies the original denomination. Both can be null when denomination metadata is unavailable. Do not infer them from the SAR price. PARTNER_PRICE and RETAIL_FALLBACK identify the resolved price source.

Pagination and dates

List endpoints use page starting at 1 and size from 1 to 100 (default 20). Results contain items and pagination with page, size, total, and totalPages. An empty list has totalPages: 0.

Timestamps use ISO 8601. Ledger from is inclusive and to is exclusive. Either bound may be used alone; with both, from must be earlier than to and the range must not exceed 366 days. Statement periods are fully elapsed calendar months in Asia/Riyadh; periodEndExclusive is the start of the next month.

Handle card credentials carefully

Order lists do not contain credentials. Purchase and detail responses expose them only after fulfillment completes. Finance, order, and statement responses carry Cache-Control: no-store. Deliver credentials only to their intended recipient and keep them out of analytics and logs.