@laranex/myanmar-payments 0.0.0-stage → 4.0.0-dev.1

package/dist/esm/cyber-source/cyber-source.d.ts

@@ -0,0 +1,95 @@
+import { type AmountInput } from '../core/amount.js';
+import { CallbackRequest, PaymentCallback } from '../core/callback.js';
+import { type EnvSource } from '../core/env.js';
+import { FormPayment } from '../core/results.js';
+/** The settings of {@link CyberSourceConfig}. */
+export interface CyberSourceConfigOptions {
+    /** The Secure Acceptance profile id. */
+    profileId: string;
+    /** The profile's access key. */
+    accessKey: string;
+    /** The profile's secret key, which signs the fields. */
+    secretKey: string;
+    /** Use the test environment (default `true`). */
+    sandbox?: boolean | undefined;
+    /** Overrides the Secure Acceptance base URL. */
+    baseUrl?: string | undefined;
+}
+/**
+ * A CyberSource Secure Acceptance profile. A missing credential throws a `ConfigurationError`.
+ */
+export declare class CyberSourceConfig {
+    static readonly SANDBOX_URL = "https://testsecureacceptance.cybersource.com";
+    static readonly PRODUCTION_URL = "https://secureacceptance.cybersource.com";
+    readonly profileId: string;
+    readonly accessKey: string;
+    readonly secretKey: string;
+    readonly sandbox: boolean;
+    /** The base URL in use. */
+    readonly baseUrl: string;
+    constructor(options: CyberSourceConfigOptions);
+    /**
+     * Reads `CYBER_SOURCE_PROFILE_ID`, `CYBER_SOURCE_ACCESS_KEY`, `CYBER_SOURCE_SECRET_KEY`,
+     * `CYBER_SOURCE_SANDBOX` and `CYBER_SOURCE_BASE_URL`.
+     */
+    static fromEnv(env?: EnvSource): CyberSourceConfig;
+}
+/** What CyberSource does with the card. */
+export type CyberSourceTransactionType = 'sale' | 'authorization' | 'sale,create_payment_token' | 'authorization,create_payment_token';
+/** The CyberSource transaction types. */
+export declare const CyberSourceTransactionType: Readonly<{
+    /** Authorize and capture in one step. */
+    readonly Sale: "sale";
+    /** Authorize only; capture later. */
+    readonly Authorization: "authorization";
+    /** A sale that also saves the card as a payment token. */
+    readonly SaleAndCreateToken: "sale,create_payment_token";
+    /** An authorization that also saves the card as a payment token. */
+    readonly AuthorizationAndCreateToken: "authorization,create_payment_token";
+}>;
+/**
+ * A Secure Acceptance card payment. CyberSource is multi-currency.
+ */
+export interface CyberSourcePaymentData {
+    /** Your order id (`reference_number`), at most 50 characters. Echoed back as `req_reference_number`. */
+    orderId: string;
+    /** The total in `currency`: 0 or more, any decimals, at most 15 characters, e.g. `Amount.parse('10.50')`. */
+    amount: AmountInput;
+    /** The URL CyberSource posts the result to (`override_backoffice_post_url`), at most 255 characters. */
+    callbackUrl: string;
+    /** The receipt page (`override_custom_receipt_page`), at most 255 characters. */
+    returnUrl?: string | undefined;
+    /** The page shown on cancel (`override_custom_cancel_page`), at most 255 characters. */
+    cancelUrl?: string | undefined;
+    /** An ISO 4217 code (default `MMK`). */
+    currency?: string | undefined;
+    /** What to do with the card (default `sale`). */
+    transactionType?: CyberSourceTransactionType | undefined;
+    /** The hosted page language, e.g. `en-us` (the default). */
+    locale?: string | undefined;
+}
+/**
+ * CyberSource Secure Acceptance hosted checkout for card payments: signs the form and verifies the
+ * result posts. Makes no network calls.
+ */
+export declare class CyberSource {
+    /** The configuration in use. */
+    readonly config: CyberSourceConfig;
+    constructor(config: CyberSourceConfig | CyberSourceConfigOptions);
+    /** A gateway configured from the `CYBER_SOURCE_*` environment variables. */
+    static fromEnv(env?: EnvSource): CyberSource;
+    /** Checks the payment against the Secure Acceptance field reference; throws an `InvalidPaymentDataError`. */
+    static validate(data: CyberSourcePaymentData): void;
+    /**
+     * Signs the payment fields. The customer's browser must POST the returned form to CyberSource;
+     * `toHtml()` renders a page that does it.
+     */
+    initiate(data: CyberSourcePaymentData): FormPayment;
+    /**
+     * Verifies CyberSource's result post. The same check works for the browser post to your receipt
+     * page.
+     */
+    handleCallback(request: CallbackRequest): PaymentCallback;
+    /** Signs the fields listed in `signed_field_names`; `undefined` when a listed field is missing. */
+    private sign;
+}

package/dist/esm/cyber-source/cyber-source.js

@@ -0,0 +1,184 @@
+import {} from '../core/amount.js';
+import { CallbackRequest, losslessInput, PaymentCallback } from '../core/callback.js';
+import { hmacSha256Base64, randomHex, safeEqual } from '../core/crypto.js';
+import { defaultEnv, envFirst, envSandbox, optionalSetting, requireSetting, trimUrl, } from '../core/env.js';
+import { SignatureVerificationError } from '../core/errors.js';
+import { toPlainObject } from '../core/json.js';
+import { FormPayment } from '../core/results.js';
+import { resolveStatus } from '../core/status.js';
+import { toAmount, Validator } from '../core/validate.js';
+import { get, optional, scalarString, trimmed } from '../core/values.js';
+/**
+ * A CyberSource Secure Acceptance profile. A missing credential throws a `ConfigurationError`.
+ */
+export class CyberSourceConfig {
+    static SANDBOX_URL = 'https://testsecureacceptance.cybersource.com';
+    static PRODUCTION_URL = 'https://secureacceptance.cybersource.com';
+    profileId;
+    accessKey;
+    secretKey;
+    sandbox;
+    /** The base URL in use. */
+    baseUrl;
+    constructor(options) {
+        this.profileId = requireSetting('cyber_source', 'profile_id', options.profileId);
+        this.accessKey = requireSetting('cyber_source', 'access_key', options.accessKey);
+        this.secretKey = requireSetting('cyber_source', 'secret_key', options.secretKey);
+        this.sandbox = options.sandbox ?? true;
+        this.baseUrl = trimUrl(optionalSetting(options.baseUrl) ??
+            (this.sandbox ? CyberSourceConfig.SANDBOX_URL : CyberSourceConfig.PRODUCTION_URL));
+    }
+    /**
+     * Reads `CYBER_SOURCE_PROFILE_ID`, `CYBER_SOURCE_ACCESS_KEY`, `CYBER_SOURCE_SECRET_KEY`,
+     * `CYBER_SOURCE_SANDBOX` and `CYBER_SOURCE_BASE_URL`.
+     */
+    static fromEnv(env = defaultEnv()) {
+        return new CyberSourceConfig({
+            profileId: envFirst(env, 'CYBER_SOURCE_PROFILE_ID'),
+            accessKey: envFirst(env, 'CYBER_SOURCE_ACCESS_KEY'),
+            secretKey: envFirst(env, 'CYBER_SOURCE_SECRET_KEY'),
+            sandbox: envSandbox(env, 'CYBER_SOURCE_SANDBOX'),
+            baseUrl: envFirst(env, 'CYBER_SOURCE_BASE_URL'),
+        });
+    }
+}
+/** The CyberSource transaction types. */
+export const CyberSourceTransactionType = Object.freeze({
+    /** Authorize and capture in one step. */
+    Sale: 'sale',
+    /** Authorize only; capture later. */
+    Authorization: 'authorization',
+    /** A sale that also saves the card as a payment token. */
+    SaleAndCreateToken: 'sale,create_payment_token',
+    /** An authorization that also saves the card as a payment token. */
+    AuthorizationAndCreateToken: 'authorization,create_payment_token',
+});
+const TRANSACTION_TYPES = Object.values(CyberSourceTransactionType);
+const SIGNED_FIELDS = [
+    'access_key',
+    'profile_id',
+    'transaction_uuid',
+    'signed_field_names',
+    'signed_date_time',
+    'locale',
+    'transaction_type',
+    'reference_number',
+    'amount',
+    'currency',
+    'override_custom_receipt_page',
+    'override_backoffice_post_url',
+    'override_custom_cancel_page',
+];
+const STATUSES = {
+    ACCEPT: 'successful',
+    REVIEW: 'pending',
+    DECLINE: 'failed',
+    ERROR: 'failed',
+    CANCEL: 'cancelled',
+};
+/**
+ * CyberSource Secure Acceptance hosted checkout for card payments: signs the form and verifies the
+ * result posts. Makes no network calls.
+ */
+export class CyberSource {
+    /** The configuration in use. */
+    config;
+    constructor(config) {
+        this.config = config instanceof CyberSourceConfig ? config : new CyberSourceConfig(config);
+    }
+    /** A gateway configured from the `CYBER_SOURCE_*` environment variables. */
+    static fromEnv(env = defaultEnv()) {
+        return new CyberSource(CyberSourceConfig.fromEnv(env));
+    }
+    /** Checks the payment against the Secure Acceptance field reference; throws an `InvalidPaymentDataError`. */
+    static validate(data) {
+        new Validator()
+            .required('orderId', data.orderId)
+            .max('orderId', data.orderId, 50)
+            .amount('amount', data.amount, {
+            gateway: 'CyberSource',
+            maxDecimals: null,
+            maxLength: 15,
+            allowZero: true,
+        })
+            .required('callbackUrl', data.callbackUrl)
+            .url('callbackUrl', data.callbackUrl)
+            .max('callbackUrl', data.callbackUrl, 255)
+            .string('returnUrl', data.returnUrl)
+            .url('returnUrl', data.returnUrl)
+            .max('returnUrl', data.returnUrl, 255)
+            .string('cancelUrl', data.cancelUrl)
+            .url('cancelUrl', data.cancelUrl)
+            .max('cancelUrl', data.cancelUrl, 255)
+            .pattern('currency', String(data.currency || 'MMK'), /^[A-Z]{3}$/, 'a three letter ISO 4217 code')
+            .pattern('locale', String(data.locale || 'en-us'), /^[a-z]{2}-[a-z]{2}$/, 'a locale code such as en-us')
+            .when(!TRANSACTION_TYPES.includes(String(data.transactionType || 'sale')), 'transactionType', 'The transactionType field is not a supported transaction type.')
+            .validate();
+    }
+    /**
+     * Signs the payment fields. The customer's browser must POST the returned form to CyberSource;
+     * `toHtml()` renders a page that does it.
+     */
+    initiate(data) {
+        CyberSource.validate(data);
+        const values = {
+            access_key: this.config.accessKey,
+            profile_id: this.config.profileId,
+            transaction_uuid: randomHex(),
+            signed_field_names: SIGNED_FIELDS.join(','),
+            signed_date_time: new Date().toISOString().replace(/\.\d{3}Z$/, 'Z'),
+            locale: data.locale || 'en-us',
+            transaction_type: data.transactionType || 'sale',
+            reference_number: data.orderId,
+            amount: String(toAmount(data.amount)),
+            currency: data.currency || 'MMK',
+            override_custom_receipt_page: data.returnUrl ?? '',
+            override_backoffice_post_url: data.callbackUrl,
+            override_custom_cancel_page: data.cancelUrl ?? '',
+        };
+        const fields = SIGNED_FIELDS.map((name) => ({ name, value: values[name] }));
+        fields.push({ name: 'signature', value: this.sign(values) });
+        return new FormPayment({
+            orderId: data.orderId,
+            action: `${this.config.baseUrl}/pay`,
+            fields,
+        });
+    }
+    /**
+     * Verifies CyberSource's result post. The same check works for the browser post to your receipt
+     * page.
+     */
+    handleCallback(request) {
+        const payload = losslessInput(request);
+        const expected = this.sign(payload);
+        if (expected === undefined || !safeEqual(expected, get(payload, 'signature'))) {
+            throw new SignatureVerificationError('CyberSource callback signature verification failed.', toPlainObject(payload));
+        }
+        const decision = trimmed(payload, 'decision').toUpperCase();
+        return new PaymentCallback({
+            orderId: get(payload, 'req_reference_number'),
+            status: resolveStatus(STATUSES, decision),
+            gatewayStatus: decision,
+            gatewayReference: optional(payload, 'transaction_id'),
+            amount: get(payload, 'auth_amount') || optional(payload, 'req_amount'),
+            raw: toPlainObject(payload),
+        });
+    }
+    /** Signs the fields listed in `signed_field_names`; `undefined` when a listed field is missing. */
+    sign(fields) {
+        const pairs = [];
+        for (const name of get(fields, 'signed_field_names').split(',')) {
+            if (name === '') {
+                continue;
+            }
+            const value = scalarString(fields[name]);
+            if (value === undefined) {
+                return undefined;
+            }
+            pairs.push(`${name}=${value}`);
+        }
+        return pairs.length === 0
+            ? undefined
+            : hmacSha256Base64(this.config.secretKey, pairs.join(','));
+    }
+}

package/dist/esm/cyber-source/index.d.ts

@@ -0,0 +1 @@
+export { CyberSource, CyberSourceConfig, CyberSourceTransactionType, type CyberSourceConfigOptions, type CyberSourcePaymentData, } from './cyber-source.js';

package/dist/esm/cyber-source/index.js

@@ -0,0 +1 @@
+export { CyberSource, CyberSourceConfig, CyberSourceTransactionType, } from './cyber-source.js';

package/dist/esm/index.d.ts

@@ -0,0 +1,7 @@
+export * from './core/index.js';
+export * from './aya-pay/index.js';
+export * from './cyber-source/index.js';
+export * from './kbz-pay/index.js';
+export * from './wave-money/index.js';
+export * from './yoma-mmqr/index.js';
+export { MyanmarPayments, type MyanmarPaymentsConfig, type MyanmarPaymentsOptions, } from './myanmar-payments.js';

package/dist/esm/index.js

@@ -0,0 +1,7 @@
+export * from './core/index.js';
+export * from './aya-pay/index.js';
+export * from './cyber-source/index.js';
+export * from './kbz-pay/index.js';
+export * from './wave-money/index.js';
+export * from './yoma-mmqr/index.js';
+export { MyanmarPayments, } from './myanmar-payments.js';

package/dist/esm/kbz-pay/index.d.ts

@@ -0,0 +1,2 @@
+export { KbzPay, KbzPayConfig, type KbzPayConfigOptions, type KbzPayPaymentData, } from './kbz-pay.js';
+export { KbzPaySigner } from './signer.js';

package/dist/esm/kbz-pay/index.js

@@ -0,0 +1,2 @@
+export { KbzPay, KbzPayConfig, } from './kbz-pay.js';
+export { KbzPaySigner } from './signer.js';

package/dist/esm/kbz-pay/kbz-pay.d.ts

@@ -0,0 +1,102 @@
+import { type AmountInput } from '../core/amount.js';
+import { CallbackRequest, PaymentCallback, PaymentStatusResult } from '../core/callback.js';
+import { type EnvSource } from '../core/env.js';
+import { type GatewayOptions, type RequestOptions } from '../core/http.js';
+import { AppPayment, QrPayment, RedirectPayment } from '../core/results.js';
+import { KbzPaySigner } from './signer.js';
+/** The settings of {@link KbzPayConfig}. */
+export interface KbzPayConfigOptions {
+    /** The `appid` KBZ issued for your merchant app. */
+    appId: string;
+    /** The secret key used to sign requests. */
+    appKey: string;
+    /** The `merch_code` KBZ issued. */
+    merchantCode: string;
+    /** Use the UAT endpoints (default `true`). UAT and production issue separate credentials. */
+    sandbox?: boolean | undefined;
+    /** Overrides the API base URL, e.g. to go through a proxy. */
+    apiUrl?: string | undefined;
+    /** Overrides the PWA checkout URL. A trailing `#` or `#/` is normalized to `#/`. */
+    pwaUrl?: string | undefined;
+}
+/**
+ * KBZ Pay credentials and endpoints. A missing credential throws a `ConfigurationError`.
+ */
+export declare class KbzPayConfig {
+    static readonly SANDBOX_API_URL = "http://api-uat.kbzpay.com/payment/gateway/uat";
+    static readonly PRODUCTION_API_URL = "https://api.kbzpay.com/payment/gateway";
+    static readonly SANDBOX_PWA_URL = "https://static.kbzpay.com/pgw/uat/pwa/#/";
+    static readonly PRODUCTION_PWA_URL = "https://wap.kbzpay.com/pgw/pwa/#/";
+    readonly appId: string;
+    readonly appKey: string;
+    readonly merchantCode: string;
+    readonly sandbox: boolean;
+    /** The API base URL in use. */
+    readonly apiUrl: string;
+    /** The PWA checkout URL in use, always ending in `/`. */
+    readonly pwaUrl: string;
+    constructor(options: KbzPayConfigOptions);
+    /**
+     * Reads `KBZ_PAY_APP_ID`, `KBZ_PAY_APP_KEY`, `KBZ_PAY_MERCHANT_CODE`, `KBZ_PAY_SANDBOX`,
+     * `KBZ_PAY_BASE_URL` and `KBZ_PAY_PWA_BASE_REDIRECT_URL`.
+     */
+    static fromEnv(env?: EnvSource): KbzPayConfig;
+}
+/**
+ * A KBZ Pay order, used for the PWA, QR and in-app flows alike. KBZ Pay only accepts MMK.
+ */
+export interface KbzPayPaymentData {
+    /** Your unique order id (`merch_order_id`): letters, digits and `_` only, at most 40. */
+    orderId: string;
+    /** Kyat, greater than 0 with at most 2 decimal places, e.g. `Amount.kyat(1000)` or `Amount.parse('1000.50')`. */
+    amount: AmountInput;
+    /** The public URL KBZ posts the result to (`notify_url`): at most 512 characters, no query string. */
+    callbackUrl: string;
+    /** The product name shown to the customer. */
+    title?: string | undefined;
+    /** How long the order stays payable, 1 to 120 minutes. KBZ defaults to 120. */
+    timeoutMinutes?: number | undefined;
+    /** Free text KBZ sends back unchanged in the callback, at most 512 characters once URL-encoded. */
+    callbackInfo?: string | undefined;
+}
+/**
+ * KBZ Pay: PWA (redirect), QR and in-app payments, order status queries and payment
+ * notifications.
+ */
+export declare class KbzPay {
+    /** The configuration in use. */
+    readonly config: KbzPayConfig;
+    /** KBZ Pay's request signer, for custom calls. */
+    readonly signer: KbzPaySigner;
+    private readonly transport;
+    constructor(config: KbzPayConfig | KbzPayConfigOptions, options?: GatewayOptions);
+    /** A gateway configured from the `KBZ_PAY_*` environment variables. */
+    static fromEnv(env?: EnvSource, options?: GatewayOptions): KbzPay;
+    /** Checks the order against KBZ's documented limits; throws an `InvalidPaymentDataError`. */
+    static validate(data: KbzPayPaymentData): void;
+    /**
+     * Creates an order and returns the KBZ Pay PWA checkout URL to redirect the customer to.
+     *
+     * The redirect only works on a phone with the KBZ Pay app installed, and its Referer must match
+     * the URL registered with KBZ.
+     */
+    pwa(data: KbzPayPaymentData, options?: RequestOptions): Promise<RedirectPayment>;
+    /** Creates an order and returns a QR payload for the customer to scan with the KBZ Pay app. */
+    qr(data: KbzPayPaymentData, options?: RequestOptions): Promise<QrPayment>;
+    /**
+     * Creates an order and returns the signed values your mobile app passes to `KBZPay.startPay()`.
+     * The SDK's own result only means the payment screen closed; rely on the callback or `status()`.
+     */
+    app(data: KbzPayPaymentData, options?: RequestOptions): Promise<AppPayment>;
+    /** Asks KBZ Pay for the current state of an order (`queryorder`). */
+    status(orderId: string, options?: RequestOptions): Promise<PaymentStatusResult>;
+    /**
+     * Verifies KBZ Pay's payment notification. Reply with the callback's `acknowledgement` (plain
+     * `success`) or KBZ retries.
+     */
+    handleCallback(request: CallbackRequest): PaymentCallback;
+    private precreate;
+    /** Sends a signed request and returns the `Response` object, throwing when KBZ reports an error. */
+    private call;
+    private orderInfoFields;
+}

package/dist/esm/kbz-pay/kbz-pay.js

@@ -0,0 +1,262 @@
+import {} from '../core/amount.js';
+import { Acknowledgement, CallbackRequest, losslessBody, PaymentCallback, PaymentStatusResult, } from '../core/callback.js';
+import { queryEscape, randomHex } from '../core/crypto.js';
+import { defaultEnv, envFirst, envSandbox, optionalSetting, requireSetting, trimUrl, } from '../core/env.js';
+import { ApiError, SignatureVerificationError } from '../core/errors.js';
+import { httpClientFrom, Transport, } from '../core/http.js';
+import { toPlainObject } from '../core/json.js';
+import { AppPayment, QrPayment, RedirectPayment } from '../core/results.js';
+import { resolveStatus } from '../core/status.js';
+import { toAmount, Validator } from '../core/validate.js';
+import { get, object, optional, trimmed } from '../core/values.js';
+import { KbzPaySigner } from './signer.js';
+/**
+ * KBZ Pay credentials and endpoints. A missing credential throws a `ConfigurationError`.
+ */
+export class KbzPayConfig {
+    static SANDBOX_API_URL = 'http://api-uat.kbzpay.com/payment/gateway/uat';
+    static PRODUCTION_API_URL = 'https://api.kbzpay.com/payment/gateway';
+    static SANDBOX_PWA_URL = 'https://static.kbzpay.com/pgw/uat/pwa/#/';
+    static PRODUCTION_PWA_URL = 'https://wap.kbzpay.com/pgw/pwa/#/';
+    appId;
+    appKey;
+    merchantCode;
+    sandbox;
+    /** The API base URL in use. */
+    apiUrl;
+    /** The PWA checkout URL in use, always ending in `/`. */
+    pwaUrl;
+    constructor(options) {
+        this.appId = requireSetting('kbz_pay', 'app_id', options.appId);
+        this.appKey = requireSetting('kbz_pay', 'app_key', options.appKey);
+        this.merchantCode = requireSetting('kbz_pay', 'merchant_code', options.merchantCode);
+        this.sandbox = options.sandbox ?? true;
+        this.apiUrl = trimUrl(optionalSetting(options.apiUrl) ??
+            (this.sandbox ? KbzPayConfig.SANDBOX_API_URL : KbzPayConfig.PRODUCTION_API_URL));
+        this.pwaUrl = `${trimUrl(optionalSetting(options.pwaUrl) ??
+            (this.sandbox ? KbzPayConfig.SANDBOX_PWA_URL : KbzPayConfig.PRODUCTION_PWA_URL))}/`;
+    }
+    /**
+     * Reads `KBZ_PAY_APP_ID`, `KBZ_PAY_APP_KEY`, `KBZ_PAY_MERCHANT_CODE`, `KBZ_PAY_SANDBOX`,
+     * `KBZ_PAY_BASE_URL` and `KBZ_PAY_PWA_BASE_REDIRECT_URL`.
+     */
+    static fromEnv(env = defaultEnv()) {
+        return new KbzPayConfig({
+            appId: envFirst(env, 'KBZ_PAY_APP_ID'),
+            appKey: envFirst(env, 'KBZ_PAY_APP_KEY'),
+            merchantCode: envFirst(env, 'KBZ_PAY_MERCHANT_CODE'),
+            sandbox: envSandbox(env, 'KBZ_PAY_SANDBOX'),
+            apiUrl: envFirst(env, 'KBZ_PAY_BASE_URL'),
+            pwaUrl: envFirst(env, 'KBZ_PAY_PWA_BASE_REDIRECT_URL'),
+        });
+    }
+}
+const ORDER_ID = /^[A-Za-z0-9_]+$/;
+const STATUSES = {
+    PAY_SUCCESS: 'successful',
+    WAIT_PAY: 'pending',
+    PAYING: 'pending',
+    PAY_FAILED: 'failed',
+    ORDER_CLOSED: 'cancelled',
+    ORDER_EXPIRED: 'expired',
+};
+/**
+ * KBZ Pay: PWA (redirect), QR and in-app payments, order status queries and payment
+ * notifications.
+ */
+export class KbzPay {
+    /** The configuration in use. */
+    config;
+    /** KBZ Pay's request signer, for custom calls. */
+    signer;
+    transport;
+    constructor(config, options = {}) {
+        this.config = config instanceof KbzPayConfig ? config : new KbzPayConfig(config);
+        this.signer = new KbzPaySigner(this.config.appKey);
+        this.transport = new Transport(httpClientFrom(options));
+    }
+    /** A gateway configured from the `KBZ_PAY_*` environment variables. */
+    static fromEnv(env = defaultEnv(), options = {}) {
+        return new KbzPay(KbzPayConfig.fromEnv(env), options);
+    }
+    /** Checks the order against KBZ's documented limits; throws an `InvalidPaymentDataError`. */
+    static validate(data) {
+        const callbackUrl = typeof data.callbackUrl === 'string' ? data.callbackUrl : '';
+        new Validator()
+            .required('orderId', data.orderId)
+            .max('orderId', data.orderId, 40)
+            .pattern('orderId', data.orderId, ORDER_ID, 'letters, numbers and underscores')
+            .amount('amount', data.amount, { gateway: 'KBZ Pay', maxDecimals: 2 })
+            .required('callbackUrl', data.callbackUrl)
+            .url('callbackUrl', callbackUrl)
+            .max('callbackUrl', callbackUrl, 512)
+            .when(callbackUrl.includes('?'), 'callbackUrl', 'The callbackUrl field must not contain a query string.')
+            .string('title', data.title)
+            .between('timeoutMinutes', data.timeoutMinutes, 1, 120)
+            .string('callbackInfo', data.callbackInfo)
+            .max('callbackInfo', typeof data.callbackInfo === 'string' ? queryEscape(data.callbackInfo) : undefined, 512)
+            .validate();
+    }
+    /**
+     * Creates an order and returns the KBZ Pay PWA checkout URL to redirect the customer to.
+     *
+     * The redirect only works on a phone with the KBZ Pay app installed, and its Referer must match
+     * the URL registered with KBZ.
+     */
+    async pwa(data, options = {}) {
+        const order = await this.precreate(data, 'PWAAPP', options);
+        const fields = this.orderInfoFields(order);
+        return new RedirectPayment({
+            orderId: data.orderId,
+            url: `${this.config.pwaUrl}?${this.signer.signString(fields)}&sign=${this.signer.sign(fields)}`,
+            gatewayReference: order.prepayId,
+            raw: toPlainObject(order.response),
+        });
+    }
+    /** Creates an order and returns a QR payload for the customer to scan with the KBZ Pay app. */
+    async qr(data, options = {}) {
+        const order = await this.precreate(data, 'PAY_BY_QRCODE', options);
+        const qrCode = get(order.response, 'qrCode');
+        if (qrCode === '') {
+            throw new ApiError('KBZ Pay did not return a QR code.', {
+                raw: toPlainObject(order.response),
+            });
+        }
+        return new QrPayment({
+            orderId: data.orderId,
+            qrString: qrCode,
+            expiresAt: data.timeoutMinutes === undefined
+                ? undefined
+                : new Date(Date.now() + data.timeoutMinutes * 60_000),
+            reference: order.prepayId,
+            raw: toPlainObject(order.response),
+        });
+    }
+    /**
+     * Creates an order and returns the signed values your mobile app passes to `KBZPay.startPay()`.
+     * The SDK's own result only means the payment screen closed; rely on the callback or `status()`.
+     */
+    async app(data, options = {}) {
+        const order = await this.precreate(data, 'APP', options);
+        const fields = this.orderInfoFields(order);
+        return new AppPayment({
+            orderId: data.orderId,
+            orderInfo: this.signer.signString(fields),
+            sign: this.signer.sign(fields),
+            signType: 'SHA256',
+            raw: toPlainObject(order.response),
+        });
+    }
+    /** Asks KBZ Pay for the current state of an order (`queryorder`). */
+    async status(orderId, options = {}) {
+        const response = await this.call('queryorder', 'kbz.payment.queryorder', '3.0', {
+            appid: this.config.appId,
+            merch_code: this.config.merchantCode,
+            merch_order_id: orderId,
+        }, {}, randomHex(), timestamp(), options.signal);
+        const tradeStatus = trimmed(response, 'trade_status');
+        return new PaymentStatusResult({
+            orderId: optional(response, 'merch_order_id') || orderId,
+            status: resolveStatus(STATUSES, tradeStatus),
+            gatewayStatus: tradeStatus,
+            gatewayReference: optional(response, 'mm_order_id'),
+            amount: optional(response, 'total_amount'),
+            raw: toPlainObject(response),
+        });
+    }
+    /**
+     * Verifies KBZ Pay's payment notification. Reply with the callback's `acknowledgement` (plain
+     * `success`) or KBZ retries.
+     */
+    handleCallback(request) {
+        const input = losslessBody(request);
+        const fields = object(input, 'Request') ?? input;
+        if (!this.signer.verify(fields)) {
+            throw new SignatureVerificationError('KBZ Pay callback signature verification failed.', toPlainObject(input));
+        }
+        const tradeStatus = trimmed(fields, 'trade_status');
+        return new PaymentCallback({
+            orderId: get(fields, 'merch_order_id'),
+            status: resolveStatus(STATUSES, tradeStatus),
+            gatewayStatus: tradeStatus,
+            gatewayReference: optional(fields, 'mm_order_id'),
+            amount: optional(fields, 'total_amount'),
+            raw: toPlainObject(fields),
+            acknowledgement: new Acknowledgement({ body: 'success' }),
+        });
+    }
+    async precreate(data, tradeType, options) {
+        KbzPay.validate(data);
+        const biz = {
+            appid: this.config.appId,
+            merch_code: this.config.merchantCode,
+            merch_order_id: data.orderId,
+            trade_type: tradeType,
+            total_amount: String(toAmount(data.amount)),
+            trans_currency: 'MMK',
+        };
+        if (data.title) {
+            biz.title = data.title;
+        }
+        if (data.timeoutMinutes !== undefined) {
+            biz.timeout_express = `${data.timeoutMinutes}m`;
+        }
+        if (data.callbackInfo) {
+            biz.callback_info = queryEscape(data.callbackInfo);
+        }
+        const nonce = randomHex();
+        const time = timestamp();
+        const response = await this.call('precreate', 'kbz.payment.precreate', '1.0', biz, { notify_url: data.callbackUrl }, nonce, time, options.signal);
+        const prepayId = get(response, 'prepay_id');
+        if (prepayId === '') {
+            throw new ApiError('KBZ Pay did not return a prepay_id.', { raw: toPlainObject(response) });
+        }
+        return { prepayId, nonce, timestamp: time, response };
+    }
+    /** Sends a signed request and returns the `Response` object, throwing when KBZ reports an error. */
+    async call(endpoint, method, version, biz, extra, nonce, time, signal) {
+        const common = {
+            timestamp: time,
+            method,
+            nonce_str: nonce,
+            version,
+            ...extra,
+        };
+        const request = {
+            ...common,
+            sign_type: 'SHA256',
+            sign: this.signer.sign({ ...common, ...biz }),
+            biz_content: biz,
+        };
+        const response = await this.transport.postJson(`${this.config.apiUrl}/${endpoint}`, { Request: request }, {}, signal);
+        const body = response.json();
+        const result = object(body, 'Response') ?? {};
+        if (!response.successful() ||
+            get(result, 'result') !== 'SUCCESS' ||
+            get(result, 'code') !== '0') {
+            const code = optional(result, 'code');
+            const message = optional(result, 'msg');
+            throw new ApiError(code
+                ? `KBZ Pay ${endpoint} failed: [${code}] ${message ?? ''}`.trimEnd()
+                : `KBZ Pay ${endpoint} failed with HTTP ${response.status}.`, {
+                gatewayCode: code,
+                gatewayMessage: message,
+                httpStatus: response.status,
+                raw: toPlainObject(body),
+            });
+        }
+        return result;
+    }
+    orderInfoFields(order) {
+        return {
+            appid: this.config.appId,
+            merch_code: this.config.merchantCode,
+            nonce_str: order.nonce,
+            prepay_id: order.prepayId,
+            timestamp: order.timestamp,
+        };
+    }
+}
+function timestamp() {
+    return String(Math.floor(Date.now() / 1000));
+}