OnePay Endpoints

The SDK wraps eight OnePay endpoints under the /wallet-service/wallet/payment-integration prefix. All POST unless noted.

Base URL by environment

The same path set is served on two hosts. Pick one with PAYNOW_ENV:

PAYNOW_ENV	Base URL
sandbox (default)	https://paynowdev.firstfintech.com
live	https://backend.paynow.com.ly

Endpoints, request shapes, response shapes, and error envelopes are identical across both — only the host differs. Sandbox accepts test data only; live moves real funds.

Endpoints

Operation	Path	Auth
createInvoice / initiateWebPayment	/web-payment/initiate	Api-Key + Secret-Key (+ HMAC)
generateQr (OnePay)	/web-payment/one-pay/merchant-qr	Bearer JWT (+ HMAC)
generateQr (PayNow wallet)	/web-payment/paynow/merchant-qr	Bearer JWT (+ HMAC)
validateAccount (OnePay)	/web-payment/initiate-payment-request	Bearer JWT (+ HMAC)
validateAccount (PayNow wallet)	/web-payment/paynow/initiate-payment-request	Bearer JWT (+ HMAC)
submitOtp (OnePay)	/payment-request	Bearer JWT (+ HMAC)
submitOtp (PayNow wallet)	/web-payment/paynow/process-payment-request	Bearer JWT (+ HMAC)
fetchStatus	/web-payment/check-status	Bearer JWT (+ HMAC)
fetchInstitutions (GET)	/get-institution-list	Bearer JWT (+ HMAC)

Authentication headers

Header	When attached
Api-Key	Only on /web-payment/initiate (and on /check-status if statusPathRequiresMerchantAuth: true).
Secret-Key	Same as Api-Key.
Authorization: Bearer <jwt>	All downstream calls. The JWT is returned by /web-payment/initiate under data.token.
X-PayNow-Client-Id / X-PayNow-Timestamp / X-PayNow-Nonce / X-PayNow-Signature	When an HmacSigner is configured — see HMAC Signer.
Content-Type: application/json	All POST requests.

Request / response envelope

Most endpoints follow this shape:

{
              "success": true,
              "message": "OK",
              "data": { ... }
            }
            

The SDK's _decodeJson unwraps data so callers see flat fields. The OnePay /payment-request endpoint is the exception — it returns data as a plain string acknowledgement ({ "success": true, "data": "Payment requested." }), which the SDK detects via _stringDataAcknowledgement and treats as state: waitingPayment.

Status endpoint body

POST /web-payment/check-status
            Authorization: Bearer <jwt>
            Content-Type: application/json
            
            { "byAccountNumber": false, "orderId": "<orderId>" }
            

byAccountNumber is true once the OnePay account flow has captured a debitorAccNumber; false for QR and PayNow-wallet flows. See Status Polling for the full schedule.

Currency on the wire

All amounts go out as major units in a string for /payment-request and as major units in a number for /web-payment/initiate. The SDK converts from amountMinor using currencyFractionDigits(currency) so 3-digit currencies (LYD/BHD/KWD/OMR/TND) serialize correctly.

Idempotency

/web-payment/initiate is not idempotent. Make sure your merchant server creates a session at most once per logical order — the SDK's idempotencyKey is consumed by the engine's retry layer, not by OnePay.

Downstream endpoints (/initiate-payment-request, /process-payment-request, /payment-request) accept repeated calls but typically replay the existing OTP / settlement instead of creating a new one.