PaymentApi

PaymentApi is the contract every backend implementation honours. Live in packages/paynow_core/lib/src/payment_api.dart:

abstract interface class PaymentApi {
              Future<PaymentSession> createInvoice(CreateInvoiceRequest request);
              Future<PaymentSession> generateQr(GenerateQrRequest request);
              Future<PaymentSession> validateAccount(ValidateAccountRequest request);
              Future<PaymentSession> submitAccount(SubmitAccountRequest request);
              Future<PaymentSession> submitOtp(SubmitOtpRequest request);
              Future<PaymentSession> fetchStatus(FetchStatusRequest request);
            }
            

Implementations

PayNowOnePayApi

Production backend. Wraps the OnePay wallet-service endpoints. See OnePay Endpoints for the full mapping.

final api = PayNowOnePayApi(
              config: PayNowOnePayConfig(
                environment: PaymentEnvironment.sandbox,        // or .live
                apiKey: env['PAYNOW_ONEPAY_API_KEY'],
                secretKey: env['PAYNOW_ONEPAY_SECRET_KEY'],
                statusPath: '/web-payment/check-status',
                signer: HmacSigner(clientId: ..., secret: ...), // optional
                // baseUri: optional explicit override — day-to-day, switch environment.
              ),
            );
            

PaymentEnvironment selects the OnePay deployment (sandbox → paynowdev.firstfintech.com, live → backend.paynow.com.ly). baseUri is an optional override for tests / on-prem hosts; when null, the SDK uses the URL associated with environment.

StaticJsonPaymentApi

In-memory fixtures. No network calls. Useful for design previews, demos, and unit tests. The fixture flow auto-progresses qrGenerated → waitingPayment → success over a couple of fetchStatus calls.

PaymentApiException

All implementations throw PaymentApiException on failure:

class PaymentApiException implements Exception {
              final String message;
              final bool isRetryable;
              final int? statusCode;
              final String? code;
            }
            

See Error Handling for typed error codes and how RetryPolicy consumes them.

Choosing an implementation

Use createPaymentApi() from payment_api_factory.dart — it reads the PAYNOW_GATEWAY_FLOW_MODE build define (static vs onepay) and the PAYNOW_ENV define (sandbox vs live) and constructs the right backend.

final api = createPaymentApi(); // mode + env from --dart-define
            

Modes:

• static — StaticJsonPaymentApi. Available for fixture-only cPanel/shared-hosting demos. PAYNOW_ENV is irrelevant here.
• onepay — PayNowOnePayApi. Targets paynowdev.firstfintech.com (sandbox) or backend.paynow.com.ly (live) based on PAYNOW_ENV. Defaults to sandbox so a misconfigured deploy never moves real funds.

See Merchant Onboarding for the full env-var matrix.