PPayNow Docs
Menu — Quick Start

Quick Start

Quick Start

Boot the local stack and walk a QR checkout end to end. Five minutes.

You'll have a working merchant storefront, a PayNow gateway, and a successful QR checkout in five minutes.

Prerequisites

  • Dart SDK 3.11+ (dart --version).
  • macOS or Linux — the local stack script uses bash, lsof, and Unix-style kill semantics.
  • OnePay sandbox credentials if you want to run against the real backend. Without them the stack falls back to in-memory fixtures.

1. Clone and resolve

git clone https://github.com/your-org/paynow-nexus.git
            cd paynow-nexus
            dart pub get

2. (Optional) Add OnePay credentials

Copy the env template and fill in the values OnePay issued you:

cp scripts/onepay.sandbox.env.example scripts/onepay.sandbox.env
            $EDITOR scripts/onepay.sandbox.env

Without this file the stack still boots — it just runs in static mode against fixtures. With sandbox credentials, it auto-detects onepay mode and drives the real sandbox backend.

The sandbox template targets paynowdev.firstfintech.com, so you can develop safely without risking a real transaction. To target the live backend (backend.paynow.com.ly) use a separate scripts/onepay.live.env copied from scripts/onepay.live.env.example, then run with ONEPAY_ENV_FILE=scripts/onepay.live.env. The gateway shows a yellow SANDBOX badge whenever it's not in live mode. See Merchant Onboarding for the full env-var matrix.

3. Boot the stack

./scripts/start_local_stack.sh

Three things happen:

Service URL
PayNow gateway http://localhost:8080
Merchant demo (Bella Cart) http://localhost:8082
Status polling endpoint /wallet-service/wallet/payment-integration/web-payment/check-status

4. Walk a QR checkout

  1. Open http://localhost:8082. Add an item to the cart.
  2. Click Place order with PayNow. The merchant server calls /web-payment/initiate server-side and redirects you to the gateway with a paymentId query param.
  3. The gateway shows the QR code. Scan it with the OnePay sandbox banking app, or simulate a settlement via the OnePay dashboard.
  4. Within one poll tick (≤ 3 s in the first 30 s, ≤ 10 s after) the gateway flips to the success receipt — no button click required.

5. Try the OnePay account flow

From the same merchant cart click Place order, then on the gateway choose OnePay Account. Enter a sandbox account number, complete the OTP, and the gateway will hold on the "awaiting confirmation" screen until /check-status reports settlement.

What's running where

  • Gateway (:8080) — packages/paynow_jaspr_sdk/bin/server.dart. Renders the checkout, handles QR / account / OTP, polls /check-status.
  • Merchant (:8082) — examples/paynow_jaspr_ecommerce_demo/bin/server.dart. Owns the cart UI and the server-side /api/initiate-payment endpoint.
  • Status poller — packages/paynow_core/lib/src/payment_status_poller.dart. Lives in the gateway page; activates only on the QR and OnePay-waiting screens.

Stop the stack

Ctrl+C in the terminal kills both servers and clears .local_stack.pids.

Next steps

  • Merchant onboarding — get production-ready credentials and configure your environment.
  • Server-side initiation — the security boundary every integration must respect.
  • QR flow — what actually happens between the browser, the merchant server, the gateway, and OnePay.