Merchant Onboarding

Before you can accept payments you need three things from OnePay:

1. Api-Key — your merchant identifier.
2. Secret-Key — paired with the API key on /web-payment/initiate.
3. (Optional) HMAC client_id + secret — additional request signing if your deployment requires it.

Sandbox vs live (production)

The SDK supports two OnePay deployments. Pick one with the PAYNOW_ENV switch:

PAYNOW_ENV	Base URL	When to use
sandbox (default)	https://paynowdev.firstfintech.com	Test data only. Use until your integration passes manual QA.
live	https://backend.paynow.com.ly	Real funds move. Only after manual QA on sandbox.

The default is sandbox — fail-safe, so a misconfigured deploy never accidentally hits production. Production credentials are different from sandbox; never reuse sandbox keys in live mode.

The gateway also renders a yellow SANDBOX badge in the top-right corner whenever it's wired to anything other than live, so QA and customers can tell at a glance that no real funds are moving.

Configure your environment

The repo keeps sandbox and live credentials in separate gitignored files:

cp scripts/onepay.sandbox.env.example scripts/onepay.sandbox.env
            cp scripts/onepay.live.env.example scripts/onepay.live.env
            

scripts/start_local_stack.sh uses scripts/onepay.sandbox.env by default when it exists. To run against live, pass ONEPAY_ENV_FILE=scripts/onepay.live.env explicitly. Both templates list the same supported variables:

# Which OnePay deployment to talk to (sandbox or live).
            PAYNOW_ENV="sandbox"
            
            # Optional explicit base URL override. Day-to-day, switch PAYNOW_ENV instead.
            # Leave blank to let the SDK use the URL associated with PAYNOW_ENV.
            PAYNOW_ONEPAY_BASE=""
            
            # Required for /web-payment/initiate
            PAYNOW_ONEPAY_API_KEY=""
            PAYNOW_ONEPAY_SECRET_KEY=""
            
            # Optional: where the gateway POSTs terminal events
            PAYNOW_ONEPAY_CALLBACK_URL=""
            
            # Optional: defaults for /payment-request fields
            PAYNOW_ONEPAY_CUSTOMER_PHONE=""
            PAYNOW_ONEPAY_CREDITOR_ACC=""
            PAYNOW_ONEPAY_MCC=""
            
            # Optional: status polling endpoint (defaults to /web-payment/check-status)
            PAYNOW_ONEPAY_STATUS_PATH=""
            
            # Optional: HMAC signing — runtime only, never baked into the browser bundle
            PAYNOW_HMAC_CLIENT_ID=""
            PAYNOW_HMAC_SECRET=""
            

Where credentials live

This is the rule that matters most: merchant credentials must never reach the browser.

• Server-side only: Api-Key, Secret-Key, HMAC client_id and secret. Read at request time via Platform.environment inside the merchant SSR server. Never use String.fromEnvironment for these — that bakes them into the compiled JS bundle every visitor downloads.
• Safe to ship to the browser: gateway base URL, return URL, locale, and other display config.

The server-side initiation pattern (next page) is the practical implementation.

Production checklist

• OnePay production credentials in scripts/onepay.live.env (or your prod equivalent).
• PAYNOW_ENV=live in the production environment.
• PAYNOW_ONEPAY_BASE left blank (or removed) so the SDK uses the env's built-in URL — set this only if you need to override.
• PAYNOW_GATEWAY_BASE and MERCHANT_RETURN_BASE set to your live origins.
• HMAC enabled if your contract requires it (PAYNOW_HMAC_CLIENT_ID + PAYNOW_HMAC_SECRET set).
• Server-side /api/initiate-payment endpoint deployed (the merchant demo's merchantInitiateMiddleware is the working reference).
• scripts/onepay.live.env is in .gitignore (it already is in this repo — verify in any fork).
• Confirmed the SANDBOX badge no longer appears on the gateway (it hides automatically when PAYNOW_ENV=live).