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

package/dist/esm/core/callback.d.ts

@@ -0,0 +1,180 @@
+import { type LosslessObject } from './json.js';
+import type { PaymentStatus } from './status.js';
+/** Headers as a Fetch `Headers`, a Node-style object or `[name, value]` pairs. */
+export type HeadersInput = Headers | Readonly<Record<string, string | readonly string[] | undefined>> | Iterable<readonly [string, string]>;
+/** A query string, `URLSearchParams` or an object of values. */
+export type QueryInput = string | URLSearchParams | Readonly<Record<string, string | readonly string[] | undefined>>;
+/** A request body: text or raw bytes (a `Buffer` works). */
+export type BodyInput = string | Uint8Array | ArrayBuffer;
+/** The parts of a gateway request. */
+export interface CallbackRequestInit {
+    /** The raw request body exactly as received. */
+    body?: BodyInput | null | undefined;
+    /** The request headers. */
+    headers?: HeadersInput | null | undefined;
+    /** The query string parameters. */
+    query?: QueryInput | null | undefined;
+}
+/**
+ * The parts of a Node `http.IncomingMessage` this package reads, so Express, Fastify (`request.raw`)
+ * and Koa (`ctx.req`) requests work too.
+ */
+export interface NodeRequestLike extends AsyncIterable<unknown> {
+    headers: Readonly<Record<string, string | readonly string[] | undefined>>;
+    url?: string | undefined;
+    /** A raw body captured by middleware, e.g. `express.raw()` or a `verify` hook. */
+    rawBody?: unknown;
+    /** A body parsed by middleware. Used only when the stream was already consumed. */
+    body?: unknown;
+}
+/** The parts of a Fetch API `Request` this package reads. */
+export interface WebRequestLike {
+    readonly url: string;
+    readonly headers: Headers;
+    readonly bodyUsed: boolean;
+    clone(): {
+        text(): Promise<string>;
+    };
+}
+/**
+ * An incoming request from a gateway (a server callback or a browser return). Signatures are
+ * verified against what the gateway actually sent, so build it from the real request with
+ * {@link CallbackRequest.fromNodeRequest} or {@link CallbackRequest.fromWebRequest}.
+ */
+export declare class CallbackRequest {
+    /** The raw request body, decoded as UTF-8. */
+    readonly body: string;
+    /** The request headers, with lowercase names. Repeated headers are joined with `, `. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** The query string parameters (the first value of each). */
+    readonly query: Readonly<Record<string, string>>;
+    constructor(init?: CallbackRequestInit);
+    /** Builds a request from its parts, e.g. to replay a stored callback. */
+    static from(init: CallbackRequestInit): CallbackRequest;
+    /**
+     * Builds a request from a decoded payload, encoded as a JSON body, e.g. to replay a callback
+     * stored as JSON.
+     */
+    static fromJson(payload: unknown, headers?: HeadersInput | null): CallbackRequest;
+    /**
+     * Reads a Node `http.IncomingMessage` (also Express `req`, Fastify `request.raw`, Koa `ctx.req`).
+     * Reads the raw body from the stream, or from `rawBody`/`body` when middleware captured it as
+     * text or bytes. When a body parser already consumed the stream, the parsed `body` is encoded
+     * again as JSON or a form.
+     */
+    static fromNodeRequest(request: NodeRequestLike): Promise<CallbackRequest>;
+    /**
+     * Reads a Fetch API `Request` (Next.js route handlers, Hono, Bun, Deno, Cloudflare Workers). The
+     * body is read from a clone, so the request stays readable.
+     */
+    static fromWebRequest(request: WebRequestLike): Promise<CallbackRequest>;
+    /** The named header, matched case-insensitively, or `undefined`. */
+    header(name: string): string | undefined;
+    /** The body decoded as JSON or as a urlencoded form. */
+    parsedBody(): Record<string, unknown>;
+    /** The parsed body merged over the query string. */
+    input(): Record<string, unknown>;
+    /** The query string merged over the parsed body. */
+    queryInput(): Record<string, unknown>;
+}
+/** The body as JSON (numbers kept exact) or a form, or `{}`. @internal */
+export declare function losslessBody(request: CallbackRequest): LosslessObject;
+/** @internal */
+export declare function losslessInput(request: CallbackRequest): LosslessObject;
+/** @internal */
+export declare function losslessQueryInput(request: CallbackRequest): LosslessObject;
+/** The headers, a status and a body a gateway expects after it delivers a callback. */
+export interface AcknowledgementInit {
+    status?: number | undefined;
+    body?: string | undefined;
+    headers?: Readonly<Record<string, string>> | undefined;
+}
+/** The parts of a Node `http.ServerResponse` (or Express `res`) {@link Acknowledgement.send} uses. */
+export interface ServerResponseLike {
+    statusCode: number;
+    setHeader(name: string, value: string): unknown;
+    end(body?: string): unknown;
+}
+/**
+ * The HTTP response a gateway expects after it delivers a callback. Gateways retry until they
+ * receive it.
+ */
+export declare class Acknowledgement {
+    /** The HTTP status, 200 unless a gateway documents another. */
+    readonly status: number;
+    /** The response body, e.g. KBZ Pay's plain `success`. */
+    readonly body: string;
+    /** The response headers. */
+    readonly headers: Readonly<Record<string, string>>;
+    constructor(init?: AcknowledgementInit);
+    /** An empty `200 text/plain` response, which most gateways expect. */
+    static default(): Acknowledgement;
+    /** Writes the acknowledgement to a Node `http.ServerResponse` (or Express `res`) and ends it. */
+    send(response: ServerResponseLike): void;
+    /** The acknowledgement as a Fetch API `Response`, for Next.js, Hono, Bun and other Fetch servers. */
+    toResponse(): Response;
+}
+/** The fields of a {@link PaymentCallback}. */
+export interface PaymentCallbackInit {
+    orderId: string;
+    status: PaymentStatus;
+    gatewayStatus: string;
+    gatewayReference?: string | undefined;
+    amount?: string | undefined;
+    raw?: Readonly<Record<string, unknown>> | undefined;
+    acknowledgement?: Acknowledgement | undefined;
+}
+/**
+ * A gateway notification whose signature has been verified.
+ *
+ * Always compare `amount` with your order before fulfilling it, and handle duplicates: gateways
+ * retry.
+ */
+export declare class PaymentCallback {
+    /** Your order id. */
+    readonly orderId: string;
+    /** The status mapped onto this package's statuses. */
+    readonly status: PaymentStatus;
+    /** The gateway's own status value, unmapped. */
+    readonly gatewayStatus: string;
+    /** The gateway's id for the payment, when it sends one. */
+    readonly gatewayReference: string | undefined;
+    /** The amount the gateway reports, exactly as it sent it, when it sends one. */
+    readonly amount: string | undefined;
+    /** The verified payload. */
+    readonly raw: Readonly<Record<string, unknown>>;
+    /** The response to send so the gateway stops retrying. */
+    readonly acknowledgement: Acknowledgement;
+    constructor(init: PaymentCallbackInit);
+    /** Whether the customer paid. */
+    isSuccessful(): boolean;
+}
+/** The fields of a {@link PaymentStatusResult}. */
+export interface PaymentStatusResultInit {
+    orderId?: string | undefined;
+    status: PaymentStatus;
+    gatewayStatus: string;
+    gatewayReference?: string | undefined;
+    amount?: string | undefined;
+    raw?: Readonly<Record<string, unknown>> | undefined;
+}
+/**
+ * The state of a payment as reported by a gateway's status API.
+ */
+export declare class PaymentStatusResult {
+    /** Your order id, when the gateway returns it. */
+    readonly orderId: string | undefined;
+    /** The status mapped onto this package's statuses. */
+    readonly status: PaymentStatus;
+    /** The gateway's own status value, unmapped. */
+    readonly gatewayStatus: string;
+    /** The gateway's id for the payment, when it sends one. */
+    readonly gatewayReference: string | undefined;
+    /** The amount the gateway reports, exactly as it sent it, when it sends one. */
+    readonly amount: string | undefined;
+    /** The gateway's response, for logging. */
+    readonly raw: Readonly<Record<string, unknown>>;
+    constructor(init: PaymentStatusResultInit);
+    /** Whether the customer paid. */
+    isSuccessful(): boolean;
+}

package/dist/esm/core/callback.js

@@ -0,0 +1,294 @@
+import { parseJsonObject, setKey, toPlainObject } from './json.js';
+/**
+ * An incoming request from a gateway (a server callback or a browser return). Signatures are
+ * verified against what the gateway actually sent, so build it from the real request with
+ * {@link CallbackRequest.fromNodeRequest} or {@link CallbackRequest.fromWebRequest}.
+ */
+export class CallbackRequest {
+    /** The raw request body, decoded as UTF-8. */
+    body;
+    /** The request headers, with lowercase names. Repeated headers are joined with `, `. */
+    headers;
+    /** The query string parameters (the first value of each). */
+    query;
+    constructor(init = {}) {
+        this.body = bodyText(init.body);
+        this.headers = Object.freeze(normalizeHeaders(init.headers));
+        this.query = Object.freeze(normalizeQuery(init.query));
+    }
+    /** Builds a request from its parts, e.g. to replay a stored callback. */
+    static from(init) {
+        return new CallbackRequest(init);
+    }
+    /**
+     * Builds a request from a decoded payload, encoded as a JSON body, e.g. to replay a callback
+     * stored as JSON.
+     */
+    static fromJson(payload, headers) {
+        return new CallbackRequest({
+            body: JSON.stringify(payload),
+            headers: { ...normalizeHeaders(headers), 'content-type': 'application/json' },
+        });
+    }
+    /**
+     * Reads a Node `http.IncomingMessage` (also Express `req`, Fastify `request.raw`, Koa `ctx.req`).
+     * Reads the raw body from the stream, or from `rawBody`/`body` when middleware captured it as
+     * text or bytes. When a body parser already consumed the stream, the parsed `body` is encoded
+     * again as JSON or a form.
+     */
+    static async fromNodeRequest(request) {
+        const headers = normalizeHeaders(request.headers);
+        const query = new URL(request.url ?? '/', 'http://localhost').searchParams;
+        let body = rawBody(request.rawBody) ?? rawBody(request.body);
+        if (body === undefined) {
+            const chunks = [];
+            for await (const chunk of request) {
+                chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+            }
+            body = Buffer.concat(chunks);
+            if (body.length === 0 && isPlainObject(request.body)) {
+                body = encodeParsedBody(request.body, headers['content-type'] ?? '');
+            }
+        }
+        return new CallbackRequest({ body, headers, query });
+    }
+    /**
+     * Reads a Fetch API `Request` (Next.js route handlers, Hono, Bun, Deno, Cloudflare Workers). The
+     * body is read from a clone, so the request stays readable.
+     */
+    static async fromWebRequest(request) {
+        return new CallbackRequest({
+            body: request.bodyUsed ? '' : await request.clone().text(),
+            headers: request.headers,
+            query: new URL(request.url).searchParams,
+        });
+    }
+    /** The named header, matched case-insensitively, or `undefined`. */
+    header(name) {
+        return this.headers[name.toLowerCase()];
+    }
+    /** The body decoded as JSON or as a urlencoded form. */
+    parsedBody() {
+        return toPlainObject(losslessBody(this));
+    }
+    /** The parsed body merged over the query string. */
+    input() {
+        return toPlainObject(losslessInput(this));
+    }
+    /** The query string merged over the parsed body. */
+    queryInput() {
+        return toPlainObject(losslessQueryInput(this));
+    }
+}
+/** The body as JSON (numbers kept exact) or a form, or `{}`. @internal */
+export function losslessBody(request) {
+    const body = request.body.trim();
+    if (body === '') {
+        return {};
+    }
+    const json = parseJsonObject(body);
+    if (json !== undefined) {
+        return json;
+    }
+    return firstValues(new URLSearchParams(body));
+}
+/** @internal */
+export function losslessInput(request) {
+    return merge({ ...request.query }, losslessBody(request));
+}
+/** @internal */
+export function losslessQueryInput(request) {
+    return merge(losslessBody(request), request.query);
+}
+function merge(target, source) {
+    const result = {};
+    for (const object of [target, source]) {
+        for (const key of Object.keys(object)) {
+            setKey(result, key, object[key]);
+        }
+    }
+    return result;
+}
+/**
+ * The HTTP response a gateway expects after it delivers a callback. Gateways retry until they
+ * receive it.
+ */
+export class Acknowledgement {
+    /** The HTTP status, 200 unless a gateway documents another. */
+    status;
+    /** The response body, e.g. KBZ Pay's plain `success`. */
+    body;
+    /** The response headers. */
+    headers;
+    constructor(init = {}) {
+        this.status = init.status ?? 200;
+        this.body = init.body ?? '';
+        this.headers = Object.freeze({ ...(init.headers ?? { 'Content-Type': 'text/plain' }) });
+    }
+    /** An empty `200 text/plain` response, which most gateways expect. */
+    static default() {
+        return new Acknowledgement();
+    }
+    /** Writes the acknowledgement to a Node `http.ServerResponse` (or Express `res`) and ends it. */
+    send(response) {
+        response.statusCode = this.status;
+        for (const [name, value] of Object.entries(this.headers)) {
+            response.setHeader(name, value);
+        }
+        response.end(this.body);
+    }
+    /** The acknowledgement as a Fetch API `Response`, for Next.js, Hono, Bun and other Fetch servers. */
+    toResponse() {
+        return new Response(this.body, { status: this.status, headers: { ...this.headers } });
+    }
+}
+/**
+ * A gateway notification whose signature has been verified.
+ *
+ * Always compare `amount` with your order before fulfilling it, and handle duplicates: gateways
+ * retry.
+ */
+export class PaymentCallback {
+    /** Your order id. */
+    orderId;
+    /** The status mapped onto this package's statuses. */
+    status;
+    /** The gateway's own status value, unmapped. */
+    gatewayStatus;
+    /** The gateway's id for the payment, when it sends one. */
+    gatewayReference;
+    /** The amount the gateway reports, exactly as it sent it, when it sends one. */
+    amount;
+    /** The verified payload. */
+    raw;
+    /** The response to send so the gateway stops retrying. */
+    acknowledgement;
+    constructor(init) {
+        this.orderId = init.orderId;
+        this.status = init.status;
+        this.gatewayStatus = init.gatewayStatus;
+        this.gatewayReference = init.gatewayReference;
+        this.amount = init.amount;
+        this.raw = init.raw ?? {};
+        this.acknowledgement = init.acknowledgement ?? Acknowledgement.default();
+    }
+    /** Whether the customer paid. */
+    isSuccessful() {
+        return this.status === 'successful';
+    }
+}
+/**
+ * The state of a payment as reported by a gateway's status API.
+ */
+export class PaymentStatusResult {
+    /** Your order id, when the gateway returns it. */
+    orderId;
+    /** The status mapped onto this package's statuses. */
+    status;
+    /** The gateway's own status value, unmapped. */
+    gatewayStatus;
+    /** The gateway's id for the payment, when it sends one. */
+    gatewayReference;
+    /** The amount the gateway reports, exactly as it sent it, when it sends one. */
+    amount;
+    /** The gateway's response, for logging. */
+    raw;
+    constructor(init) {
+        this.orderId = init.orderId;
+        this.status = init.status;
+        this.gatewayStatus = init.gatewayStatus;
+        this.gatewayReference = init.gatewayReference;
+        this.amount = init.amount;
+        this.raw = init.raw ?? {};
+    }
+    /** Whether the customer paid. */
+    isSuccessful() {
+        return this.status === 'successful';
+    }
+}
+function bodyText(body) {
+    if (body === undefined || body === null) {
+        return '';
+    }
+    if (typeof body === 'string') {
+        return body;
+    }
+    return new TextDecoder().decode(body);
+}
+function rawBody(value) {
+    if (typeof value === 'string' || value instanceof Uint8Array || value instanceof ArrayBuffer) {
+        return value;
+    }
+    return undefined;
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function encodeParsedBody(body, contentType) {
+    if (!contentType.toLowerCase().includes('urlencoded')) {
+        return JSON.stringify(body);
+    }
+    const form = new URLSearchParams();
+    for (const [key, value] of Object.entries(body)) {
+        for (const item of Array.isArray(value) ? value : [value]) {
+            form.append(key, String(item));
+        }
+    }
+    return form.toString();
+}
+function normalizeHeaders(headers) {
+    const result = {};
+    if (headers === undefined || headers === null) {
+        return result;
+    }
+    const add = (name, value) => {
+        if (value === undefined) {
+            return;
+        }
+        const text = typeof value === 'string' ? value : value.join(', ');
+        const key = name.toLowerCase();
+        setKey(result, key, result[key] === undefined ? text : `${result[key]}, ${text}`);
+    };
+    if (typeof headers.forEach === 'function' &&
+        typeof headers.get === 'function') {
+        headers.forEach((value, name) => {
+            add(name, value);
+        });
+    }
+    else if (Symbol.iterator in headers) {
+        for (const [name, value] of headers) {
+            add(name, value);
+        }
+    }
+    else {
+        for (const [name, value] of Object.entries(headers)) {
+            add(name, value);
+        }
+    }
+    return result;
+}
+function normalizeQuery(query) {
+    if (query === undefined || query === null) {
+        return {};
+    }
+    if (typeof query === 'string' || query instanceof URLSearchParams) {
+        return firstValues(new URLSearchParams(query));
+    }
+    const result = {};
+    for (const [key, value] of Object.entries(query)) {
+        const first = typeof value === 'string' ? value : value?.[0];
+        if (first !== undefined) {
+            setKey(result, key, first);
+        }
+    }
+    return result;
+}
+function firstValues(params) {
+    const result = {};
+    for (const [key, value] of params) {
+        if (!Object.prototype.hasOwnProperty.call(result, key)) {
+            setKey(result, key, value);
+        }
+    }
+    return result;
+}

package/dist/esm/core/crypto.d.ts

@@ -0,0 +1,19 @@
+/** HMAC-SHA256 of `message`, hex encoded. @internal */
+export declare function hmacSha256Hex(key: string, message: string): string;
+/** HMAC-SHA256 of `message`, base64 encoded. @internal */
+export declare function hmacSha256Base64(key: string, message: string): string;
+/** SHA-256 of `message`, hex encoded. @internal */
+export declare function sha256Hex(message: string): string;
+/** Compares two strings in constant time (for equal lengths). @internal */
+export declare function safeEqual(expected: string, actual: string): boolean;
+/** `bytes` random bytes, hex encoded. @internal */
+export declare function randomHex(bytes?: number): string;
+/**
+ * Escapes text like Go's `url.QueryEscape` and PHP's `urlencode`: everything except letters,
+ * digits and `-_.~` is percent-encoded and spaces become `+`.
+ *
+ * @internal
+ */
+export declare function queryEscape(value: string): string;
+/** Decodes strict standard base64 (with padding), or `undefined`. @internal */
+export declare function decodeBase64(value: string): string | undefined;

package/dist/esm/core/crypto.js

@@ -0,0 +1,41 @@
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+/** HMAC-SHA256 of `message`, hex encoded. @internal */
+export function hmacSha256Hex(key, message) {
+    return createHmac('sha256', key).update(message, 'utf8').digest('hex');
+}
+/** HMAC-SHA256 of `message`, base64 encoded. @internal */
+export function hmacSha256Base64(key, message) {
+    return createHmac('sha256', key).update(message, 'utf8').digest('base64');
+}
+/** SHA-256 of `message`, hex encoded. @internal */
+export function sha256Hex(message) {
+    return createHash('sha256').update(message, 'utf8').digest('hex');
+}
+/** Compares two strings in constant time (for equal lengths). @internal */
+export function safeEqual(expected, actual) {
+    const a = Buffer.from(expected, 'utf8');
+    const b = Buffer.from(actual, 'utf8');
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+/** `bytes` random bytes, hex encoded. @internal */
+export function randomHex(bytes = 16) {
+    return randomBytes(bytes).toString('hex');
+}
+/**
+ * Escapes text like Go's `url.QueryEscape` and PHP's `urlencode`: everything except letters,
+ * digits and `-_.~` is percent-encoded and spaces become `+`.
+ *
+ * @internal
+ */
+export function queryEscape(value) {
+    return encodeURIComponent(value)
+        .replace(/[!'()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`)
+        .replace(/%20/g, '+');
+}
+/** Decodes strict standard base64 (with padding), or `undefined`. @internal */
+export function decodeBase64(value) {
+    if (value === '' || value.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(value)) {
+        return undefined;
+    }
+    return Buffer.from(value, 'base64').toString('utf8');
+}

package/dist/esm/core/env.d.ts

@@ -0,0 +1,21 @@
+/** Environment variables, e.g. `process.env`. */
+export type EnvSource = Readonly<Record<string, string | undefined>>;
+/** The first non-empty value among `keys`, trimmed, or `''`. @internal */
+export declare function envFirst(env: EnvSource, ...keys: string[]): string;
+/**
+ * Reads a `*_SANDBOX` variable. Only `false`, `0`, `f`, `no` and `off` (any case) select
+ * production; unset or unrecognized values mean sandbox.
+ *
+ * @internal
+ */
+export declare function envSandbox(env: EnvSource, key: string): boolean;
+/** An integer variable, or `undefined` when unset or not an integer. @internal */
+export declare function envInt(env: EnvSource, key: string): number | undefined;
+/** The trimmed value, or throws a {@link ConfigurationError} naming `key`. @internal */
+export declare function requireSetting(gateway: string, key: string, value: unknown): string;
+/** A trimmed optional string, `undefined` when blank. @internal */
+export declare function optionalSetting(value: unknown): string | undefined;
+/** Removes trailing slashes. @internal */
+export declare function trimUrl(url: string): string;
+/** The default environment: `process.env`. @internal */
+export declare function defaultEnv(): EnvSource;

package/dist/esm/core/env.js

@@ -0,0 +1,45 @@
+import { ConfigurationError } from './errors.js';
+/** The first non-empty value among `keys`, trimmed, or `''`. @internal */
+export function envFirst(env, ...keys) {
+    for (const key of keys) {
+        const value = env[key]?.trim();
+        if (value) {
+            return value;
+        }
+    }
+    return '';
+}
+/**
+ * Reads a `*_SANDBOX` variable. Only `false`, `0`, `f`, `no` and `off` (any case) select
+ * production; unset or unrecognized values mean sandbox.
+ *
+ * @internal
+ */
+export function envSandbox(env, key) {
+    const value = env[key]?.trim().toLowerCase() ?? '';
+    return !['false', '0', 'f', 'no', 'off'].includes(value);
+}
+/** An integer variable, or `undefined` when unset or not an integer. @internal */
+export function envInt(env, key) {
+    const value = env[key]?.trim() ?? '';
+    return /^[+-]?\d+$/.test(value) ? Number.parseInt(value, 10) : undefined;
+}
+/** The trimmed value, or throws a {@link ConfigurationError} naming `key`. @internal */
+export function requireSetting(gateway, key, value) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new ConfigurationError(gateway, key);
+    }
+    return value;
+}
+/** A trimmed optional string, `undefined` when blank. @internal */
+export function optionalSetting(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+}
+/** Removes trailing slashes. @internal */
+export function trimUrl(url) {
+    return url.replace(/\/+$/, '');
+}
+/** The default environment: `process.env`. @internal */
+export function defaultEnv() {
+    return process.env;
+}

package/dist/esm/core/errors.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Base class of every error thrown by this package.
+ */
+export declare class PaymentError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when payment data has values the gateway would reject. Thrown before any request is sent.
+ */
+export declare class InvalidPaymentDataError extends PaymentError {
+    /** Field name to error message, e.g. `{ amount: 'The amount field is required.' }`. */
+    readonly errors: Readonly<Record<string, string>>;
+    constructor(errors: Record<string, string>);
+}
+/**
+ * Thrown when a gateway rejects a request or answers with an error, including errors sent with
+ * HTTP 200, or when it cannot be reached (the network error is the `cause`).
+ */
+export declare class ApiError extends PaymentError {
+    /** The gateway's own error code, e.g. `ORDER_ID_USED` or `09`. */
+    readonly gatewayCode: string | undefined;
+    /** The gateway's own error message. */
+    readonly gatewayMessage: string | undefined;
+    /** The HTTP status of the response, or `0` when no response was received. */
+    readonly httpStatus: number;
+    /** The decoded response body. */
+    readonly raw: Readonly<Record<string, unknown>>;
+    constructor(message: string, details?: {
+        gatewayCode?: string | undefined;
+        gatewayMessage?: string | undefined;
+        httpStatus?: number;
+        raw?: Record<string, unknown>;
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when a callback, return redirect or gateway response fails signature verification.
+ * Never act on its payload.
+ */
+export declare class SignatureVerificationError extends PaymentError {
+    /** The unverified payload, for logging only. */
+    readonly raw: Readonly<Record<string, unknown>>;
+    constructor(message: string, raw?: Record<string, unknown>);
+}
+/**
+ * Thrown when a gateway is missing a credential or setting it needs.
+ */
+export declare class ConfigurationError extends PaymentError {
+    /** The gateway, e.g. `kbz_pay`. */
+    readonly gateway: string;
+    /** The missing setting, e.g. `app_key`. */
+    readonly key: string;
+    constructor(gateway: string, key: string);
+}