API conventions

Base URL and versioning

All production requests start with:

https://omnipay.page/api/v1

The API version is part of the URL. Build endpoint paths from the base URL instead of repeating the complete URL throughout your code.

const omnipay = new URL("https://omnipay.page/api/v1/");
const depositsUrl = new URL("deposits", omnipay);

Request and response format

Request and response bodies use UTF-8 JSON. Send Content-Type: application/json whenever a request has a body.

Successful responses use:

Do not treat every 2xx response as having the same schema. Parse the response for the endpoint and status code you called.

Monetary values

Money is represented as a decimal string in BDT:

{
  "amount": "500.00"
}

Do not send JavaScript floating-point numbers. Keep amounts as strings or use a decimal-money library in your application.

Identifiers

merchant_id is your business identifier and idempotency key. Generate it before the API call and persist it with your order or payout.

The response id is OmniPay's resource identifier. Persist both:

{
  "id": "cm7deposit02",
  "merchant_id": "order-123"
}

Use the OmniPay id in status and verification endpoint paths. Use merchant_id to correlate the resource with your own records and webhook events.

Timestamps

Response timestamps are UTC date-time strings. H2H signature timestamps are whole Unix seconds and are valid within a five-minute clock-skew window.

Synchronize production hosts with NTP and generate the signature timestamp immediately before sending the request.

Request IDs

Every API response includes an X-Request-Id header. Capture it in structured logs and include it when contacting OmniPay support.

Do not log API keys, H2H signing secrets, complete Authorization headers, or unredacted payer data.

Forward compatibility

• Ignore unknown JSON response fields.
• Ignore webhook event types your integration does not handle.
• Treat an unknown next_action.type as non-actionable and fail closed.
• Build fulfillment logic around documented top-level status values.

Download the machine-readable OpenAPI 3.1 document for client generation, contract tests, or IDE tooling.

Read error and retry behavior →