Requests and responses

The base URL, request format, response envelope, request IDs, and how dates, money and IDs are written.

Base URL#

All endpoints live under one base URL, for both sandbox and production:

https://api-host.localoy.app/api/v1/open-network/v1

The v1 at the end of the path is the API version. Paths in this documentation are relative to the base URL — GET /ping means GET {BASE_URL}/ping.

Request format#

Send request bodies as JSON with Content-Type: application/json.
A body may be at most 1 MB. A larger body is refused with 413.
Field names are camelCase: externalId, priceCents, amountMinor.
Unknown fields are ignored.
Text fields are trimmed of surrounding whitespace before they are checked and stored.
Validation stops at the first invalid field, so fix errors one at a time.
If a query parameter is repeated, the last value is used.

Response envelope#

Every response is a JSON object with a success flag.

Success

{
  "success": true,
  "message": "Catalog item created",
  "data": { "…": "…" }
}

Reads return success and data.
Writes usually add a human-readable message.
DELETE /catalog/items/{externalId} returns no data.
The payment write endpoints add a top-level replayed flag next to data.

Error

{
  "success": false,
  "message": "No catalog item with externalId \"sku-9\"",
  "code": "open_network_item_not_found",
  "requestId": "3f0c9f8e-6a1d-4f5e-9b1a-2f1c0d9e7a41"
}

message is written for people. Do not parse it.
code is the stable, machine-readable reason. Branch on code, not on message. Some input validation errors carry only a message; see Errors.
details, when present, is an object with structured context for that error.

Request IDs#

Every response carries an X-Request-Id header. Error bodies repeat it as requestId.

If you send your own X-Request-Id header, Localoy uses it instead of generating one, so you can follow a call through your logs and ours. Include the request ID whenever you contact Localoy about a failed call.

Dates and times#

Timestamps are ISO 8601 strings in UTC with milliseconds:

Format

2026-09-26T08:15:30.123Z

Money#

Amounts are integers in minor units (poisha for BDT: 45000 is ৳450.00). Never send decimals.

Where	Amount field	Currency field
Catalogue items	`priceCents`	`currency` — an ISO 4217 code, `BDT` by default
Payment sessions	`amountMinor`	`currency` — always `BDT`
Booking webhooks	`totalTaka` — whole taka, not minor units	—

Identifiers#

Localoy's own IDs (id, payment session IDs, bookable IDs) are opaque strings. Store them as text and do not parse them.
Catalogue items are addressed by your externalId, not by Localoy's id.
Webhook event IDs start with evt_.

Every call is logged#

Every API call — including refused ones — is recorded with its status code and shown to you on the Partner Portal's Open Network → Activity page. The log is kept for 180 days.