@dpayglobal/dpay-node-sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,876 @@
+import { H as HttpClient, A as ApiResponse, a as ApiRequest } from './types-CGcSNriz.cjs';
+import { inspect } from 'node:util';
+
+type BaseUrlKey = 'apiPayments' | 'panel' | 'gateway';
+declare class BaseUrls {
+    private readonly urls;
+    constructor(overrides?: Readonly<Record<string, string>>);
+    resolve(host: BaseUrlKey): string;
+}
+
+/** Default HTTP timeout in milliseconds. */
+declare const DEFAULT_TIMEOUT = 30000;
+/** Per-call overrides accepted as the last argument of every service method. */
+interface RequestOptions {
+    /** Cancels the call. Combined with the configured timeout. */
+    signal?: AbortSignal;
+    /** Timeout for this call only, in milliseconds. */
+    timeout?: number;
+}
+/** What `onRequest` receives. Sensitive values are already redacted. */
+interface RequestHookContext {
+    readonly method: string;
+    readonly url: string;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: string | null;
+}
+/** What `onResponse` receives. */
+interface ResponseHookContext {
+    readonly status: number;
+    readonly url: string;
+    readonly body: string;
+}
+/** Options accepted by `new DPayClient(...)`. */
+interface DPayClientOptions {
+    /** Payment point name from panel.dpay.pl. */
+    service: string;
+    /** Secret Hash key from panel.dpay.pl. Never expose it to a browser. */
+    secretHash: string;
+    /** HTTP timeout in milliseconds. Defaults to 30000. */
+    timeout?: number;
+    /** Custom transport for proxying, retries or tests. */
+    httpClient?: HttpClient;
+    /** Overrides for the `apiPayments`, `panel` and `gateway` hosts. */
+    baseUrls?: Record<string, string>;
+    /** Called before every request, with the checksum and card data redacted. */
+    onRequest?: (context: RequestHookContext) => void;
+    /** Called after every response that reached the SDK. */
+    onResponse?: (context: ResponseHookContext) => void;
+}
+declare class Config {
+    readonly service: string;
+    readonly secretHash: string;
+    readonly timeout: number;
+    readonly httpClient: HttpClient | null;
+    readonly baseUrls: BaseUrls;
+    readonly onRequest: ((context: RequestHookContext) => void) | null;
+    readonly onResponse: ((context: ResponseHookContext) => void) | null;
+    private constructor();
+    static fromOptions(options: DPayClientOptions): Config;
+}
+
+declare class ChecksumCalculator {
+    private readonly secretHash;
+    constructor(secretHash: string);
+    secretSecond(service: string, fields: readonly unknown[]): string;
+    orderedBody(values: readonly unknown[]): string;
+}
+
+interface Operation<T> {
+    readonly method: 'GET' | 'POST';
+    readonly host: BaseUrlKey;
+    readonly path: string;
+    readonly parse: (response: ApiResponse) => T;
+    readonly body?: Record<string, unknown>;
+    readonly raiseForStatus?: boolean;
+}
+
+declare class ApiRequestor {
+    readonly service: string;
+    readonly checksum: ChecksumCalculator;
+    private readonly config;
+    private readonly httpClient;
+    constructor(config: Config, httpClient: HttpClient);
+    execute<T>(operation: Operation<T>, options?: RequestOptions): Promise<T>;
+    private buildRequest;
+    private resolveSignal;
+    private notify;
+}
+
+/** A bank offered on the transfer payment page. */
+interface Bank {
+    readonly id: string;
+    readonly name: string;
+    /** Logo file name, when the API provides one. */
+    readonly image: string | null;
+    /** First hour of the day the bank accepts transfers. */
+    readonly onFrom: number;
+    /** Last hour of the day the bank accepts transfers. */
+    readonly onTo: number;
+    readonly iterator: number | null;
+    readonly isTest: boolean;
+    readonly type: string | null;
+    readonly raw: Record<string, unknown>;
+}
+
+/** Lists the banks dpay supports for transfer payments. */
+declare class BankService {
+    private readonly api;
+    constructor(api: ApiRequestor);
+    /** Every bank dpay supports. */
+    all(options?: RequestOptions): Promise<Bank[]>;
+    /** Banks enabled for this payment point. Defaults `timestamp` to the current clock. */
+    forService(params?: {
+        timestamp?: number;
+    }, options?: RequestOptions): Promise<Bank[]>;
+}
+
+/** BLIK alias namespace. */
+declare const BlikAliasType: {
+    readonly UID: "UID";
+    readonly PAYID: "PAYID";
+};
+type BlikAliasType = (typeof BlikAliasType)[keyof typeof BlikAliasType];
+
+/** A banking app that accepted the alias. */
+interface BlikApp {
+    readonly key: string | null;
+    readonly label: string | null;
+}
+/** A registered BLIK alias. */
+interface BlikAlias {
+    readonly aliasValue: string;
+    readonly aliasType: BlikAliasType | (string & {});
+    readonly status: string | null;
+    readonly expirationDate: string | null;
+    readonly apps: readonly BlikApp[];
+    readonly isActive: boolean;
+    readonly raw: Record<string, unknown>;
+}
+/** Mandate parameters attached to a recurring alias. */
+interface BlikRecurringRegistrationInfo {
+    readonly model: string | null;
+    readonly frequency: string | null;
+    /** Single charge limit in minor units. */
+    readonly limitAmt: number | null;
+    /** Total limit in minor units. */
+    readonly totLimitAmt: number | null;
+    readonly isLimitAmtFixed: boolean | null;
+    readonly initDate: string | null;
+    readonly label: string | null;
+    readonly registeredAt: string | null;
+    readonly raw: Record<string, unknown>;
+}
+/** State of a recurring BLIK mandate. */
+interface BlikRecurringStatus {
+    readonly aliasValue: string;
+    readonly aliasType: BlikAliasType | (string & {});
+    readonly status: string | null;
+    readonly expirationDate: string | null;
+    readonly registration: BlikRecurringRegistrationInfo | null;
+    readonly isActive: boolean;
+    readonly raw: Record<string, unknown>;
+}
+
+interface BlikAliasParams {
+    aliasValue: string;
+    aliasType?: BlikAliasType | (string & {});
+}
+interface BlikUnregisterAliasParams extends BlikAliasParams {
+    reason?: string;
+}
+
+/** Registers, reads and unregisters BLIK aliases, and reads recurring mandate status. */
+declare class BlikService {
+    private readonly api;
+    constructor(api: ApiRequestor);
+    /** Registers a BLIK alias so the payer can pay without a code next time. */
+    alias(params: BlikAliasParams, options?: RequestOptions): Promise<BlikAlias>;
+    /** Removes a BLIK alias. */
+    unregisterAlias(params: BlikUnregisterAliasParams, options?: RequestOptions): Promise<void>;
+    /** Reads the state of a recurring BLIK mandate. */
+    recurringStatus(params: {
+        aliasValue: string;
+    }, options?: RequestOptions): Promise<BlikRecurringStatus>;
+}
+
+/** A monetary amount held in minor units, never as a float. */
+declare class Money {
+    /** Amount in minor units, for example 1050 for 10.50 PLN. */
+    readonly minor: number;
+    /** Three-letter currency code. */
+    readonly currency: string;
+    private constructor();
+    /** Amount in Polish grosz, for example `Money.pln(1050)` is 10.50 PLN. */
+    static pln(minor: number): Money;
+    /** Amount in minor units of an arbitrary currency. */
+    static of(minor: number, currency: string): Money;
+    /** Parses a decimal string with at most two fraction digits. */
+    static fromDecimal(decimal: string, currency: string): Money;
+    /** Parses whatever shape the API used for this field. Throws on anything unparsable. */
+    static fromApiNumber(value: unknown, currency: string): Money;
+    /** Same as `fromApiNumber`, but returns null instead of throwing. */
+    static tryFromApiNumber(value: unknown, currency: string): Money | null;
+    /** Renders the amount as a decimal string with exactly two fraction digits. */
+    toDecimal(): string;
+    get isNegative(): boolean;
+    equals(other: Money): boolean;
+    toString(): string;
+    toJSON(): {
+        minor: number;
+        currency: string;
+    };
+}
+
+/** What the merchant must do next after a card operation. */
+declare const RedirectType: {
+    readonly SUCCESS: "SUCCESS";
+    readonly FORM: "FORM";
+    readonly URL: "URL";
+    readonly DCC_OFFER: "DCC_OFFER";
+};
+type RedirectType = (typeof RedirectType)[keyof typeof RedirectType];
+/** Payer's answer to a dynamic currency conversion offer. */
+declare const DccDecision: {
+    readonly ACCEPT: "accept";
+    readonly REJECT: "reject";
+};
+type DccDecision = (typeof DccDecision)[keyof typeof DccDecision];
+/** Card-on-file operation requested at registration time. */
+declare const CardRecurringOperation: {
+    readonly ADD_CARD: "add_card";
+    readonly COF_INITIAL: "cof_initial";
+    readonly CHARGE: "charge";
+};
+type CardRecurringOperation = (typeof CardRecurringOperation)[keyof typeof CardRecurringOperation];
+/** Charge cadence of a card mandate. */
+declare const CardRecurringFrequency: {
+    readonly DAILY: "DAILY";
+    readonly WEEKLY: "WEEKLY";
+    readonly BIWEEKLY: "BIWEEKLY";
+    readonly MONTHLY: "MONTHLY";
+    readonly QUARTERLY: "QUARTERLY";
+    readonly SEMIANNUAL: "SEMIANNUAL";
+    readonly ANNUAL: "ANNUAL";
+};
+type CardRecurringFrequency = (typeof CardRecurringFrequency)[keyof typeof CardRecurringFrequency];
+
+/** One markup component of a DCC offer. */
+interface DccMarkup {
+    readonly rate: number;
+    readonly additionalInfo: string | null;
+}
+/** Dynamic currency conversion offer the payer must accept or reject. */
+interface DccOffer {
+    readonly currencyConversionId: string;
+    readonly originalAmount: Money;
+    readonly convertedAmount: Money;
+    readonly exchangeRate: number;
+    readonly validUntil: string;
+    /** PSD2 declaration text that must be shown to the payer verbatim. */
+    readonly declarationText: string;
+    readonly isEuropeanEconomicArea: boolean;
+    readonly markup: readonly DccMarkup[];
+    readonly raw: Record<string, unknown>;
+}
+/** Outcome of a card operation. */
+interface CardPaymentResult {
+    readonly redirectType: RedirectType | (string & {}) | null;
+    readonly redirectText: string | null;
+    readonly isSuccess: boolean;
+    readonly requiresThreeDsForm: boolean;
+    readonly requiresRedirect: boolean;
+    readonly hasDccOffer: boolean;
+    /** Decoded 3-D Secure form to render, when `requiresThreeDsForm`. */
+    readonly threeDsFormHtml: string | null;
+    /** Decoded URL to send the payer to, when `requiresRedirect`. */
+    readonly redirectUrl: string | null;
+    readonly dccOffer: DccOffer | null;
+    readonly raw: Record<string, unknown>;
+}
+
+/** Payment flow requested at registration time. */
+declare const TransactionType: {
+    readonly TRANSFERS: "transfers";
+    readonly DCB_GATEWAY: "dcb_gateway";
+    readonly CARD_AUTH: "card_auth";
+    readonly MB_WAY_DIRECT: "mb_way_direct";
+    readonly BIZUM_DIRECT: "bizum_direct";
+    readonly BLIK_RECURRING: "blik_recurring";
+    readonly CARD_RECURRING: "card_recurring";
+};
+type TransactionType = (typeof TransactionType)[keyof typeof TransactionType];
+/** Lifecycle state of a transaction. The API may return values outside this list. */
+declare const TransactionStatus: {
+    readonly PAID: "paid";
+    readonly CREATED: "created";
+    readonly PROCESSING: "processing";
+    readonly EXPIRED: "expired";
+    readonly CAPTURED: "captured";
+};
+type TransactionStatus = (typeof TransactionStatus)[keyof typeof TransactionStatus];
+/** Who absorbs the payout fee. */
+declare const PayoutFeeMode: {
+    readonly NET: "net";
+    readonly GROSS: "gross";
+};
+type PayoutFeeMode = (typeof PayoutFeeMode)[keyof typeof PayoutFeeMode];
+
+/** Where dpay sends the payer back, and where it posts the IPN. */
+interface ReturnUrls {
+    /** Payer returns here after a successful payment. */
+    success: string;
+    /** Payer returns here after a failed payment. */
+    fail: string;
+    /** dpay posts the IPN here. Must be reachable from the internet. */
+    ipn: string;
+}
+/** Optional payer identity, prefilled on the payment page. */
+interface PayerParams {
+    email?: string;
+    firstName?: string;
+    lastName?: string;
+}
+/** 3-D Secure device fingerprint, required for card payments. */
+interface DeviceInfoParams {
+    browserAcceptHeader: string;
+    browserLanguage: string;
+    browserColorDepth: number;
+    browserScreenHeight: number;
+    browserScreenWidth: number;
+    /** Timezone offset in minutes, as reported by `Date.prototype.getTimezoneOffset`. */
+    browserTz: number;
+    browserUserAgent: string;
+    systemFamily: string;
+    geoLocalization: string;
+    /** 1 to 64 characters. */
+    deviceId: string;
+    /** 1 to 64 characters. */
+    applicationName: string;
+    browserJavaEnabled?: boolean | undefined;
+}
+/** KSeF invoice details, only valid together with `efaktura`. */
+interface InvoiceParams {
+    payerNip?: string;
+    payerName?: string;
+    invoiceNumber?: string;
+    /** YYYY-MM-DD. */
+    paymentDueDate?: string;
+    vatAmount?: Money;
+}
+/** One leg of a 1:1 payout attached to a payment. */
+interface PayoutPositionParams {
+    iban: string;
+    /** 1 to 255 characters. */
+    title: string;
+    amount: Money;
+}
+/** Payout instruction attached to a payment. */
+interface PayoutInstructionParams {
+    positions: readonly PayoutPositionParams[];
+    /** Defaults to `net`. */
+    feeMode?: PayoutFeeMode | (string & {});
+}
+
+/** Server-to-server card payment. */
+interface CardPaymentParams {
+    /** 3-D Secure device fingerprint. Required. */
+    deviceInfo: DeviceInfoParams;
+    email?: string;
+    channelId?: number;
+    cardHolderFirstName?: string;
+    cardHolderLastName?: string;
+    /** Base64 payload produced by `CardEncryptor`. */
+    encryptedCardData?: string;
+    threeDsConfirmed?: boolean;
+    /** Answer to a pending dynamic currency conversion offer. */
+    dccDecision?: DccDecision | (string & {});
+}
+/** Google Pay payment. */
+interface GooglePayParams {
+    token: string;
+    deviceInfo: DeviceInfoParams;
+    email?: string;
+    channelId?: number;
+}
+/** Apple Pay. Omit `token` to initialise a session. */
+interface ApplePayParams {
+    deviceInfo: DeviceInfoParams;
+    token?: string;
+    channelId?: number;
+}
+
+/** Charges, authorizes, captures and cancels card payments, including Google Pay and Apple Pay wallets. */
+declare class CardService {
+    private readonly api;
+    constructor(api: ApiRequestor);
+    /** Current RSA public key. dpay rotates it, so fetch it before every attempt. */
+    publicKey(options?: RequestOptions): Promise<string>;
+    /** Charges a card immediately. */
+    payOtp(transactionId: string, params: CardPaymentParams, options?: RequestOptions): Promise<CardPaymentResult>;
+    /** Authorizes a card without capturing the funds. */
+    preAuth(transactionId: string, params: CardPaymentParams, options?: RequestOptions): Promise<CardPaymentResult>;
+    /** Captures a pre-authorization. Omit `amount` to capture in full. */
+    capture(transactionId: string, params?: {
+        amount?: Money;
+    }, options?: RequestOptions): Promise<CardPaymentResult>;
+    /** Cancels a pre-authorization. Omit `amount` to cancel in full. */
+    cancel(transactionId: string, params?: {
+        amount?: Money;
+    }, options?: RequestOptions): Promise<CardPaymentResult>;
+    /** Pays with a Google Pay token. */
+    googlePay(transactionId: string, params: GooglePayParams, options?: RequestOptions): Promise<CardPaymentResult>;
+    /** Initialises an Apple Pay session, or pays when `token` is given. */
+    applePay(transactionId: string, params: ApplePayParams, options?: RequestOptions): Promise<CardPaymentResult>;
+}
+
+/** Kind of notification dpay sent. */
+declare const IpnType: {
+    readonly TRANSFER: "transfer";
+    readonly CAPTURE: "capture";
+    readonly DCB: "dcb";
+};
+type IpnType = (typeof IpnType)[keyof typeof IpnType];
+/**
+ * Body dpay requires in the IPN response. It must be exactly this string;
+ * the HTTP status is ignored.
+ */
+declare const IPN_ACK = "OK";
+/** A verified IPN notification. */
+interface IpnEvent {
+    readonly id: string;
+    /** Raw decimal string. The payload carries no currency, so compare it to your own order. */
+    readonly amount: string;
+    readonly email: string | null;
+    readonly type: IpnType | (string & {});
+    readonly attempt: number;
+    readonly version: number;
+    /** Whatever you passed as `custom` at registration time. */
+    readonly custom: string | null;
+    readonly capturePaymentId: string | null;
+    readonly signature: string;
+    readonly isTransfer: boolean;
+    readonly isCapture: boolean;
+    readonly isDcb: boolean;
+    readonly raw: Record<string, unknown>;
+}
+
+/** Verifies IPN notifications dpay posts to your server after a payment event. */
+declare class IpnService {
+    private readonly config;
+    constructor(config: Config);
+    /** Verifies an IPN body. Uses the client's `secretHash` unless one is given. */
+    constructEvent(rawBody: string | Uint8Array, secretHash?: string): IpnEvent;
+    /** Reads and verifies an IPN straight from an incoming HTTP request. */
+    constructEventFromRequest(request: unknown, secretHash?: string): Promise<IpnEvent>;
+}
+
+/** Result of a successful payment registration. */
+interface RegisteredPayment {
+    readonly transactionId: string;
+    /** Raw `msg` field. Carries either a URL or a status sentence. */
+    readonly message: string;
+    /** KSeF invoice identifier, when e-invoicing was requested. */
+    readonly ipksef: string | null;
+    /** Where to send the payer, or null when there is nothing to redirect to. */
+    readonly redirectUrl: string | null;
+    /** True when the payment was already settled inline. */
+    readonly isPaid: boolean;
+    /** True when dpay is processing the payment without a payer redirect. */
+    readonly isInternalProcessing: boolean;
+    /** Alias returned when a card mandate was registered. */
+    readonly cardRecurringAlias: string | null;
+    readonly raw: Record<string, unknown>;
+}
+/** A single refund attached to a transaction. */
+interface TransactionRefund {
+    readonly paymentId: string;
+    readonly value: Money;
+    readonly status: TransactionStatus | (string & {});
+    readonly creationDate: string | null;
+    readonly paymentDate: string | null;
+    readonly raw: Record<string, unknown>;
+}
+/** Full transaction state from `pbl/details`. */
+interface Transaction {
+    readonly id: string;
+    readonly value: Money;
+    readonly status: TransactionStatus | (string & {});
+    readonly paymentMethod: string | null;
+    readonly creationDate: string | null;
+    readonly paymentDate: string | null;
+    readonly isPaid: boolean;
+    readonly isSettled: boolean;
+    readonly isRefunded: boolean;
+    readonly refundedAmount: Money;
+    readonly availableRefundAmount: Money;
+    readonly isFullyRefunded: boolean;
+    readonly isDirect: boolean;
+    readonly gatewayId: string | null;
+    readonly payer: Record<string, unknown>;
+    readonly refunds: readonly TransactionRefund[];
+    readonly raw: Record<string, unknown>;
+}
+
+declare const MODELS: readonly ["A", "M", "O"];
+/** Registers a one-off BLIK alias alongside a payment. */
+interface BlikAliasRegistrationParams {
+    /** 1 to 50 characters, shown in the payer's banking app. */
+    label: string;
+    /** Defaults to `UID`. */
+    type?: BlikAliasType | (string & {});
+}
+/** Registers a recurring BLIK mandate alongside a payment. */
+interface BlikRecurringRegistrationParams {
+    /** 1 to 50 characters. */
+    label: string;
+    /** `A` automatic, `M` merchant initiated, `O` one-off. */
+    model: (typeof MODELS)[number];
+    /** Count plus unit, for example `12M`. Units: D, W, M, Q, Y. */
+    frequency: string;
+    value?: Money;
+    /** Single charge limit in minor units. */
+    limitAmt?: number;
+    /** Total limit in minor units. */
+    totLimitAmt?: number;
+    limitAmtFixed?: boolean;
+    /** YYYY-MM-DD. */
+    expirationDate?: string;
+    /** YYYY-MM-DD. */
+    initDate?: string;
+}
+
+/** Registers a card mandate alongside a payment. */
+interface CardRecurringRegistrationParams {
+    /** 1 to 50 characters. */
+    label: string;
+    frequency?: CardRecurringFrequency | (string & {});
+    limitAmt?: Money;
+    totLimitAmt?: Money;
+    limitAmtFixed?: boolean;
+    /** YYYY-MM-DD. */
+    expirationDate?: string;
+    /** YYYY-MM-DD. */
+    initDate?: string;
+}
+
+/** Everything `payments.register` accepts. Only the first three fields are required. */
+interface RegisterPaymentParams {
+    /** Amount to charge. */
+    amount: Money;
+    /** Payment flow. */
+    transactionType: TransactionType | (string & {});
+    /** Success, failure and IPN URLs. */
+    urls: ReturnUrls;
+    description?: string;
+    /** Opaque merchant reference, echoed back in the IPN. */
+    custom?: string;
+    payer?: PayerParams;
+    acceptTos?: boolean;
+    /** Payment channel identifier from panel.dpay.pl. */
+    channel?: string;
+    creditCard?: boolean;
+    paysafecard?: boolean;
+    blik?: boolean;
+    installment?: boolean;
+    paypal?: boolean;
+    /** Hides the bank list on the payment page. */
+    noBanks?: boolean;
+    /** Requires `currencyCode` to be set as well. */
+    phoneNumber?: string;
+    currencyCode?: string;
+    /** Uppercase letters and digits, up to 64 characters. */
+    partnerPlatform?: string;
+    /** Required together with `blikCode` or `blikAlias`. */
+    userAgent?: string;
+    /** Required together with `blikCode` or `blikAlias`. */
+    userIp?: string;
+    /** Exactly six digits. Cannot be combined with `blikAlias`. */
+    blikCode?: string;
+    /** Cannot be combined with `blikCode` or any alias registration. */
+    blikAlias?: string;
+    registerBlikAlias?: BlikAliasRegistrationParams;
+    registerBlikRecurringAlias?: BlikRecurringRegistrationParams;
+    aliasIpnUrl?: string;
+    noDelay?: boolean;
+    /** Cannot be combined with `cardRecurringAlias`. */
+    registerCardRecurring?: CardRecurringRegistrationParams;
+    /** Cannot be combined with `registerCardRecurring`. */
+    cardRecurringAlias?: string;
+    authorizeOnly?: boolean;
+    cardRecurringOperation?: CardRecurringOperation | (string & {});
+    payout?: PayoutInstructionParams;
+    billingAddress?: Record<string, unknown>;
+    shippingAddress?: Record<string, unknown>;
+    deviceInfo?: DeviceInfoParams;
+    products?: ReadonlyArray<Record<string, unknown>>;
+    /** Only valid when `transactionType` is `transfers`. */
+    efaktura?: boolean;
+    invoice?: InvoiceParams;
+}
+
+/** Registers dpay payments and reads their current transaction status. */
+declare class PaymentService {
+    private readonly api;
+    constructor(api: ApiRequestor);
+    /**
+     * Registers a payment and returns the redirect target.
+     * Throws `PaymentRejectedError` when dpay rejects it with HTTP 200.
+     */
+    register(params: RegisterPaymentParams, options?: RequestOptions): Promise<RegisteredPayment>;
+    /** Reads the current state of a transaction, including its refunds. */
+    details(transactionId: string, options?: RequestOptions): Promise<Transaction>;
+}
+
+/** Beneficiary of a payout. */
+interface PayoutReceiver {
+    readonly nrb: string | null;
+    readonly title: string | null;
+    readonly amount: Money | null;
+    readonly service: string | null;
+    readonly receiverName: string | null;
+    readonly receiverAddress: string | null;
+    readonly raw: Record<string, unknown>;
+}
+/** State of a single payout. */
+interface PayoutDetails {
+    readonly id: number;
+    /** 0 waiting, 1 processed, -1 failed. */
+    readonly state: number;
+    readonly net: Money;
+    readonly fee: Money;
+    readonly gross: Money;
+    readonly creationDate: string | null;
+    readonly isDirectSettlement: boolean;
+    readonly nrb: string | null;
+    readonly isDeclined: boolean;
+    readonly declineReason: string | null;
+    readonly declineStatus: string | null;
+    readonly receiver: PayoutReceiver | null;
+    readonly isWaiting: boolean;
+    readonly isProcessed: boolean;
+    readonly isFailed: boolean;
+    readonly raw: Record<string, unknown>;
+}
+
+interface PayoutDetailsParams {
+    withdrawId: number;
+    timestamp?: number;
+}
+
+/** Reads the state of payouts (withdrawals) from a dpay merchant balance. */
+declare class PayoutService {
+    private readonly api;
+    constructor(api: ApiRequestor);
+    /** Reads the state of a single payout. */
+    details(params: PayoutDetailsParams, options?: RequestOptions): Promise<PayoutDetails>;
+}
+
+/** Outcome of a refund request. */
+interface Refund {
+    readonly isAccepted: boolean;
+    readonly message: string | null;
+    readonly raw: Record<string, unknown>;
+}
+/** Outcome of a refund availability check. */
+interface RefundAvailability {
+    readonly isAvailable: boolean;
+    readonly message: string | null;
+    /** HTTP status the API answered with. The API signals refusal through the status. */
+    readonly httpStatus: number;
+    readonly raw: Record<string, unknown>;
+}
+
+interface RefundParams {
+    transactionId: string;
+    amount?: Money;
+    reason?: string;
+}
+
+/** Refunds transactions and checks whether a refund would be accepted before performing it. */
+declare class RefundService {
+    private readonly api;
+    constructor(api: ApiRequestor);
+    /** Refunds a transaction in full, or partially when `amount` is given. */
+    create(params: RefundParams, options?: RequestOptions): Promise<Refund>;
+    /**
+     * Checks whether a refund would be accepted, without performing it.
+     * Refusal arrives as a 4xx status carrying an outcome body, not as an error.
+     */
+    checkAvailability(params: RefundParams, options?: RequestOptions): Promise<RefundAvailability>;
+}
+
+/** Entry point of the SDK. One instance per payment point. */
+declare class DPayClient {
+    /** Version of this SDK. */
+    readonly VERSION = "0.1.0";
+    /** Register payments and read transaction state. */
+    readonly payments: PaymentService;
+    /** Refund transactions and check refund availability. */
+    readonly refunds: RefundService;
+    /** List banks available on the payment page. */
+    readonly banks: BankService;
+    /** Register, unregister and inspect BLIK aliases. */
+    readonly blik: BlikService;
+    /** Server-to-server card payments, wallets and pre-authorizations. */
+    readonly cards: CardService;
+    /** Read the state of payouts. */
+    readonly payouts: PayoutService;
+    /** Verify incoming IPN notifications. */
+    readonly ipn: IpnService;
+    /**
+     * Validates `options` eagerly - before any network call - and mounts every service on
+     * top of a shared transport. Defaults to `FetchHttpClient` when `options.httpClient` is
+     * not given.
+     */
+    constructor(options: DPayClientOptions);
+}
+
+declare const SDK_VERSION = "0.1.0";
+
+/** Currency codes used by dpay. Any ISO-4217 style code is accepted. */
+declare const Currency: {
+    readonly PLN: "PLN";
+    readonly EUR: "EUR";
+    readonly CZK: "CZK";
+};
+type Currency = (typeof Currency)[keyof typeof Currency] | (string & {});
+declare function isValidCurrency(code: string): boolean;
+declare function assertCurrency(code: string): void;
+
+/** Default transport, built on the global `fetch`. */
+declare class FetchHttpClient implements HttpClient {
+    private readonly fetchImpl;
+    constructor(fetchImpl?: typeof fetch);
+    request(request: ApiRequest): Promise<ApiResponse>;
+}
+
+type DPayErrorType = 'value_error' | 'transport_error' | 'signature_verification_error' | 'card_encryption_error' | 'api_error' | 'authentication_error' | 'invalid_request_error' | 'access_denied_error' | 'not_found_error' | 'rate_limit_error' | 'card_payment_error' | 'payment_rejected_error' | 'api_server_error';
+/** Base class for every error thrown by this SDK. */
+declare class DPayError extends Error {
+    /** Stable discriminator, usable in `switch` when `instanceof` is unreliable. */
+    readonly type: DPayErrorType;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Invalid argument passed to the SDK. Thrown before any network call. */
+declare class DPayValueError extends DPayError {
+    readonly type = "value_error";
+}
+/** Network failure, timeout or abort. The payment status is unknown. */
+declare class TransportError extends DPayError {
+    readonly type = "transport_error";
+}
+/** The IPN payload is malformed or its signature does not match. */
+declare class SignatureVerificationError extends DPayError {
+    readonly type = "signature_verification_error";
+}
+/** Card data could not be encrypted with the public key from the API. */
+declare class CardEncryptionError extends DPayError {
+    readonly type = "card_encryption_error";
+}
+/** The API answered, but rejected the request. */
+declare class ApiError extends DPayError {
+    readonly type: DPayErrorType;
+    /** HTTP status of the response, or 200 for rejections carried in a success body. */
+    readonly httpStatus: number;
+    /** Business error code from the API, when present. */
+    readonly errorCode: string | null;
+    /** Per-field validation messages, normalized across the 400 and 422 formats. */
+    readonly fieldErrors: Record<string, string[]>;
+    /** Unparsed response body. */
+    readonly rawBody: string;
+    constructor(message: string, httpStatus: number, errorCode?: string | null, fieldErrors?: Record<string, string[]>, rawBody?: string);
+}
+/** HTTP 401 - usually a wrong checksum. */
+declare class AuthenticationError extends ApiError {
+    readonly type = "authentication_error";
+}
+/** HTTP 400 or 422 - see `fieldErrors`. */
+declare class InvalidRequestError extends ApiError {
+    readonly type = "invalid_request_error";
+}
+/** HTTP 403. */
+declare class AccessDeniedError extends ApiError {
+    readonly type = "access_denied_error";
+}
+/** HTTP 404. */
+declare class NotFoundError extends ApiError {
+    readonly type = "not_found_error";
+}
+/** HTTP 5xx. */
+declare class ApiServerError extends ApiError {
+    readonly type = "api_server_error";
+}
+/** HTTP 429. */
+declare class RateLimitError extends ApiError {
+    readonly type = "rate_limit_error";
+    /** Seconds from the `Retry-After` header. */
+    readonly retryAfter: number | null;
+    /** Value of `X-RateLimit-Limit`. */
+    readonly limit: number | null;
+    /** Value of `X-RateLimit-Remaining`. */
+    readonly remaining: number | null;
+    constructor(message: string, httpStatus: number, retryAfter?: number | null, limit?: number | null, remaining?: number | null, rawBody?: string);
+}
+/** Payment registration rejected with HTTP 200 and `error: true`. */
+declare class PaymentRejectedError extends ApiError {
+    readonly type = "payment_rejected_error";
+    /** Transaction identifier returned alongside the rejection, when present. */
+    readonly transactionId: string | null;
+    constructor(message: string, httpStatus: number, errorCode?: string | null, fieldErrors?: Record<string, string[]>, rawBody?: string, transactionId?: string | null);
+    static fromApi(data: Record<string, unknown>): PaymentRejectedError;
+}
+/** Card payment rejected with HTTP 200 and `success != true`. */
+declare class CardPaymentError extends ApiError {
+    readonly type = "card_payment_error";
+    static fromApi(data: Record<string, unknown>): CardPaymentError;
+}
+
+/**
+ * Raw card credentials, held only long enough to encrypt them.
+ *
+ * Redacts itself when logged or serialized, so it never reaches a log sink in clear text.
+ * `pan`, `cvv`, and `expiry` are exposed through getters backed by private fields rather than
+ * plain enumerable own data properties, so APIs that bypass custom inspection - such as
+ * `console.dir(card)` or `Object.keys(card)` - have nothing to dump either.
+ */
+declare class CardData {
+    #private;
+    constructor(params: {
+        pan: string;
+        cvv: string;
+        expiry: string;
+    });
+    /** Card number, normalized to digits only (spaces stripped). */
+    get pan(): string;
+    /** Card verification value, 3-4 digits. */
+    get cvv(): string;
+    /** Expiry in `MM/YY` format. */
+    get expiry(): string;
+    private redacted;
+    /** Redacted representation - `pan` masked to its last 4 digits, `cvv` fully masked. */
+    toJSON(): {
+        pan: string;
+        cvv: string;
+        expiry: string;
+    };
+    /** Redacted representation - `pan` masked to its last 4 digits, `cvv` fully masked. */
+    toString(): string;
+    /** Node `util.inspect` hook - delegates to the same redacted `toString()`. */
+    [inspect.custom](): string;
+}
+
+/** Encrypts card credentials with the rotating RSA key from `cards.publicKey()`. */
+declare class CardEncryptor {
+    /**
+     * Returns the Base64 payload to put in `encryptedCardData`.
+     * Fetch the public key immediately before every attempt - dpay rotates it.
+     */
+    encrypt(card: CardData, transactionId: string, publicKeyPem: string): string;
+}
+
+/**
+ * Parses and verifies an IPN body. Always pass the exact bytes dpay sent -
+ * a re-serialized JSON object will not verify.
+ */
+declare function constructIpnEvent(rawBody: string | Uint8Array, secretHash: string): IpnEvent;
+
+/**
+ * Reads the exact bytes of an incoming request body.
+ * Accepts a WHATWG `Request`, a Node `IncomingMessage`, a string, a Buffer, or a Uint8Array.
+ */
+declare function readRawBody(request: unknown): Promise<string>;
+
+export { AccessDeniedError, ApiError, ApiRequest, ApiResponse, ApiServerError, type ApplePayParams, AuthenticationError, type Bank, type BlikAlias, type BlikAliasParams, type BlikAliasRegistrationParams, BlikAliasType, type BlikApp, type BlikRecurringRegistrationInfo, type BlikRecurringRegistrationParams, type BlikRecurringStatus, type BlikUnregisterAliasParams, CardData, CardEncryptionError, CardEncryptor, CardPaymentError, type CardPaymentParams, type CardPaymentResult, CardRecurringFrequency, CardRecurringOperation, type CardRecurringRegistrationParams, Currency, DEFAULT_TIMEOUT, DPayClient, type DPayClientOptions, DPayError, type DPayErrorType, DPayValueError, DccDecision, type DccMarkup, type DccOffer, type DeviceInfoParams, FetchHttpClient, type GooglePayParams, HttpClient, IPN_ACK, InvalidRequestError, type InvoiceParams, type IpnEvent, IpnType, Money, NotFoundError, type PayerParams, PaymentRejectedError, type PayoutDetails, type PayoutDetailsParams, PayoutFeeMode, type PayoutInstructionParams, type PayoutPositionParams, type PayoutReceiver, RateLimitError, RedirectType, type Refund, type RefundAvailability, type RefundParams, type RegisterPaymentParams, type RegisteredPayment, type RequestHookContext, type RequestOptions, type ResponseHookContext, type ReturnUrls, SDK_VERSION, SignatureVerificationError, type Transaction, type TransactionRefund, TransactionStatus, TransactionType, TransportError, assertCurrency, constructIpnEvent, isValidCurrency, readRawBody };