OMPAY — API Integration Guide

This guide explains how you, as a merchant, integrate with the OMPAY payment gateway to create and manage payment transactions.

One API, one integration. You work with a single OMPAY API to create and manage payments — cards, digital wallets, refunds, reversals, and status look‑ups. OMPAY handles the acquiring banks, routing, and settlement for you; there is nothing else to call.

Stable API (v1.2.0). This API is a backward‑compatible contract. Existing endpoints, parameters, response fields, status values, and error codes will not change or be removed under /api/v1 — only new optional parameters, endpoints, and response fields may be added over time. v1.2.0 is fully compatible with v1.0.0/v1.1.0: it only adds the OMPAY Wallet endpoints (§3.4) and the Corporate Dashboard disbursement endpoints (§8) — nothing from earlier versions changed. Build against the documented fields and ignore any response fields you don't recognise so future additions never break your integration. The payment links endpoints (§10) and the settlement reports endpoints (§11) are later additions of the same kind. Any breaking change would ship as a new version (/api/v2), leaving /api/v1 untouched.

1. Base URL

OMPAY runs two environments. Point your integration at the sandbox while you build and test, then change this one value to go live — nothing else about the requests differs.

Every endpoint below is prefixed with /api/v1 — for example https://api.sandbox.truepay.ompay.om/api/v1/transactions/bank-hosted.

Your API key and secret are issued per environment: sandbox credentials do not work in production, and production credentials do not work in the sandbox.

2. Authentication

Every request authenticates with two headers — your API key and secret:

OMPAY-API-Key:    <your_api_key>
OMPAY-API-Secret: <your_api_secret>

You receive these from OMPAY when your merchant account is set up, and can view them any time in your OMPAY Merchant Portal (each merchant has a unique key/secret; the secret can be rotated).

Your account is identified by these two headers alone — there is no merchant_id (or any account id) to send. Every request is automatically scoped to the merchant that owns the API key, and results only ever include your own transactions. You never put an account identifier in a URL, query, or body.

⚠️ Keep your API secret server‑side. Never embed it in browser, mobile, or other client‑side code. Calls should originate from your backend.

Authentication errors

3. Transaction types

There are two ways to take a payment. Pick one per transaction:

Payment flows at a glance

flowchart LR
  subgraph MH["Merchant-hosted — you collect the card"]
    direction TB
    m1["Card entered on<br/>YOUR checkout"] --> m2["POST /transactions/merchant-hosted<br/>(card details or saved token)"]
    m2 --> m3{"3-D Secure /<br/>OTP required?"}
    m3 -->|"Yes"| m4["Redirect to<br/>OMPAY OTP page"] --> m5["OMPAY charges<br/>the bank"]
    m3 -->|"No (frictionless token)"| m5
  end
  subgraph BH["Bank-hosted — card never touches you"]
    direction TB
    b1["POST /transactions/bank-hosted<br/>(no card)"] --> b2["Redirect customer to<br/>OMPAY pay-page"] --> b3["Card entered on<br/>OMPAY's hosted page"]
    b3 --> b4{"3-D Secure /<br/>OTP required?"}
    b4 -->|"Yes"| b5["OTP on<br/>OMPAY page"] --> b6["OMPAY charges<br/>the bank"]
    b4 -->|"No"| b6
  end

The key difference is who collects the card: in *merchant‑hosted* it is entered on your checkout and sent to OMPAY; in *bank‑hosted* the customer is redirected to OMPAY's hosted page and the card never touches your servers. Either way the OTP page is OMPAY‑hosted, and whenever the customer is redirected you confirm the outcome with a server‑to‑server status inquiry (§3.9) — the redirect never carries the status.

Plus the management endpoints:

The customer stays on OMPAY pages — they never visit the bank's site. Whenever a step needs the cardholder (entering a card, or an OTP), the response gives you a OMPAY redirect_url. Send the customer there; OMPAY shows its own secure card / OTP page (collecting the OTP and submitting it to the bank via API) and, on completion, returns the customer to your return_url.

Each flow must be enabled for your merchant account. OMPAY Operations switches on the specific capabilities you're contracted for — Bank‑hosted, Merchant‑hosted (CVV+OTP / no‑CVV+OTP / no‑CVV no‑OTP), Apple Pay, Samsung Pay, and card tokenization (the vault — storing cards as tokens and charging a saved‑card token). Calling a flow that isn't enabled for you (or presenting a card BIN outside your enabled range) returns 402 MERCHANT_CAPABILITY_DISABLED — *"BIN range is not enabled for the merchant."* Ask OMPAY to enable the capability rather than retrying. In particular, if card tokenization is not enabled, POST /api/v1/tokens, GET/DELETE /api/v1/tokens/:token, and any pay‑by‑token request all return this error.

A live, interactive version of every endpoint below — with editable credentials and example bodies you can fire — is in the API Sandbox on this developer portal.

3.1 Merchant‑hosted payment

POST /api/v1/transactions/merchant-hosted

Send the card either as full details or as a saved token (one or the other, not both). The allowed authentication depends on which you send:

When 3‑D Secure is required you get back otp_required: true and a OMPAY redirect_url; otherwise you get the final result in one call.

sequenceDiagram
  autonumber
  participant C as Cardholder
  participant M as Your server / checkout
  participant O as OMPAY
  participant B as Bank / acquirer
  C->>M: Enters card on YOUR page
  M->>O: POST /transactions/merchant-hosted (card or token + browser)
  alt Token — frictionless (no OTP)
    O->>B: Authorize + capture
    B-->>O: Result
    O-->>M: 200 final status (SUCCESSFUL / FAILED)
  else Full card, or token needing 3-D Secure
    O-->>M: 200 otp_required + redirect_url (OMPAY OTP page)
    M-->>C: Redirect to redirect_url
    C->>O: Enters OTP on OMPAY's page
    O->>B: Submit OTP + capture
    B-->>O: Result
    O-->>C: 302 back to your return_url (ids only, no status)
    M->>O: POST /transactions/inquiry
    O-->>M: Authoritative status
  end

Request body

3‑D Secure 2 browser data (browser)

Card payments are authenticated with 3‑D Secure 2, which requires details about the cardholder's browser. Because *you* host the checkout, the cardholder is on your page — TruePay never sees their browser and cannot collect this for you. So you collect it on your checkout page and send it in the browser object. Omitting it (or sending your own server's values instead of the cardholder's) can cause the payment to fail 3‑D Secure authentication.

All values are sent as strings (or booleans for the two …Enabled fields). For bank‑hosted payments (§3.2) you do not send this — OMPAY's hosted page collects it from the cardholder directly.

Full card (CVV + 3‑D Secure):

curl -X POST https://api.sandbox.truepay.ompay.om/api/v1/transactions/merchant-hosted \
  -H "OMPAY-API-Key: $OMPAY_API_KEY" -H "OMPAY-API-Secret: $OMPAY_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 12.500, "currency": "OMR", "return_url": "https://shop.example/thanks",
    "card": { "number": "4111111111111111", "exp_month": "12", "exp_year": "2028", "holder_name": "Ada Lovelace", "cvv": "123" },
    "browser": {
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0 Safari/537.36",
      "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
      "language": "en-US", "ip": "94.200.10.5",
      "colorDepth": "24", "screenWidth": "1920", "screenHeight": "1080", "tz": "-240",
      "javaEnabled": false, "javascriptEnabled": true
    }
  }'

Pay with a token (same endpoint, no CVV):

curl -X POST https://api.sandbox.truepay.ompay.om/api/v1/transactions/merchant-hosted \
  -H "OMPAY-API-Key: $OMPAY_API_KEY" -H "OMPAY-API-Secret: $OMPAY_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 9.250, "currency": "OMR", "return_url": "https://shop.example/thanks", "token": "tok_…" }'

3‑D Secure required — 200:

{ "success": true, "data": { "transaction_id": "…", "status": "PROCESSING", "otp_required": true, "redirect_url": "https://api.sandbox.truepay.ompay.om/api/v1/transactions/…/otp-page" } }

Send the customer to redirect_url; on completion they return to return_url.

Frictionless final result (token, no OTP) — 201/200:

{ "success": true, "data": { "transaction_id": "…", "status": "SUCCESSFUL", "otp_required": false, "provider_transaction_id": "…" } }

A declined card returns HTTP 200 with status: "FAILED" and an error_message (e.g. an IPAYxxxxxxx code). Missing CVV on a full card → 400 CVV_REQUIRED.

3.2 Bank‑hosted payment (redirect / 3‑D Secure)

POST /api/v1/transactions/bank-hosted

The customer enters their card and OTP on the bank's hosted page, then returns to your return_url. No card data touches your servers.

sequenceDiagram
  autonumber
  participant C as Cardholder
  participant M as Your server
  participant O as OMPAY (hosted pages)
  participant B as Bank / acquirer
  M->>O: POST /transactions/bank-hosted (amount, return_url — no card)
  O-->>M: 200 redirect_url (OMPAY pay-page)
  M-->>C: Redirect to redirect_url
  C->>O: Enters card, then OTP, on OMPAY's hosted pages
  O->>B: Authorize / submit OTP / capture (server-to-server)
  B-->>O: Result
  O-->>C: 302 back to your return_url (transaction_id, reference_number — no status)
  M->>O: POST /transactions/inquiry
  O-->>M: Authoritative status

curl -X POST https://api.sandbox.truepay.ompay.om/api/v1/transactions/bank-hosted \
  -H "OMPAY-API-Key: $OMPAY_API_KEY" \
  -H "OMPAY-API-Secret: $OMPAY_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 15.750, "currency": "OMR", "return_url": "https://shop.example/thanks", "reference_number": "ORDER-1002" }'

Response — 200 (note: redirect_url is a OMPAY URL):

{ "success": true, "data": { "transaction_id": "…", "status": "PROCESSING", "redirect_url": "https://api.sandbox.truepay.ompay.om/api/v1/transactions/…/pay-page" } }

Flow:

1. Send the cardholder's browser to redirect_url (a OMPAY URL).
2. OMPAY shows its own card-entry page, then its own OTP page; the OTP is

submitted to the bank via API (the customer never visits the bank).

1. On completion OMPAY 302s the customer back to your return_url with

?transaction_id=…&reference_number=… — and nothing else.

⚠️ The redirect does not carry the payment status. A status sitting in a browser URL is visible to (and forgeable by) the customer, so it must never be trusted. When the customer lands back on your return_url, call POST /api/v1/transactions/inquiry (§3.9) with the transaction_id (or reference_number) to get the authoritative outcome server‑to‑server before you fulfil the order. Don't rely on the customer returning at all — also reconcile from your backend (inquiry / reports), since the browser may never come back.

3.3 Wallet payment (Apple Pay / Samsung Pay)

POST /api/v1/transactions/wallet-pay

Merchant-hosted direct purchase for Apple Pay / Samsung Pay, routed to the wallet payment provider. There's no redirect and no OTP — the wallet's own device attestation (the cryptogram) is the 3-D Secure step.

The same endpoint serves your iOS app and your own website — an Apple Pay JS token has the same shape PassKit produces, so there is nothing different to send.

There are two ways to hand us an Apple Pay payment. Prefer the first.

A — send the encrypted token, we decrypt it (recommended). Put Apple's token object in wallet.payment_token exactly as PassKit or Apple Pay JS gave it to you. We decrypt it with the Payment Processing certificate you enrolled through the merchant portal, so no decryption code, key handling or cardholder data touches your servers:

{
  "amount": 12.500, "currency": "OMR", "reference_number": "ORDER-1003",
  "wallet": {
    "type": "APPLE_PAY",
    "payment_token": {
      "paymentData": { "data": "…", "signature": "…", "version": "EC_v1",
                       "header": { "publicKeyHash": "…", "ephemeralPublicKey": "…", "transactionId": "…" } },
      "paymentMethod": { "displayName": "Visa 1234", "network": "Visa", "type": "debit" },
      "transactionIdentifier": "…"
    }
  }
}

Don't unwrap it and don't send only paymentData — send the whole token object. Set up the certificate first: merchant portal → Apple Pay (we generate the key and CSR, you enroll it with Apple and upload the issued .cer; the private key never leaves us).

Samsung Pay works the same way: send Samsung's encrypted paymentCredential in wallet.payment_token and we decrypt it with the key we generated for your Samsung Pay service — see §3.3.2.

If you enrolled a separate Payment Processing certificate for your website, add it in the portal under *Additional Payment Processing certificates*. Each token names the certificate it was encrypted to by its public key hash, so your app's and your site's certificates both keep working. Skip this if your site reuses the app's certificate.

B — send decrypted fields. If you already decrypt the wallet token yourself, send the fields instead. Never log the cryptogram or DPAN. wallet.type is APPLE_PAY or SAMSUNG_PAY:

{
  "amount": 12.500, "currency": "OMR", "reference_number": "ORDER-1003",
  "wallet": {
    "type": "APPLE_PAY",
    "dpan": "4111111111111111", "exp_date": "2812",
    "device_manufacturer_id": "040010030273", "payment_data_type": "3DSecure",
    "cryptogram": "<base64 onlinePaymentCryptogram from PassKit>", "eci_indicator": "05",
    "display_name": "Your Store", "network": "visa"
  }
}

{
  "amount": 12.500, "currency": "OMR", "reference_number": "ORDER-1004",
  "wallet": {
    "type": "SAMSUNG_PAY",
    "token_pan": "4111111111111111", "token_pan_expiration": "2812", "utc": "20260701120000",
    "cryptogram": "<base64 cryptogram from the Samsung Pay SDK>", "eci_indicator": "07",
    "method": "3DS", "recurring_payment": false, "card_brand": "VISA", "card_last4": "1111"
  }
}

Response — 201 only when the provider result is CAPTURED; otherwise 200 with status: "FAILED":

{ "success": true, "data": { "transaction_id": "…", "status": "SUCCESSFUL", "provider_transaction_id": "…", "error_message": null } }

Refund (§3.7) and reverse (§3.8) both work on a completed wallet payment exactly like a card payment — same endpoints, same request shape.

3.3.1 Apple Pay on your own website

POST /api/v1/transactions/apple-pay/validate-merchant

▶ Download the working sample — everything below, runnable. Four files, no dependencies, Node 18+: a checkout page, the Apple Pay JS, and the two backend endpoints. Browse the source first if you prefer. There is also a native iOS sample for the in-app flow.

Apple Pay in a browser needs one step that in-app Apple Pay does not: before the payment sheet will release a token, your page must call completeMerchantValidation() with a session obtained from Apple over mutual TLS. Until that happens onpaymentauthorized never fires and there is no token to send us — if your site shows the sheet and then closes it with nothing, this is almost always why.

This endpoint performs that call for you, using your Apple merchant identifier and your Merchant Identity certificate. The certificate stays with us; nothing is downloaded and no key material goes near the browser.

Before you start

• Your own Apple Pay merchant identifier, with your domain registered and verified

against it in your Apple Developer account. Apple enforces this — we don't check domains, and we can't register one for you.

• A Merchant Identity certificate set up in the merchant portal (*Apple Pay →

Merchant Identity*): generate the CSR, enroll it with Apple, upload the .cer.

• A Payment Processing certificate, as in §3.3 — the same one as your app, or a

separate one added under *Additional Payment Processing certificates*.

Step 1 — validate the merchant. Call this from your backend, never the browser: it is authenticated with your API key.

POST /api/v1/transactions/apple-pay/validate-merchant
Authorization: <your API key>

{
  "validationURL": "https://apple-pay-gateway.apple.com/paymentservices/startSession",
  "domain": "shop.example.om"
}

The response is Apple's merchant session, verbatim — an opaque, short-lived object. Pass it to completeMerchantValidation() unchanged; don't reshape or cache it.

session.onvalidatemerchant = async (event) => {
  const r = await fetch('/your-backend/apple-pay/validate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ validationURL: event.validationURL }),
  });
  session.completeMerchantValidation(await r.json());
};

Step 2 — take the payment. Identical to your app. onpaymentauthorized gives you event.payment.token; send it to your backend and post it to wallet-pay (§3.3):

session.onpaymentauthorized = async (event) => {
  const r = await fetch('/your-backend/apple-pay/pay', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ token: event.payment.token }),
  });
  const result = await r.json();
  session.completePayment(result.success
    ? ApplePaySession.STATUS_SUCCESS
    : ApplePaySession.STATUS_FAILURE);
};

Then confirm the outcome server-to-server with a status inquiry (§3.9), as with any flow.

Don't want to build this? OMPAY's bank-hosted pay-page (§3.2) already has Apple Pay in the browser, on OMPAY's own domain — you redirect and we handle validation and the sheet. No certificates, no merchant identifier, no domain registration. Ask OMPAY to enable bank-hosted checkout.

3.3.2 Samsung Pay on your app or website

Samsung Pay works exactly like Apple Pay option A above: your app or website collects the payment with Samsung's SDK, and you send us Samsung's encrypted paymentCredential unchanged. We decrypt it with a key we generated for your Samsung Pay service and charge it. No decryption code, key or card data touches your servers.

One-time setup — merchant portal → Samsung Pay (shown when TruePay has enabled Samsung Pay for your account):

1. On the Samsung Pay portal, create your service

(Web Checkout for a website, in-app for an Android app) and copy its Service ID into the portal. For the sheet in your own page on Galaxy phones, also (or instead) create a W3C Mobile Web Payment service — see below.

1. Click Generate key & CSR and Download CSR. We keep the private key; it never

leaves us.

1. On the Samsung Pay portal, upload that CSR to your service and choose RSA-OAEP

(or RSA1_5) with AES-GCM. For Web Checkout, also register your website's domain. Samsung issues no certificate: it encrypts every payment credential to the public key in the CSR, so there is nothing to upload back.

1. Click Enable Samsung Pay. A Web Checkout / in-app Service ID or a W3C Service ID,

with the key, completes the setup.

The portal shows your key's SHA-256 public-key fingerprint, so you can confirm the CSR registered with Samsung is the one we hold.

On your website (Web Checkout). Show the button only when isReadyToPay says so, open the sheet with the same amount and currency you will send us, send the credential to your server, then tell Samsung the outcome:

<script src="https://img.mpay.samsung.com/gsmpi/sdk/samsungpay_web_sdk.js"></script>
<script>
  const client = new SamsungPay.PaymentClient({ environment: 'STAGE' });   // 'PRODUCTION' when live
  const methods = { version: '2', serviceId: 'YOUR_SERVICE_ID', protocol: 'PROTOCOL_3DS',
                    allowedBrands: ['visa', 'mastercard'] };
  client.isReadyToPay(methods).then((r) => { if (r.result) showSamsungPayButton(); });

  function onSamsungPayClick() {
    client.loadPaymentSheet(methods, {
      orderNumber: 'ORDER-1005',
      merchant: { name: 'Your Store', url: 'yourstore.om', id: 'your-ref', countryCode: 'OM' },
      amount: { option: 'FORMAT_TOTAL_PRICE_ONLY', currency: 'OMR', total: 12.500 },
    }).then((paymentCredential) =>
      // Your server calls TruePay /wallet-pay with this object, unchanged (below).
      fetch('/your-server/pay', { method: 'POST', headers: { 'Content-Type': 'application/json' },
                                  body: JSON.stringify({ paymentCredential }) })
        .then((r) => r.json())
        .then((result) => client.notify({ status: result.success ? 'CHARGED' : 'ERRED', provider: 'TruePay' })));
  }
</script>

In the page on Galaxy phones (W3C). Web Checkout sends a phone to Samsung's checkout page. Samsung's W3C Mobile Web Payment service instead opens Samsung Wallet's sheet over your own page on a Galaxy phone (Samsung Internet or Chrome, with Samsung Wallet) — the customer never leaves your checkout. Use it where it is available and keep Web Checkout as the fallback everywhere else.

1. On the Samsung Pay portal, create a W3C Mobile Web Payment service:

• Service country: Oman (the country of your customers' phones — Samsung refuses a

phone from a country the service does not list).

• Payment gateway: TruePay's CSR is signed with our own key, not a gateway's — if

TruePay is not in the list, choose NONE.

• CSR: upload the same CSR you downloaded from the merchant portal (so our key

decrypts it too), in network token mode.

• Service domain: the exact host your checkout page runs on. If checkout is on a

subdomain (pay.yourstore.om), register that subdomain — not yourstore.om. Add each host you check out on.

1. Testing. A new service is in Debugging: only the Samsung accounts listed under its

test accounts (signed in to Samsung Wallet on the test phone) can pay, until its debug end date.

1. Going live. Request release; Samsung verifies the service and sets it to Approved.

Until then Samsung Wallet refuses every other customer. Use the Service ID of the released service.

1. Enter its W3C Service ID and the merchant name exactly as registered (same spelling,

case and spaces) in merchant portal → Samsung Pay → *In the page on Galaxy phones (W3C)*. The portal shows the code below with both filled in.

1. If your checkout page sends a Content-Security-Policy, its connect-src **must list

https://spay.samsung.com**. Browsers check a payment method against connect-src; if it is missing, new PaymentRequest() throws *"payment method identifier violates Content Security Policy"* and the sheet never opens.

<script>
  function samsungPayRequest() {                 // a PaymentRequest can be shown once: make a new one each time
    return new PaymentRequest(
      [{ supportedMethods: 'https://spay.samsung.com',
         data: { version: '1', productId: 'YOUR_W3C_SERVICE_ID', merchantName: 'Name exactly as registered',
                 allowedCardNetworks: ['visa', 'mastercard'], orderNumber: 'ORDER-1005',
                 paymentProtocol: 'PROTOCOL_3DS' } }],
      { total: { label: 'Your Store', amount: { currency: 'OMR', value: '12.500' } } });
  }
  samsungPayRequest().canMakePayment().then((ok) => { if (ok) showSamsungPayButton(); /* else Web Checkout */ });

  async function onSamsungPayClick() {
    const response = await samsungPayRequest().show();          // Samsung Wallet's sheet, over this page
    const r = await fetch('/your-server/pay', { method: 'POST', headers: { 'Content-Type': 'application/json' },
                                                body: JSON.stringify({ samsungPay: response.details }) });
    const result = await r.json();                              // your server called TruePay /wallet-pay
    await response.complete(result.success ? 'success' : 'fail');
  }
</script>

Send response.details to us unchanged as wallet.payment_token (the whole PaymentResponse is accepted too). It carries the same encrypted credential in a different shape:

{
  "amount": 12.500, "currency": "OMR", "reference_number": "ORDER-1005",
  "wallet": {
    "type": "SAMSUNG_PAY",
    "payment_token": {
      "paymentCredential": { "type": "S", "version": "100", "data": "eyJhbGciOiJSU0EtT0FFUCIs…" },
      "paymentInfo": { "card_last4digits": "1234", "cardBrand": "VI" }
    }
  }
}

In your Android app. Samsung's in-app SDK returns the same paymentCredential (3DS type) when payment succeeds on the device — send it to your server and on to us unchanged.

The request — from your server, with your API key:

{
  "amount": 12.500, "currency": "OMR", "reference_number": "ORDER-1005",
  "wallet": {
    "type": "SAMSUNG_PAY",
    "payment_token": {
      "method": "3DS", "recurring_payment": false,
      "card_brand": "VI", "card_last4digits": "1234",
      "3DS": { "type": "S", "version": "100", "data": "eyJhbGciOiJSU0EtT0FFUCIs…" }
    }
  }
}

payment_token may also be the credential as a JSON string, and payment_credential is accepted as another name for it. Send the whole object — not just 3DS.data. The amount and currency must be the ones the customer authorised in the sheet: if the credential carries a different amount or currency the payment is refused and recorded as FAILED. (If you already decrypt Samsung's credential yourself, option B in §3.3 still works.)

What can go wrong

The success response, refund (§3.7) and reverse (§3.8) are the same as for Apple Pay.

Testing without a Samsung device. On test environments, merchant portal → Samsung Pay → Simulation makes /wallet-pay settle Samsung Pay requests as a successful capture or a decline of your choice, without decrypting or charging anything. Simulation is never available in production.

3.4 OMPAY Wallet — pay by phone + OTP

The customer pays from their OMPAY Wallet (a stored‑value account) by confirming a one‑time password sent to their mobile — there is no card. Pick the flow that matches your contracted capability.

Merchant‑hosted — you collect the phone and OTP in your own UI, in two calls.

Step 1 — send the OTP. POST /api/v1/transactions/ompay-wallet/send-otp

OMPAY generates a numeric OTP and SMSes it to the customer. The transaction stays PENDING until you submit the OTP. If the customer never completes it, OMPAY auto‑expires the transaction to FAILED after a configured timeout — start a new one.

{ "success": true, "data": { "transaction_id": "…", "reference_number": "…", "status": "PENDING", "otp_required": true } }

Step 2 — verify the OTP and charge. POST /api/v1/transactions/:id/ompay-wallet/verify

On the correct OTP the wallet is debited and the transaction becomes SUCCESSFUL (201):

{ "success": true, "data": { "transaction_id": "…", "reference_number": "…", "status": "SUCCESSFUL", "provider_transaction_id": "…", "error_message": null, "provider_error": null } }

A wrong OTP with attempts remaining returns 400 with otp_required: true — let the customer retry the same transaction. Too many wrong attempts, an expired OTP, or an expired transaction returns a terminal error with the transaction FAILED.

{ "success": false, "error": "OTP_INVALID", "message": "Incorrect OTP. Please try again.", "otp_required": true }

Example

# 1) send the OTP
curl -X POST https://api.sandbox.truepay.ompay.om/api/v1/transactions/ompay-wallet/send-otp \
  -H "OMPAY-API-Key: $OMPAY_API_KEY" -H "OMPAY-API-Secret: $OMPAY_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 12.500, "phone": "+96892303072", "reference_number": "ORD-1001" }'

# 2) verify the OTP the customer received (:id from step 1's transaction_id)
curl -X POST https://api.sandbox.truepay.ompay.om/api/v1/transactions/<id>/ompay-wallet/verify \
  -H "OMPAY-API-Key: $OMPAY_API_KEY" -H "OMPAY-API-Secret: $OMPAY_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "otp": "123456" }'

Bank‑hosted — OMPAY collects the phone and OTP on its own pages, so you do not call the two endpoints above. Start a normal bank‑hosted payment (POST /api/v1/transactions/bank-hosted, §3.2); if OMPAY Wallet bank‑hosted is enabled for you, an OMPAY Wallet option appears on the OMPAY hosted checkout page, and choosing it runs the phone + OTP flow on OMPAY's pages before returning the customer to your return_url. Confirm the final status from your backend with /inquiry (§3.9), exactly as for bank‑hosted cards.

Refund (§3.7) / reverse (§3.8) work on a completed OMPAY Wallet payment exactly like a card payment — same endpoints, same request shape — crediting the amount back to the customer's wallet.

3.5 List transactions

GET /api/v1/transactions

Returns your transactions, newest first. With no parameters it returns just your last 10 — page or filter to pull more, so a busy account never ships a huge payload by accident. Use page/limit to paginate and date_from/date_to to bound the window; the pagination block tells you how many pages there are.

Query parameters

To fetch one specific transaction, use GET /api/v1/transactions/{id} (§3.6) instead — this list endpoint is only for browsing/paging many.

# most recent 10 (default)
curl -sG https://api.sandbox.truepay.ompay.om/api/v1/transactions \
  -H "OMPAY-API-Key: $OMPAY_API_KEY" -H "OMPAY-API-Secret: $OMPAY_API_SECRET"

# page 2, 25 per page, only July, only successful
curl -sG https://api.sandbox.truepay.ompay.om/api/v1/transactions \
  -H "OMPAY-API-Key: $OMPAY_API_KEY" -H "OMPAY-API-Secret: $OMPAY_API_SECRET" \
  --data-urlencode "page=2" --data-urlencode "limit=25" \
  --data-urlencode "date_from=2026-07-01" --data-urlencode "date_to=2026-07-31" \
  --data-urlencode "status=SUCCESSFUL"

{
  "success": true,
  "data": [ { "id": "…", "status": "SUCCESSFUL", "amount": "12.500", "currency": "OMR" } ],
  "pagination": { "total": 2, "page": 1, "limit": 10, "pages": 1 }
}

3.6 Get a transaction

GET /api/v1/transactions/:id

Returns one transaction plus its logs (status‑change history / audit trail). You may only retrieve your own transactions (others return 403).

{
  "success": true,
  "data": {
    "id": "15a09acb-…",
    "status": "SUCCESSFUL",
    "amount": "12.500",
    "currency": "OMR",
    "logs": [
      { "status": "PENDING", "message": "Transaction created.", "created_at": "…" },
      { "status": "PROCESSING", "message": "Submitted to the payment provider.", "created_at": "…" },
      { "status": "SUCCESSFUL", "message": "Provider approved the request.", "created_at": "…" }
    ]
  }
}

3.7 Refund a transaction

POST /api/v1/transactions/:id/refund

Refunds a SUCCESSFUL transaction via the bank — full or partial, on any day. This creates a new, separate transaction linked to the original via original_transaction_id (transaction_type: "REFUND") — the original transaction is never modified; it stays SUCCESSFUL forever. Refunds are capped at the amount not already refunded (cumulative across multiple partial refunds); you can call this repeatedly until the full amount is refunded.

Capability: the Refund API is enabled for your account when any Merchant‑hosted flow is enabled (or when refund is granted to you explicitly). Otherwise it returns 402 MERCHANT_CAPABILITY_DISABLED.

Request body (optional — omit amount to refund whatever remains):

{ "amount": 5.000 }

Response — 200 on success, 422 if the provider declines:

{
  "success": true,
  "data": {
    "refunded": true,
    "original_transaction_id": "…",
    "refund_transaction_id": "…",
    "refund_status": "SUCCESSFUL",
    "refund_amount": "5.000",
    "rrn": "381064972275",
    "error_message": null,
    "refundable_remaining": "7.750"
  }
}

A 400 LIMIT_EXCEEDED is returned if amount exceeds refundable_remaining. Fetch GET /api/v1/transactions/:id on the *original* transaction to see the cumulative refund_summary (amount, refunded, remaining, and every linked refund) and GET /api/v1/transactions/:id on the refund itself to see original_transaction_id.

3.8 Reverse (void) a transaction

POST /api/v1/transactions/:id/reverse

Some banks reject a refund on the purchase date and require a void instead — this endpoint voids the full amount of a SUCCESSFUL transaction, and is only accepted on the same calendar day as the purchase. From the next day onward, use /refund instead. Like a refund, this creates a new, separate transaction (transaction_type: "REVERSAL") linked via original_transaction_id — the original is never modified. Optional body:

Capability: the Reversal API is enabled together with the Refund API — when any Merchant‑hosted flow is enabled (or reversal is granted explicitly). Otherwise it returns 402 MERCHANT_CAPABILITY_DISABLED.

{ "reason": "CUSTOMER_REQUEST" }

Response — 200 on success, 422 if the provider declines (e.g. already reversed, or it's no longer the purchase date):

{
  "success": true,
  "data": {
    "reversed": true,
    "original_transaction_id": "…",
    "reversal_transaction_id": "…",
    "reversal_status": "SUCCESSFUL",
    "rrn": "TP178288751588598",
    "error_message": null
  }
}

A 400 REVERSAL_NOT_ALLOWED is returned if it's no longer the purchase date, or the transaction was already refunded/reversed.

3.9 Status inquiry

POST /api/v1/transactions/inquiry

Look up the latest status of one of your transactions by either its OMPAY transaction_id or the reference_number you supplied when creating it (send exactly one). Where a live inquiry is available, OMPAY refreshes the status from the provider first, updates its own record, and returns the current result — so this is the authoritative way to resolve a transaction that was still PENDING/PROCESSING when the customer left.

Request body (one of the two identifiers):

{ "transaction_id": "6965adeb-f21d-4f07-bc79-16bf4bf4ad0a" }

{ "reference_number": "ORDER-10506" }

Response — 200:

{
  "success": true,
  "data": {
    "transaction_id": "6965adeb-f21d-4f07-bc79-16bf4bf4ad0a",
    "reference_number": "ORDER-10506",
    "status": "SUCCESSFUL",
    "amount": 7.5,
    "currency": "OMR",
    "bin_group": "Visa Cards",
    "rrn": "000123456789",
    "provider_transaction_id": "TP178288751588598",
    "payment_id": "9900112233",
    "track_id": "TP178288751588598",
    "error_message": null,
    "token": null,
    "saved_card": null
  }
}

404 TRANSACTION_NOT_FOUND if neither identifier matches one of your transactions; 400 VALIDATION_ERROR if you send neither.

FAILED with outcome_unconfirmed: true

A payment the bank never answered — neither captured nor declined — is closed as FAILED about six minutes after it was last sent to the bank, so nothing stays open for ever. That FAILED is OMPAY's decision, not the bank's answer, and the response says so:

{ "status": "FAILED", "outcome_unconfirmed": true,
  "error_message": "Payment could not be confirmed with the bank within 6 minutes and has been closed as unsuccessful. If the customer was charged, OMPAY will review it with the bank and either confirm the payment or return the money." }

• Never charge the customer again on it automatically — they may already have been charged.
• A reported status is never changed by itself. If the bank later reports the payment as

captured, OMPAY reviews it and either returns the money to the customer (the payment stays FAILED) or confirms the capture — only then does it become SUCCESSFUL, and it is settled to you in the next settlement run.

• outcome_unconfirmed disappears when OMPAY has settled the question (money returned). It is

absent on an ordinary decline. The same field is on GET /api/v1/transactions/{id}.

Bank Hosted — Forced Saved Cards

If your account is enabled for Bank Hosted – Forced Saved Cards (a variant of the bank‑hosted flow), every successful bank‑hosted payment also tokenizes the card. There's nothing extra to send on /bank-hosted; once the transaction reaches SUCCESSFUL, call /inquiry and the response carries the saved‑card token so you can charge it again later via merchant‑hosted token pay:

{
  "status": "SUCCESSFUL",
  "token": "tok_a1b2c3d4e5f6",
  "saved_card": { "token": "tok_a1b2c3d4e5f6", "masked_pan": "464156******3343", "brand": "VISA" }
}

token/saved_card are null for any non‑SUCCESSFUL transaction and for ordinary (non‑forced‑saved) flows.

3.10 Splitting a payment across your settlement accounts

If OMPAY has set up more than one settlement bank account for you, every payment is settled to your primary account by default, in the proportions configured for you. You can override that for an individual payment by sending an optional split on /merchant-hosted or /bank-hosted.

split is optional and additive. If you don't send it, nothing about your integration changes.

Your accounts and their identifiers are listed in the merchant portal under Settlements. An identifier looks like sba_4f1c… and is stable — quote it exactly.

curl -X POST https://api.sandbox.truepay.ompay.om/api/v1/transactions/bank-hosted \
  -H "OMPAY-API-Key: $OMPAY_API_KEY" -H "OMPAY-API-Secret: $OMPAY_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.000,
    "currency": "OMR",
    "return_url": "https://your-shop.example/checkout/return",
    "split": [
      { "settlement_bank_identifier": "sba_4f1c9a2b7e8d1035a6c4b2e9f7d3a501", "percent": 30 }
    ]
  }'

Here 30.000 is settled to that account and the remaining 70.000 to your primary account.

Rules

• Anything you don't allocate goes to your primary account. You never have to account for the

whole payment.

• The parts cannot exceed the whole. A split totalling more than the payment is rejected with

400 INVALID_SPLIT, and nothing is charged.

• At most 10 accounts per payment, each named once.
• An identifier that isn't one of yours is rejected with 400 UNKNOWN_SETTLEMENT_ACCOUNT — it is

never resolved against another merchant's accounts.

• A refund or reversal comes back out of the same accounts the original payment went into. You

don't send split on a refund; it inherits the original's.

What you are actually paid. A split says where this payment's money belongs. What reaches your accounts is a *settlement*, which covers many payments and is net of fees, refunds and any balance carried from an earlier period — so the figures rarely match a single payment exactly. OMPAY divides what is payable in the proportions you asked for. Which account absorbs the difference is a setting on your account: either your primary takes it, or every account is scaled by the same factor. Your account manager can tell you which is configured, and both are visible to OMPAY on your settlement statement.

4. Transaction lifecycle

Every transaction — a payment, a refund, or a reversal — goes through the same three-state lifecycle:

PENDING ──▶ PROCESSING ──▶ SUCCESSFUL
                   │
                   └────────▶ FAILED

A refund or reversal is its own transaction with its own lifecycle above — it is not a status the original payment transitions into. A SUCCESSFUL payment that has been fully refunded stays status: "SUCCESSFUL" forever; check its refund_summary (see §3.7) to see whether — and how much — it's been refunded.

5. Error responses

Every error shares this shape — check success: false and branch on the machine‑readable error code (the codes below are part of the frozen /api/v1 contract and will not change):

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Request validation failed.",
  "details": [ { "field": "amount", "message": "amount must be a positive number greater than zero." } ]
}

message is human‑readable (and may be genericised in production for 5xx); details is present only on field validation errors; requestId is included when request tracing is enabled.

5.1 Common errors (any authenticated endpoint)

These can be returned by any endpoint below, so handle them once in your HTTP client:

5.2 Per‑endpoint errors

Success codes are shown for context; a declined payment/refund is a normal response, not an HTTP error (see the note under each). Every table also inherits the §5.1 common errors.

POST /api/v1/transactions/merchant-hosted

POST /api/v1/transactions/bank-hosted (alias POST /api/v1/transactions/hosted)

POST /api/v1/transactions/wallet-pay

POST /api/v1/transactions/apple-pay/validate-merchant — Apple Pay on your own website (§3.3.1)

POST /api/v1/transactions/inquiry

POST /api/v1/transactions/:id/otp — submit the OTP for a merchant‑hosted transaction

POST /api/v1/transactions/:id/refund *(omit amount for a full refund)*

POST /api/v1/transactions/:id/reverse — same‑day void of a SUCCESSFUL transaction

GET /api/v1/transactions (list) · GET /api/v1/transactions/:id (get)

POST /api/v1/tokens (tokenize a card)

GET /api/v1/tokens/:token (masked metadata)

DELETE /api/v1/tokens/:token (revoke)

Shared tokens (merchant groups)

If your business trades under several merchant accounts with OMPAY — a main account and one or more sub-merchants — OMPAY can switch on token sharing for the group. Ask your account manager; it is off unless you request it.

With it on, every merchant in the group can use every other member's saved cards, so a customer who saved their card with one of your brands does not have to enter it again at another:

• Reading a shared token (GET /api/v1/tokens/:token) works, and the response carries

"shared_from_group": true so you can tell it was saved by a sibling account.

• Paying with a shared token works exactly as with your own. The payment is booked to

whichever merchant account made it, not to the one that saved the card.

• Revoking is deliberately narrower: only the merchant that saved the card, or your group's

main account, can revoke it. A sibling attempting it gets 403 TOKEN_NOT_YOURS. Ask the main account to revoke on a cardholder's behalf.

• Legacy tokens carried over from the old gateway are shared the same way. They are charged

against the acquiring account of the merchant that owns them, because that is the only account the token exists in.

• Each merchant still needs Card Tokenization enabled in its own right to use tokens at all.

Nothing about ownership changes: a token always belongs to the merchant that created it, so if sharing is switched off later, every token simply answers to its owner again.

6. Sandbox / test behaviour

• POST /api/v1/transactions (create a payment with no card/token) is a

simple, deterministic smoke test for wiring up auth and reading back a status: any amount whose value ends in 00 (e.g. 100, 200, 1500.00 → "1500") is declined (FAILED); any other amount (e.g. 12.500, 99.900) succeeds (SUCCESSFUL). It requires a merchant‑hosted capability, so an account without one gets 402 MERCHANT_CAPABILITY_DISABLED. Use it to exercise create → list → status; to test refunds and reversals, create a real card payment with merchant‑hosted (§3.1) or bank‑hosted (§3.2) first — those are the transactions §3.7/§3.8 act on.

• **Merchant‑hosted (§3.1) and bank‑hosted (§3.2) payments run against the live

bank integration** — the result reflects what the bank actually returns for the card/amount you send, and these ARE the transactions you refund/reverse in §3.7/§3.8.

• Routing is automatic — you never send a payment method, bank, or provider,

and the acquiring bank is never exposed to you. OMPAY routes the card internally from its BIN. The transaction instead carries neutral, provider‑agnostic fields: the bin_group (e.g. "Local Debit Cards"), the payment_instrument card type (e.g. "Debit Card" / "Credit Card"), and reconciliation identifiers (rrn, provider_transaction_id, payment_id, track_id). (Bank‑hosted redirects to the 3‑D Secure page, since the PAN isn't known until the customer enters it there.)

Test cards

Use these cards in the sandbox to run card payments end‑to‑end. Sandbox only — they move no real money.

With OTP (3‑D Secure) — completes through the OTP step:

Without OTP — completes without a 3‑D Secure / OTP step:

7. Quick start

1. Get your API key and secret from your OMPAY Merchant Portal — these identify your account; there is no merchant id to send.
2. Try the call in §3.1 with curl.
3. Or fire any endpoint live — with editable credentials and ready‑to‑send example requests — from the API Sandbox on this developer portal.

Copy‑paste Node.js and Python examples are below.

Node.js (built‑in fetch, Node 18+)

// Bank-hosted: get a redirect_url to send the cardholder to.
const res = await fetch('https://api.sandbox.truepay.ompay.om/api/v1/transactions/bank-hosted', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'OMPAY-API-Key': process.env.OMPAY_API_KEY,
    'OMPAY-API-Secret': process.env.OMPAY_API_SECRET,
  },
  body: JSON.stringify({
    amount: 12.5, currency: 'OMR',
    return_url: 'https://shop.example/thanks',
    reference_number: 'ORDER-1001',
  }),
});
const { data } = await res.json();
console.log(data.status, data.redirect_url); // redirect the customer here

Python (requests)

import os, requests
r = requests.post("https://api.sandbox.truepay.ompay.om/api/v1/transactions/bank-hosted",
    headers={"OMPAY-API-Key": os.environ["OMPAY_API_KEY"],
             "OMPAY-API-Secret": os.environ["OMPAY_API_SECRET"]},
    json={"amount": 12.5, "currency": "OMR",
          "return_url": "https://shop.example/thanks",
          "reference_number": "ORDER-1001"})
print(r.json()["data"]["redirect_url"])

8. Disbursements (Corporate Dashboard)

*Available only to merchants enabled for the Corporate Dashboard — a prefunded OMR balance you hold with OMPAY, topped up by bank transfer and credited by OMPAY after verification. If it isn't enabled for you, these endpoints return 402 MERCHANT_CAPABILITY_DISABLED. Ask OMPAY to enable it.*

Pay out from your corporate balance to your customers' OMPAY wallets — one at a time or in bulk. Each disbursement debits your balance and credits the customer's wallet; if your balance is insufficient the disbursement is rejected. Give every disbursement a unique reference — a repeat with the same reference is rejected, so a retry can never pay a customer twice. Phone numbers are Oman mobiles and are always handled in the form +968XXXXXXXX: you may send 9XXXXXXX, 968…, 00968… or +968… (spaces and dashes are ignored) and the number is normalised; anything that is not an 8‑digit Oman mobile is rejected with 400 VALIDATION_ERROR. Phone numbers are returned masked as +968****XXXX.

OMPAY's fee. If your agreement includes a disbursement fee, it is taken from your balance with each disbursement, plus VAT at the prevailing rate — the balance must cover the amount, the fee and the VAT, or the disbursement is rejected and nothing is taken. The fee is fixed when you submit the disbursement and is shown on each row as fee and fee_vat (both 0 when no fee applies). A disbursement that ends FAILED returns its fee and VAT with the amount. Collections carry no fee. In the rare case the fee cannot be worked out, the call is refused with 503 FEE_CONFIG_UNAVAILABLE and nothing is created — retry shortly.

Wallet credits and debits are paced platform‑wide at 50 per second (half the wallet's own limit). Bulk batches drain at the worker's pace; in the rare case that the pacing queue is full, a single call returns status: PENDING with a "queued" message and the worker completes it — poll GET /api/v1/disbursements/{batch_id} (or /collections/{batch_id}).

8.1 Single disbursement

POST /api/v1/disbursements — processed synchronously; the response carries the final status.

curl -X POST https://api.sandbox.truepay.ompay.om/api/v1/disbursements \
  -H "OMPAY-API-Key: $OMPAY_API_KEY" -H "OMPAY-API-Secret: $OMPAY_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+96890000000", "amount": 10.000, "reference": "PAYOUT-1001" }'

201 on success:

{ "success": true, "data": {
  "batch_id": "…",
  "disbursement": { "disbursement_id": "…", "reference": "PAYOUT-1001", "phone": "+968****0000",
    "amount": 10.000, "currency": "OMR", "status": "SUCCESSFUL", "wallet_reference": "…", "error_message": null,
    "fee": 0.250, "fee_vat": 0.013 }
}}

status is SUCCESSFUL; FAILED (with error_message — e.g. insufficient balance, or the credit was declined); or, rarely, PROCESSING (awaiting confirmation from the wallet provider — poll §8.3).

8.2 Bulk disbursement

POST /api/v1/disbursements/bulk — send up to 10,000 disbursements in one call. Every row is stored first, then processed one by one in the background; the call returns immediately with a batch you poll (§8.3) for per-row results.

{ "disbursements": [
  { "phone": "+96890000000", "amount": 10.000, "reference": "PAYOUT-1001", "description": "October" },
  { "phone": "+96890000001", "amount": 25.500, "reference": "PAYOUT-1002" }
] }

Rows that fail validation or reuse a reference are reported and excluded (the rest are queued). A reference whose earlier row ended FAILED may be submitted again: the failed attempt is kept in its batch for your records (its reference gains a ~F… suffix) and the new row carries the reference you sent:

{ "success": true, "data": { "batch_id": "…", "total": 2, "queued": 2, "errors": [] } }

8.3 Batch status + per‑row results

GET /api/v1/disbursements/:batch_id — poll until no row is PENDING/PROCESSING.

{ "success": true, "data": {
  "batch": { "batch_id": "…", "source": "API", "status": "COMPLETED",
    "total_count": 2, "success_count": 2, "failed_count": 0, "processing_count": 0, "total_amount": 35.500 },
  "disbursements": [
    { "disbursement_id": "…", "reference": "PAYOUT-1001", "phone": "+968****0000", "amount": 10.000, "status": "SUCCESSFUL", "wallet_reference": "…", "fee": 0.250, "fee_vat": 0.013 }
  ]
}}

Row status: PENDING → PROCESSING → SUCCESSFUL / FAILED. A rare NEEDS_REVIEW means the debit was taken but the wallet credit could not be confirmed — OMPAY reconciles these; do not re‑send under a new reference until you've confirmed the outcome.

8.4 Collections — debit customer wallets (needs the *Debit customer wallets* capability)

The mirror image of disbursements: take an amount from a customer's OMPAY wallet into your corporate balance. Same request and response shapes as §8.1–8.3 with the noun collection(s), under POST /api/v1/collections, POST /api/v1/collections/bulk and GET /api/v1/collections/:batch_id. Requires the Corporate Dashboard capability and the separate *Debit customer wallets (Collections)* toggle set by OMPAY — otherwise 402 MERCHANT_CAPABILITY_DISABLED.

Money moves in the opposite order: the customer's wallet is debited first, and your corporate balance is credited only once the wallet confirms the debit. A decline (for example an insufficient customer balance) leaves both sides untouched — status: FAILED with a plain error_message. If the wallet's answer cannot be obtained after retries, the row ends as NEEDS_REVIEW with nothing credited to your balance until OMPAY reconciles it.

curl -X POST https://api.sandbox.truepay.ompay.om/api/v1/collections \
  -H "OMPAY-API-Key: $KEY" -H "OMPAY-API-Secret: $SECRET" -H "Content-Type: application/json" \
  -d '{ "phone": "+96890000000", "amount": 12.500, "reference": "INV-1001", "description": "October subscription" }'

{ "success": true,
  "data": { "batch_id": "…", "idempotent": false,
    "collection": { "collection_id": "…", "direction": "DEBIT", "reference": "INV-1001",
      "wallet_txn_reference": "COLL-…", "phone": "+968****0000", "amount": 12.5, "currency": "OMR",
      "status": "SUCCESSFUL", "wallet_reference": "…", "error_message": null, "created_at": "…" } } }

Bulk takes { "collections": [ { "phone", "amount", "reference", "description" }, … ] } (or a CSV upload in the merchant portal's Corporate Dashboard → Collections (Debit) page with the same columns as the disbursement template). Idempotency-Key and the (merchant, reference) uniqueness work exactly as for disbursements; a reference already used for a disbursement cannot be reused for a collection. wallet_txn_reference (COLL-<id>) is the reference that appears on the customer's wallet transaction.

9. Customer wallet check

*Needs the Customer Wallet Check capability. Without it every call returns 402 MERCHANT_CAPABILITY_DISABLED. Ask OMPAY to enable it.*

Ask whether a customer already holds an OMPAY wallet before you try to pay them or collect from them — and, when you can produce that customer's identity document, whether the account is in a state that can transact.

Nothing is charged, nothing is stored about the customer, and the call moves no money. Because it answers a question about a named person, it is rate limited to 20 calls a minute and 500 a rolling day per merchant, and every call is recorded in OMPAY's audit trail.

9.1 Check an account

POST /api/v1/customers/wallet-check

curl -X POST https://api.sandbox.truepay.ompay.om/api/v1/customers/wallet-check \
  -H "OMPAY-API-Key: $KEY" -H "OMPAY-API-Secret: $SECRET" -H "Content-Type: application/json" \
  -d '{ "phone": "+96891234567", "id_number": "12345678" }'

{ "success": true,
  "data": {
    "found": true,
    "identity_match": true,
    "status": "ACTIVE",
    "active": true,
    "phone": "+968****4567",
    "reason": null,
    "reason_code": null,
    "checked_at": "2026-09-16T08:41:02.113Z" } }

identity_match is deliberately conservative: it is true only when the directory itself confirms the document belongs to that customer. If the directory gives OMPAY no way to check, the answer is identity_match: false with a reason saying so, and no status — never an optimistic match.

Why a status can be withheld. The account state is disclosed only to a caller who can produce that customer's identity document. So a mobile that is registered to somebody else answers, honestly and without telling you anything about them:

{ "success": true,
  "data": { "found": true, "identity_match": false, "status": null, "active": false,
    "phone": "+968****4567",
    "reason": "An OMPAY customer is registered with this mobile number, but the identity document does not belong to them.",
    "reason_code": "IDENTITY_MISMATCH",
    "checked_at": "…" } }

9.2 Errors

Treat every 5xx as "unknown", never as "no such customer". A directory that is down, slow or misconfigured always produces an error — it never produces found: false. If you branch on this call, fail the branch open (carry on and let the payment itself decide) rather than telling a real customer they have no wallet.

9.3 Test numbers (sandbox)

When the sandbox runs on simulated data, the last two digits of the mobile choose the answer:

10. Payment links

*Needs the Payment Links capability. Without it every call returns 402 MERCHANT_CAPABILITY_DISABLED. Ask OMPAY to enable it.*

A payment link is a web address you give a customer. They open it, pay on OMPAY's hosted checkout page (card details and 3‑D Secure are handled there, never by you) and are sent back to you. You do not build a payment page, and no card data ever reaches your server.

It is the same feature as Payment Links in the OMPAY Merchant Portal: a link you create here appears there, and the other way round.

Authentication is the same two headers as everywhere else (§2).

10.1 In three steps

1. Create a link. Only amount is required.

curl -X POST https://api.sandbox.truepay.ompay.om/api/v1/payment-links \
  -H "OMPAY-API-Key: $KEY" -H "OMPAY-API-Secret: $SECRET" -H "Content-Type: application/json" \
  -d '{ "amount": "12.500" }'

{ "success": true,
  "data": {
    "id": "5f0c1c9e-2b7a-4c53-9f3e-0d6a7c1b2e44",
    "status": "PENDING",
    "amount": "12.500",
    "currency": "OMR",
    "pay_url": "https://store.truepay.ompay.om/pay/Xk3...",
    "qr_url": "https://store.truepay.ompay.om/pay/Xk3.../qr.png",
    "expires_at": "2026-10-28T10:00:00.000Z",
    "created_at": "2026-10-25T10:00:00.000Z",
    "delivered": {} } }

2. Give it to your customer. Send them pay_url (a message, an email, a button), or show qr_url (the same address as a QR code image) for them to scan with their phone.

3. Find out when it is paid. Read the link: GET /api/v1/payment-links/{id}. When status is PAID, transaction_id is the payment — look it up with GET /api/v1/transactions/{transaction_id} (§3.6).

That is the whole flow. Everything below is optional.

10.2 Create a link — all the fields

POST /api/v1/payment-links

curl -X POST https://api.sandbox.truepay.ompay.om/api/v1/payment-links \
  -H "OMPAY-API-Key: $KEY" -H "OMPAY-API-Secret: $SECRET" -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d '{ "amount": "45.000", "description": "Order 1042", "reference": "ORD-1042",
        "customer_name": "Aisha", "customer_email": "aisha@example.com", "customer_phone": "91234567",
        "expiry_hours": 48, "return_url": "https://shop.example.com/thanks",
        "notify_via_email": true, "notify_via_sms": true }'

delivered in the answer says what happened to each message: { "EMAIL": "sent", "SMS": "failed" }. A message that could not be sent never loses the link: you always get pay_url back, and you can send again (§10.5). Emails go out under your own sender address when you have set one up and verified it in the portal.

Retrying safely. Send an Idempotency-Key header (any string up to 80 characters, one per link you mean to make). If your request times out and you send it again with the same key, you get the same link back instead of a second one. Without the header every call makes a new link.

10.3 The link

Every call that returns a link returns these fields:

Reading one link (GET /api/v1/payment-links/{id}) also returns deliveries: each message sent (channel, recipient, status, sent_at).

A link expires on its own at expires_at; a paid link stays paid. The customer who opens a link that is no longer payable sees a page that says so.

10.4 Read, list and cancel

curl "https://api.sandbox.truepay.ompay.om/api/v1/payment-links?status=PAID&limit=10" \
  -H "OMPAY-API-Key: $KEY" -H "OMPAY-API-Secret: $SECRET"

You only ever see your own links. A link that belongs to someone else answers 404, exactly like one that does not exist.

10.5 Send a link to the customer

POST /api/v1/payment-links/{id}/deliver

{ "success": true, "data": { "channel": "EMAIL", "recipient": "aisha@example.com", "status": "SENT" } }

Only a link that can still be paid can be sent (409 CONFLICT otherwise).

10.6 Partial payments

With "allow_partial": true the customer may pay any part of the amount, as many times as they like, until the whole amount has been paid, the link expires, or you cancel it. status is PARTIALLY_PAID along the way and remaining_amount says what is left. Each instalment is its own payment in your Transactions.

10.7 Many links at once

POST /api/v1/payment-links/bulk creates up to 500 links in one call — either as a list:

{ "links": [
    { "amount": "5.000", "description": "Invoice 1", "customer_email": "a@example.com" },
    { "amount": "7.500", "reference": "INV-2", "customer_phone": "91234567" } ] }

or with the Excel template the portal uses (GET /api/v1/payment-links/bulk/template downloads it): { "file_base64": "<the .xlsx file, base64>", "filename": "march.xlsx" }. Send links or file_base64. Keep the request under 1 MB.

{ "success": true, "data": { "batch_id": "…", "total": 2, "created": 2, "errors": [] } }

A row that fails is listed in errors with its row number, for example { "row": 3, "error": "A positive amount is required." }, and the other rows are still created. List the links of a batch with GET /api/v1/payment-links?batch_id=…, and your batches with GET /api/v1/payment-links/bulk.

10.8 Defaults and limits

GET /api/v1/payment-links/config returns default_expiry_hours (the lifetime a link gets when you do not set one — OMPAY sets it), the longest you may ask for, the channels you can send on, and the bulk limit.

Creating links is limited to 120 a minute, and sending to 30 a minute, per merchant.

10.9 Errors

Every error has the shape in §5. The ones specific to payment links:

10.10 Testing in the sandbox

Create a link with the sandbox key, open its pay_url in a browser and pay with a test card (see Test cards). The link then reads PAID with a transaction_id. The API Sandbox page has a *Payment links* group with a ready-made request for every call above.

11. Settlement reports

Settlements are what OMPAY pays out to your bank account for the payments you took: the payments of a period, less any refunds and chargebacks, less OMPAY's fee and the VAT on it. These calls give you the same settlement reports as the OMPAY Merchant Portal — your settlements, the transactions in each, an Excel report, and the tax invoices — so your own systems can reconcile without anyone logging in.

Authentication is the same two headers as everywhere else (§2). There is nothing to enable: every merchant can read its own settlements.

11.1 In three steps

1. List your settlements.

curl "https://api.sandbox.truepay.ompay.om/api/v1/settlements?status=PAID&limit=10" \
  -H "OMPAY-API-Key: $KEY" -H "OMPAY-API-Secret: $SECRET"

{ "success": true,
  "data": {
    "settlements": [ {
      "id": "8d2f6c7e-1b4a-4c0e-9a55-3f2d8b7a6c10",
      "status": "PAID",
      "currency": "OMR",
      "period_start": "2026-10-01",
      "period_end": "2026-10-07",
      "transaction_count": 42,
      "gross_amount": "1250.000",
      "fee_amount": "18.750",
      "vat_amount": "0.938",
      "net_amount": "1230.312",
      "payout_reference": "BK-20261009-17",
      "paid_at": "2026-10-09T08:00:00.000Z",
      "destinations": [ { "account_last4": "6789", "beneficiary_name": "Acme LLC", "is_primary": true, "amount": "1230.312", "status": "PAID" } ]
    } ],
    "pagination": { "total": 14, "page": 1, "limit": 10, "pages": 2 } } }

2. Open one to see the transactions in it: GET /api/v1/settlements/{id}.

3. Download its Excel report: GET /api/v1/settlements/{id}/export — a .xlsx file.

curl -o Settlement.xlsx "https://api.sandbox.truepay.ompay.om/api/v1/settlements/$ID/export" \
  -H "OMPAY-API-Key: $KEY" -H "OMPAY-API-Secret: $SECRET"

11.2 List settlements

GET /api/v1/settlements — your settlements, newest first.

Each settlement has:

All amounts are strings in OMR with three decimals.

11.3 Summary

GET /api/v1/settlements/summary

{ "success": true,
  "data": { "currency": "OMR", "pending_amount": "412.500", "pending_count": 2,
            "paid_out_this_month": "1230.312", "bank_account_last4": "6789", "as_of": "2026-10-25T10:00:00.000Z" } }

pending_amount is what is owed to you in settlements that have not been paid out yet.

11.4 One settlement, with its transactions

GET /api/v1/settlements/{id} — the settlement (as in §11.2) and transactions:

11.5 Files

These return a file, not JSON. Save the response body.

Monthly tax invoices are issued to the main merchant account, with each sub-merchant's activity itemised inside. A sub-merchant's own key has none: its list is empty and the PDF call answers 403 NOT_AVAILABLE.

11.6 What you see

• Your own settlements only. A settlement or invoice that belongs to someone else answers 404, exactly like one that does not exist.

A key sees the settlements of the merchant it belongs to; if you have sub-merchants, use each one's own key (or the portal, which shows them together).

• Never the bank behind a payment. Card network, the bank's reference number (rrn) and your own references are shown; nothing that says which acquirer processed it.
• Files are drawn by the same code as the portal's Settlements page, so a report from the API and one from the portal are the same.

11.7 Errors

Every error has the shape in §5. The ones specific to settlement reports:

11.8 Testing in the sandbox

In the API Sandbox page, the *Manage* group has a request for every call above. The file calls show a Download button beside the response. A new sandbox merchant has no settlements until a settlement run has happened for its payments; the list is then empty ("settlements": []) and the file calls need a settlement id from a run.