OnePay Online Vendor API

The OnePay Online vendor flow lets a merchant load supported customer institutions, initiate a payment, confirm it using OTP, check the status when the payment hub (DPH) needs more time, and list vendor transactions for history and reporting.

SmartPay is the payment service of the SmartBank platform by Sarab Tech. Merchants with a Mediterranean Bank (Meditbank) corporate account can receive payments from customers of all OnePay member banks through this API.

Authentication & common headers

All endpoints are authenticated with a vendor API key sent in the X-Api-Key header. The backend uses it to identify and authorize your vendor/POS.

Recommended integration flow

1 · Get OnePay institutions

Returns the institutions/banks the merchant can show to the customer. The selected institution id is later sent as CustomerInstitutionId. No body or query parameters.

Response — 200 OK

[
  { "id": "000010", "name": "Bank of Commerce and Development", "shortName": "BCD", "logo": "https://…/bcd.png" },
  { "id": "000002", "name": "Al Jumhouria Bank", "shortName": "AJB", "logo": "https://…/ajb.png" }
]

2 · Initiate OnePay payment

Creates a OnePay payment request for a customer and returns the transactionId used in confirm and status-check calls.

Request body

Response — 200 OK

{
  "customerName": "Mock Customer",
  "customerInstitutionName": "Bank of Commerce and Development",
  "amount": 100.234,
  "transactionId": "019f220e-5284-7434-833d-0e068d2da8d4"
}

3 · Confirm OnePay payment

Confirms an initiated payment using transactionId and OTP. The response may still be pending while DPH finishes processing.

Request body

Response — 200 OK

{
  "transactionId": "019ed65a-25a4-7b40-9233-5dd7689a212e",
  "bankTransactionId": "019ed65a-2595-73a8-a7ce-809c2661605d",
  "isError": false,
  "errorMessage": "",
  "hostReference": "019ed65a228478f78f405a6fd2db19c0",
  "dphReference": "15344481",
  "status": 0
}

4 · Check OnePay payment status

Checks the latest known status of a OnePay transaction. Use this when the UI is waiting, the confirm response is pending, or the result is unclear.

Path parameter

Response — 200 OK

{
  "status": 0,
  "isError": false,
  "transactionCode": "42612385",
  "transactionId": "019ed531-4a8f-7ca1-a3a1-c91d205e8133",
  "bankTransactionId": "019ed531-4a27-7503-a3de-ca9207adcaf4"
}

5 · Get vendor transactions

Returns the authenticated vendor's OnePay transactions with paging and optional filters.

Query parameters

Response — 200 OK

[
  {
    "id": "019f220e-5284-7434-833d-0e068d2da8d4",
    "transactionCode": "DPH-019f220e45f47c2ca30c321751094f37",
    "amount": 100.234,
    "currency": "434",
    "customerAccountName": "Mock Customer",
    "customerInstitutionName": "Bank of Commerce and Development",
    "pointOfSaleName": "آلة الخدمة",
    "source": "Onepay",
    "status": 1,
    "createdAt": "2026-07-02T10:59:51.810919",
    "confirmedAt": "2026-07-02T10:59:52.420934"
  }
]

Transaction status values

Error handling

Errors are returned as JSON problem details. Exact messages may be localized, so rely on HTTP status and field names first, then display the message returned by the API.

Example error body

{
  "type": "",
  "title": "Amount must be greater than 0",
  "detail": "Amount must be greater than 0",
  "status": 422,
  "instance": "/smartpay/api/online/vendor/onepay/init-transfer",
  "traceId": "<trace-id>",
  "errors": { "Amount": "Amount must be greater than 0" }
}

⚡ Payment flow simulator

Walk the full OnePay Online payment lifecycle with mock responses — no API key needed. Everything runs in your browser; no real calls are made.

🛠 Request builder

Fill in your values and copy a ready-to-run request. The snippet updates live as you type.