paysafe-sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1211 @@
+/** Selects which Paysafe environment a client talks to. */
+type Environment = "test" | "production";
+/** Local token-bucket rate limit applied before every outbound request. */
+interface RateLimitConfig {
+    /** Maximum number of requests allowed within `windowMs`. */
+    limit: number;
+    /** Window, in milliseconds, over which `limit` applies. */
+    windowMs: number;
+}
+/**
+ * `fetch`-compatible function signature. Defaults to `globalThis.fetch`;
+ * override for testing or to inject a custom transport (proxying,
+ * connection pooling, request signing middleware, etc.).
+ */
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+interface PaysafeClientOptions {
+    /** API username from the Paysafe Business Portal. */
+    username: string;
+    /** API password from the Paysafe Business Portal. */
+    password: string;
+    /** Test or Production. Defaults to `"test"`. */
+    environment?: Environment;
+    /** Default account ID used when a resource call doesn't specify one. */
+    accountId?: string;
+    /** Overrides the environment-derived base URL entirely (e.g. a mock server in tests). */
+    baseUrlOverride?: string;
+    /** Overall per-request timeout, in milliseconds. Defaults to 30_000. */
+    timeoutMs?: number;
+    /** Maximum number of retries on transient failures. Defaults to 3. */
+    maxRetries?: number;
+    /** Base delay, in milliseconds, for exponential backoff between retries. Defaults to 500. */
+    retryBaseDelayMs?: number;
+    /** Local token-bucket rate limit. Defaults to 100 requests / 1000ms. */
+    rateLimit?: RateLimitConfig;
+    /** Custom `fetch` implementation. Defaults to `globalThis.fetch`. */
+    fetch?: FetchLike;
+    /** Metric/event name prefix emitted by telemetry hooks. Defaults to `"paysafe"`. */
+    telemetryPrefix?: string;
+}
+/** Fully-resolved, validated configuration used internally by the SDK. */
+declare class ResolvedConfig {
+    readonly username: string;
+    readonly password: string;
+    readonly environment: Environment;
+    readonly accountId?: string;
+    readonly baseUrlOverride?: string;
+    readonly timeoutMs: number;
+    readonly maxRetries: number;
+    readonly retryBaseDelayMs: number;
+    readonly rateLimit: RateLimitConfig;
+    readonly fetchImpl: FetchLike;
+    readonly telemetryPrefix: string;
+    constructor(opts: PaysafeClientOptions);
+    private validate;
+    baseUrl(): string;
+    paymentsUrl(): string;
+    schedulerUrl(): string;
+    applicationsUrl(): string;
+    fxRatesUrl(): string;
+    bankAccountValidatorUrl(): string;
+    customerIdentificationUrl(): string;
+    /** Computes the Base64-encoded HTTP Basic Auth header value. */
+    authHeader(): string;
+    /** Returns `override` if non-empty, otherwise the configured default account ID. */
+    resolveAccountId(override?: string): string;
+}
+
+/**
+ * Lightweight, dependency-free instrumentation hooks around every
+ * outbound Paysafe API call. Attach a {@link TelemetryHook} to observe
+ * start/stop/exception events for logging, metrics, or tracing.
+ */
+interface TelemetryStartMeta {
+    prefix: string;
+    api: string;
+    method: string;
+    path: string;
+    operation: string;
+}
+interface TelemetryStopMeta extends TelemetryStartMeta {
+    durationMs: number;
+    httpStatus: number;
+    ok: boolean;
+    error?: unknown;
+}
+interface TelemetryExceptionMeta extends TelemetryStartMeta {
+    durationMs: number;
+    reason: unknown;
+}
+/**
+ * Receives telemetry events. All methods are optional — implement only
+ * what you need; the SDK checks for each method's presence before
+ * calling it.
+ */
+interface TelemetryHook {
+    onStart?: (meta: TelemetryStartMeta) => void;
+    onStop?: (meta: TelemetryStopMeta) => void;
+    onException?: (meta: TelemetryExceptionMeta) => void;
+}
+
+/**
+ * Manages one token bucket per key (typically the API username), so
+ * multiple clients sharing a process don't starve each other's budget.
+ */
+declare class RateLimiter {
+    private readonly buckets;
+    private bucketFor;
+    /**
+     * Checks (and, if permitted, consumes) one token for `key`. Throws a
+     * {@link PaysafeError} with `kind === "rate_limited"` if the bucket is
+     * exhausted.
+     */
+    allow(key: string, limit: number, windowMs: number): void;
+}
+
+/**
+ * Shared low-level transport used by every resource (payment handles,
+ * payments, plans, subscriptions, ...). Resources depend on this rather
+ * than calling `fetch` directly.
+ */
+
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+interface RequestOptions {
+    /** Bounded-context API name for telemetry, e.g. `"payments"`, `"scheduler"`. */
+    api: string;
+    /** Dotted operation name for telemetry, e.g. `"payments.create"`. */
+    operation: string;
+    method: HttpMethod;
+    url: string;
+    body?: unknown;
+    /** Caller-supplied abort signal, composed with the client's own timeout. */
+    signal?: AbortSignal;
+}
+/**
+ * The shared transport: rate limiting, retry with exponential backoff +
+ * jitter, telemetry spans, and JSON encode/decode all happen here so
+ * every resource method stays a thin one-liner.
+ */
+declare class HttpTransport {
+    private readonly cfg;
+    private readonly limiter;
+    private readonly hook?;
+    constructor(cfg: ResolvedConfig, limiter: RateLimiter, hook?: TelemetryHook | undefined);
+    /**
+     * Performs the HTTP round trip and returns the raw response body as
+     * text. Used directly for endpoints with no JSON object response body
+     * (e.g. `DELETE`).
+     */
+    raw(options: RequestOptions): Promise<string>;
+    /**
+     * Performs the HTTP round trip and decodes the JSON response body as
+     * `T`. This is the common case used by nearly every resource method.
+     */
+    do<T>(options: RequestOptions): Promise<T>;
+    private doWithRetry;
+    private doOnce;
+}
+
+/** A HATEOAS-style link returned by the Paysafe API. */
+interface PaysafeLink {
+    rel: string;
+    href: string;
+}
+/** Returns the href of the first link whose `rel` matches, or `undefined`. */
+declare function findLinkByRel(links: PaysafeLink[] | undefined, rel: string): string | undefined;
+
+type HandleStatus = "INITIATED" | "PAYABLE" | "PROCESSING" | "COMPLETED" | "EXPIRED" | "FAILED" | "CANCELLED" | "ERROR";
+type HandleAction = "NONE" | "REDIRECT";
+/** Distinguishes single-use tokens (SUT) from multi-use tokens (MUT). */
+type HandleUsage = "SINGLE_USE" | "MULTI_USE";
+/** Whether the payment instrument completes synchronously or via webhook. */
+type ExecutionMode = "SYNCHRONOUS" | "ASYNCHRONOUS";
+/** Selects which downstream resource a Payment Handle may be used against. */
+type TransactionType = "PAYMENT" | "STANDALONE_CREDIT" | "ORIGINAL_CREDIT" | "VERIFICATION";
+interface CardExpiry {
+    month: number;
+    year: number;
+}
+/** A network-tokenized card (Visa/Mastercard network tokens, Click to Pay). */
+interface NetworkToken {
+    token: string;
+    cryptogram?: string;
+    eci?: string;
+    expiry: CardExpiry;
+    /** Response-only: `"ACTIVE" | "SUSPENDED" | "DELETED"`. */
+    status?: string;
+}
+/**
+ * The card payment instrument object accepted by Payment Handles. Either
+ * `cardNum` or `networkToken` should be populated, not both.
+ */
+interface Card {
+    cardNum?: string;
+    cardExpiry?: CardExpiry;
+    cvv?: string;
+    holderName?: string;
+    /** e.g. `"NETWORK_TOKEN"`. */
+    tokenType?: string;
+    networkToken?: NetworkToken;
+    cardType?: string;
+    cardBin?: string;
+    lastDigits?: string;
+    status?: string;
+}
+interface BillingDetails {
+    street?: string;
+    street2?: string;
+    city?: string;
+    state?: string;
+    country?: string;
+    zip?: string;
+    phone?: string;
+}
+/** A lightweight customer profile attached inline to a Payment Handle. */
+interface InlineProfile {
+    firstName?: string;
+    lastName?: string;
+    email?: string;
+    phone?: string;
+    locale?: string;
+}
+/** 3-D Secure authentication parameters/results. Shape varies by payment method. */
+type ThreeDS = Record<string, unknown>;
+/**
+ * Request body for creating a Payment Handle. Only `merchantRefNum`,
+ * `amount`, `currencyCode`, `paymentType`, and `transactionType` are
+ * required by the API; the rest depend on the chosen payment method.
+ */
+interface CreatePaymentHandleRequest {
+    accountId?: string;
+    merchantRefNum: string;
+    /** Amount in minor currency units (e.g. cents). */
+    amount: number;
+    currencyCode: string;
+    paymentType: string;
+    transactionType: TransactionType;
+    card?: Card;
+    threeDs?: ThreeDS;
+    billingDetails?: BillingDetails;
+    profile?: InlineProfile;
+    returnLinks?: PaysafeLink[];
+    merchantDescriptor?: Record<string, unknown>;
+    customerIp?: string;
+    deviceFingerprintingId?: string;
+    settleWithAuth?: boolean;
+    singleUseCustomerToken?: string;
+}
+interface PaymentHandle {
+    id: string;
+    merchantRefNum: string;
+    amount: number;
+    currencyCode: string;
+    status: HandleStatus;
+    paymentType: string;
+    paymentHandleToken: string;
+    action: HandleAction;
+    usage: HandleUsage;
+    executionMode: ExecutionMode;
+    timeToLiveSeconds: number;
+    transactionType: TransactionType;
+    links: PaysafeLink[];
+    returnLinks: PaysafeLink[];
+    card?: Card;
+}
+type PaymentStatus = "PROCESSING" | "COMPLETED" | "FAILED" | "CANCELLED" | "PENDING";
+interface CreatePaymentRequest {
+    merchantRefNum: string;
+    amount: number;
+    currencyCode: string;
+    paymentHandleToken: string;
+    settleWithAuth?: boolean;
+    description?: string;
+    /**
+     * Enables the Partial Authorization Service (PAS) to mitigate error
+     * 3022 (insufficient funds). Supported for Visa/Mastercard on
+     * UK/EEA-acquired merchants and must be pre-enabled on the account.
+     */
+    allowPartialAuth?: boolean;
+    groupId?: string;
+}
+interface SettlementSummary {
+    id: string;
+    amount: number;
+    status: string;
+}
+interface Payment {
+    id: string;
+    merchantRefNum: string;
+    amount: number;
+    currencyCode: string;
+    status: PaymentStatus;
+    settleWithAuth: boolean;
+    txnTime: string;
+    cardType?: string;
+    cardBin?: string;
+    lastDigits?: string;
+    authentication?: Record<string, unknown>;
+    settlements?: SettlementSummary[];
+    error?: Record<string, unknown>;
+    availableToSettle?: number;
+    availableToRefund?: number;
+}
+interface ListPaymentsFilter {
+    merchantRefNum?: string;
+    startDate?: string;
+    endDate?: string;
+    limit?: number;
+    offset?: number;
+}
+interface ListPaymentsResponse {
+    payments: Payment[];
+}
+type SettlementStatus = "PENDING" | "PROCESSING" | "COMPLETED" | "CANCELLED" | "FAILED";
+/** Amount defaults to the full authorized amount when omitted (partial settlement otherwise). */
+interface CreateSettlementRequest {
+    merchantRefNum: string;
+    amount?: number;
+}
+interface Settlement {
+    id: string;
+    merchantRefNum: string;
+    amount: number;
+    status: SettlementStatus;
+    txnTime: string;
+}
+type RefundStatus = "PROCESSING" | "COMPLETED" | "FAILED" | "CANCELLED" | "PENDING";
+/** Amount defaults to the full amount when omitted (partial refunds are allowed). */
+interface CreateRefundRequest {
+    merchantRefNum: string;
+    amount?: number;
+}
+interface Refund {
+    id: string;
+    merchantRefNum: string;
+    amount: number;
+    status: RefundStatus;
+    txnTime: string;
+    error?: Record<string, unknown>;
+}
+/**
+ * Request body for a standalone credit (general payout) or an original
+ * credit (iGaming payout). 3DS does not apply to payouts; the Payment
+ * Handle must have been created with the matching `transactionType`.
+ */
+interface CreatePayoutRequest {
+    accountId?: string;
+    merchantRefNum: string;
+    amount: number;
+    currencyCode: string;
+    paymentHandleToken: string;
+}
+/**
+ * A standalone credit or original credit response. The API does not
+ * share one documented schema across both resources, so extra fields
+ * pass through untyped via index access.
+ */
+interface Payout {
+    id: string;
+    merchantRefNum: string;
+    amount: number;
+    currencyCode: string;
+    status: string;
+    txnTime: string;
+    error?: Record<string, unknown>;
+}
+interface CreateVerificationRequest {
+    merchantRefNum: string;
+    paymentHandleToken: string;
+    currencyCode?: string;
+    amount?: number;
+}
+interface Verification {
+    id: string;
+    merchantRefNum: string;
+    status: string;
+    txnTime: string;
+    error?: Record<string, unknown>;
+}
+
+/**
+ * Payment Handle operations: the entry point for every payment, payout,
+ * and verification transaction. A Payment Handle tokenizes a payment
+ * instrument (card, wallet, bank redirect, etc.) before it's used.
+ */
+declare class PaymentHandlesResource {
+    private readonly cfg;
+    private readonly transport;
+    constructor(cfg: ResolvedConfig, transport: HttpTransport);
+    /**
+     * Tokenizes a payment instrument, returning a Payment Handle. If
+     * `req.accountId` is omitted, the client's default account ID is used.
+     */
+    create(req: CreatePaymentHandleRequest, signal?: AbortSignal): Promise<PaymentHandle>;
+    /**
+     * Retrieves a Payment Handle by ID. Useful for polling status if
+     * webhooks are not received; always verify via `get` after receiving a
+     * webhook before trusting the status.
+     */
+    get(paymentHandleId: string, signal?: AbortSignal): Promise<PaymentHandle>;
+}
+/**
+ * Returns the URL the customer should be sent to when
+ * `handle.action === "REDIRECT"`, and `undefined` otherwise.
+ */
+declare function paymentHandleRedirectUrl(handle: PaymentHandle): string | undefined;
+/** Whether the caller must redirect the customer before proceeding. */
+declare function paymentHandleRequiresAction(handle: PaymentHandle): boolean;
+
+/**
+ * Payment operations: the final transaction step after a Payment Handle
+ * has reached `PAYABLE` status.
+ */
+declare class PaymentsResource {
+    private readonly cfg;
+    private readonly transport;
+    constructor(cfg: ResolvedConfig, transport: HttpTransport);
+    /** Creates a payment using a `paymentHandleToken` from a `PAYABLE` Payment Handle. */
+    create(req: CreatePaymentRequest, signal?: AbortSignal): Promise<Payment>;
+    /** Retrieves a payment by ID. */
+    get(paymentId: string, signal?: AbortSignal): Promise<Payment>;
+    /** Returns payments matching the given filter. */
+    list(filter?: ListPaymentsFilter, signal?: AbortSignal): Promise<Payment[]>;
+    /** Cancels an authorized (not-yet-settled) payment. */
+    cancel(paymentId: string, signal?: AbortSignal): Promise<Payment>;
+}
+
+/**
+ * Settlement operations: capturing an authorized payment, including
+ * partial settlement and cancellation of a pending settlement.
+ */
+declare class SettlementsResource {
+    private readonly cfg;
+    private readonly transport;
+    constructor(cfg: ResolvedConfig, transport: HttpTransport);
+    /** Settles (captures) an authorized payment by payment ID. */
+    create(paymentId: string, req: CreateSettlementRequest, signal?: AbortSignal): Promise<Settlement>;
+    /** Retrieves a settlement by ID. */
+    get(settlementId: string, signal?: AbortSignal): Promise<Settlement>;
+    /** Cancels a pending settlement. */
+    cancel(settlementId: string, signal?: AbortSignal): Promise<Settlement>;
+}
+
+/**
+ * Refund operations.
+ *
+ * Refunds are addressed by *settlement* ID, not payment ID. If
+ * `settleWithAuth` was `true` on the original payment, the settlement ID
+ * equals the payment ID — pass it directly. Otherwise pass the
+ * settlement ID returned by `SettlementsResource.create`. Don't mix
+ * refund paths on the same transaction: once a refund has been issued
+ * against a settlement ID, stick to that same ID for any further refunds
+ * on that transaction.
+ */
+declare class RefundsResource {
+    private readonly cfg;
+    private readonly transport;
+    constructor(cfg: ResolvedConfig, transport: HttpTransport);
+    /** Issues a refund for a completed payment or settlement. */
+    create(settlementId: string, req: CreateRefundRequest, signal?: AbortSignal): Promise<Refund>;
+    /** Retrieves a refund by ID. */
+    get(refundId: string, signal?: AbortSignal): Promise<Refund>;
+    /** Cancels a pending refund. */
+    cancel(refundId: string, signal?: AbortSignal): Promise<Refund>;
+}
+
+/**
+ * Payout (credit) operations: standalone credits (general payouts) and
+ * original credits (iGaming-sector payouts). 3DS does not apply to
+ * payouts.
+ */
+declare class PayoutsResource {
+    private readonly cfg;
+    private readonly transport;
+    constructor(cfg: ResolvedConfig, transport: HttpTransport);
+    /**
+     * Creates a standalone credit (payout for non-iGaming merchants). The
+     * Payment Handle must have `transactionType: "STANDALONE_CREDIT"`.
+     */
+    standaloneCredit(req: CreatePayoutRequest, signal?: AbortSignal): Promise<Payout>;
+    /**
+     * Creates an original credit (payout for iGaming merchants). The
+     * Payment Handle must have `transactionType: "ORIGINAL_CREDIT"`.
+     */
+    originalCredit(req: CreatePayoutRequest, signal?: AbortSignal): Promise<Payout>;
+    /** Retrieves a standalone credit by ID. */
+    getStandaloneCredit(creditId: string, signal?: AbortSignal): Promise<Payout>;
+    /** Retrieves an original credit by ID. */
+    getOriginalCredit(creditId: string, signal?: AbortSignal): Promise<Payout>;
+    /** Cancels a standalone credit. */
+    cancelStandaloneCredit(creditId: string, signal?: AbortSignal): Promise<Payout>;
+}
+
+/**
+ * Card verification: a zero-value authorization check used to validate a
+ * card without charging it. The Payment Handle must have
+ * `transactionType: "VERIFICATION"`.
+ */
+declare class VerificationsResource {
+    private readonly cfg;
+    private readonly transport;
+    constructor(cfg: ResolvedConfig, transport: HttpTransport);
+    /** Creates a card verification. */
+    create(req: CreateVerificationRequest, signal?: AbortSignal): Promise<Verification>;
+    /** Retrieves a verification by ID. */
+    get(verificationId: string, signal?: AbortSignal): Promise<Verification>;
+}
+
+interface DateOfBirth {
+    year: number;
+    month: number;
+    day: number;
+}
+interface Address {
+    street?: string;
+    street2?: string;
+    city?: string;
+    state?: string;
+    country?: string;
+    zip?: string;
+    nickName?: string;
+    defaultShippingAddressIndicator?: boolean;
+}
+interface CreateCustomerRequest {
+    accountId?: string;
+    merchantCustomerId: string;
+    locale?: string;
+    firstName?: string;
+    lastName?: string;
+    email?: string;
+    phone?: string;
+    dateOfBirth?: DateOfBirth;
+    gender?: string;
+    nationality?: string;
+    addresses?: Address[];
+}
+/** Only the fields set here are changed server-side; unset fields are left untouched. */
+interface UpdateCustomerRequest {
+    firstName?: string;
+    lastName?: string;
+    email?: string;
+    phone?: string;
+    locale?: string;
+    dateOfBirth?: DateOfBirth;
+}
+/** Summarizes a card stored against a Customer Vault profile. */
+interface SavedCard {
+    id?: string;
+    cardBin?: string;
+    lastDigits?: string;
+    cardType?: string;
+    status?: string;
+}
+interface Customer {
+    id: string;
+    merchantCustomerId: string;
+    firstName?: string;
+    lastName?: string;
+    email?: string;
+    phone?: string;
+    locale?: string;
+    cards?: SavedCard[];
+}
+/**
+ * Converts a single-use token (SUT) from an initial payment into a
+ * multi-use token (MUT) attached to the customer's saved profile.
+ */
+interface CreateCustomerPaymentHandleRequest {
+    merchantRefNum: string;
+    paymentHandleTokenFrom: string;
+}
+interface ListPaymentHandlesResponse {
+    paymentHandles: Record<string, unknown>[];
+}
+/**
+ * Response from tokenizing a customer's entire saved profile (cards,
+ * addresses, bank mandates) into one short-lived token, valid for 900
+ * seconds.
+ */
+interface SingleUseCustomerToken {
+    singleUseCustomerToken: string;
+    timeToLiveSeconds: number;
+}
+
+/**
+ * Customer Vault profile and saved-instrument management. Base path is
+ * flat (`/paymenthub/v1/customers` — no account ID in the URL).
+ */
+declare class CustomersResource {
+    private readonly cfg;
+    private readonly transport;
+    constructor(cfg: ResolvedConfig, transport: HttpTransport);
+    /** Creates a customer profile in the vault. */
+    create(req: CreateCustomerRequest, signal?: AbortSignal): Promise<Customer>;
+    /** Retrieves a customer profile by Paysafe's customer ID. */
+    get(customerId: string, signal?: AbortSignal): Promise<Customer>;
+    /** Retrieves a customer profile by your own `merchantCustomerId`. */
+    getByMerchantCustomerId(merchantCustomerId: string, signal?: AbortSignal): Promise<Customer>;
+    /** Updates a customer profile. Only the fields set in `req` are changed server-side. */
+    update(customerId: string, req: UpdateCustomerRequest, signal?: AbortSignal): Promise<Customer>;
+    /** Deletes a customer profile. */
+    delete(customerId: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Converts a single-use token (SUT) returned from an initial payment
+     * into a multi-use token (MUT) attached to the customer profile,
+     * enabling saved-card/recurring flows.
+     */
+    createPaymentHandle(customerId: string, req: CreateCustomerPaymentHandleRequest, signal?: AbortSignal): Promise<Record<string, unknown>>;
+    /** Lists all saved payment handles (saved instruments) for a customer. */
+    listPaymentHandles(customerId: string, signal?: AbortSignal): Promise<Record<string, unknown>[]>;
+    /** Deletes a specific saved payment handle for a customer. */
+    deletePaymentHandle(customerId: string, handleId: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Tokenizes the customer's entire saved profile — profile details,
+     * saved cards, addresses, and bank mandates — into one short-lived
+     * token valid for 900 seconds. Used to display a returning customer's
+     * saved instruments, or to re-collect a one-time CVV for a saved card.
+     */
+    createSingleUseCustomerToken(customerId: string, signal?: AbortSignal): Promise<SingleUseCustomerToken>;
+}
+
+type ApplicationStatus = "DRAFT" | "SUBMITTED" | "APPROVED" | "DECLINED" | "IN_REVIEW";
+interface ApplicationContact {
+    firstName?: string;
+    lastName?: string;
+    email?: string;
+    phone?: string;
+}
+/**
+ * Request body for creating a draft merchant application. The full
+ * parameter set varies by country and business type; this captures the
+ * common subset.
+ */
+interface CreateApplicationRequest {
+    merchantDescriptor?: string;
+    currencyCode?: string;
+    contact?: ApplicationContact;
+}
+interface Application {
+    id: string;
+    status: ApplicationStatus;
+}
+/**
+ * Request body for attaching a supporting document to an application
+ * (e.g. requested by a credit underwriter during review).
+ */
+interface UploadDocumentRequest {
+    documentType: string;
+    /** Base64-encoded file content. */
+    fileContent: string;
+    fileName: string;
+}
+
+/**
+ * Merchant onboarding Application operations.
+ *
+ * Workflow: `create` -> `update` (optional, pre-submission) ->
+ * `uploadDocument` (optional) -> `getTermsAndConditions` -> `submit`.
+ * After `submit` succeeds, the application can no longer be modified via
+ * the API; subscribe to webhooks for status updates rather than polling.
+ */
+declare class ApplicationsResource {
+    private readonly cfg;
+    private readonly transport;
+    constructor(cfg: ResolvedConfig, transport: HttpTransport);
+    /** Creates a draft merchant application. */
+    create(req: CreateApplicationRequest, signal?: AbortSignal): Promise<Application>;
+    /** Retrieves an application by ID. */
+    get(applicationId: string, signal?: AbortSignal): Promise<Application>;
+    /** Updates a draft application. Only possible before `submit` is called. */
+    update(applicationId: string, req: CreateApplicationRequest, signal?: AbortSignal): Promise<Application>;
+    /**
+     * Sends the application to Paysafe for review. After this call
+     * succeeds, the application can no longer be modified via the API.
+     */
+    submit(applicationId: string, signal?: AbortSignal): Promise<Application>;
+    /** Retrieves the terms the merchant must accept before processing can begin. */
+    getTermsAndConditions(applicationId: string, signal?: AbortSignal): Promise<Record<string, unknown>>;
+    /**
+     * Attaches a supporting document to an application (e.g. requested by
+     * a credit underwriter during review). Documents can be uploaded before
+     * or after submission.
+     */
+    uploadDocument(applicationId: string, req: UploadDocumentRequest, signal?: AbortSignal): Promise<Record<string, unknown>>;
+}
+
+type BillingCycle = "DAILY" | "WEEKLY" | "BI_WEEKLY" | "MONTHLY" | "QUARTERLY" | "SEMI_ANNUALLY" | "ANNUALLY";
+type PlanStatus = "ACTIVE" | "INACTIVE" | "DISCONTINUED";
+/** Binds a Plan or Subscription to the payment instrument used for recurring billing. */
+interface PaymentMethodDetails {
+    paymentType?: string;
+    paymentHandleToken?: string;
+}
+interface CreatePlanRequest {
+    name: string;
+    amount: number;
+    currencyCode: string;
+    interval: BillingCycle;
+    numPayments?: number;
+    startDate?: string;
+    trialAmount?: number;
+    trialPeriod?: number;
+    maxFailedPayments?: number;
+    retryPaymentAmount?: number;
+    paymentMethodDetails?: PaymentMethodDetails;
+}
+/** Keep amount increases below 20% to comply with card scheme guidelines. */
+interface UpdatePlanRequest {
+    name?: string;
+    amount?: number;
+    numPayments?: number;
+    maxFailedPayments?: number;
+    retryPaymentAmount?: number;
+}
+interface Plan {
+    id: string;
+    name: string;
+    amount: number;
+    currencyCode: string;
+    billingCycle: BillingCycle;
+    numPayments?: number;
+    status: PlanStatus;
+}
+interface ListPlansResponse {
+    plans: Plan[];
+}
+type SubscriptionStatus = "ACTIVE" | "INACTIVE" | "SUSPENDED" | "CANCELLED" | "EXPIRED" | "FUTURE" | "COMPLETED";
+/** Binds a customer (via multi-use token) to a Plan. */
+interface CreateSubscriptionRequest {
+    planId: string;
+    merchantCustomerId: string;
+    paymentHandleToken: string;
+    merchantRefNum: string;
+    amount?: number;
+    startDate?: string;
+    numPayments?: number;
+    trialAmount?: number;
+    initialAmount?: number;
+}
+/**
+ * Mutable Subscription fields, including status transitions. Prefer the
+ * `cancel`/`suspend`/`reactivate` convenience methods over setting
+ * `status` directly.
+ */
+interface UpdateSubscriptionRequest {
+    status?: SubscriptionStatus;
+    numCycles?: number;
+    discountAmount?: number;
+    discountNumPayments?: number;
+    amount?: number;
+}
+interface Subscription {
+    id: string;
+    planId: string;
+    merchantCustomerId: string;
+    amount: number;
+    currencyCode: string;
+    status: SubscriptionStatus;
+    nextPaymentDate?: string;
+    numPaymentsRemaining?: number;
+}
+interface ListSubscriptionsFilter {
+    planId?: string;
+    status?: string;
+    merchantCustomerId?: string;
+    limit?: number;
+    offset?: number;
+}
+interface ListSubscriptionsResponse {
+    subscriptions: Subscription[];
+}
+
+/** Recurring billing Plan operations. */
+declare class PlansResource {
+    private readonly cfg;
+    private readonly transport;
+    constructor(cfg: ResolvedConfig, transport: HttpTransport);
+    /**
+     * Creates a recurring billing plan under `accountId` (or the client's
+     * default account ID if `accountId` is omitted).
+     */
+    create(accountId: string | undefined, req: CreatePlanRequest, signal?: AbortSignal): Promise<Plan>;
+    /** Retrieves a plan by ID. */
+    get(accountId: string | undefined, planId: string, signal?: AbortSignal): Promise<Plan>;
+    /** Lists all billing plans for an account. */
+    list(accountId: string | undefined, signal?: AbortSignal): Promise<Plan[]>;
+    /**
+     * Updates a plan's mutable fields. Keep amount increases below 20% to
+     * comply with card scheme guidelines. Discontinuing a plan prevents new
+     * subscriptions but does not affect existing ones.
+     */
+    update(accountId: string | undefined, planId: string, req: UpdatePlanRequest, signal?: AbortSignal): Promise<Plan>;
+    /** Discontinues a plan. */
+    delete(accountId: string | undefined, planId: string, signal?: AbortSignal): Promise<void>;
+}
+
+/**
+ * Subscription operations: binding a customer (via multi-use token) to a
+ * Plan to create a recurring billing schedule.
+ */
+declare class SubscriptionsResource {
+    private readonly cfg;
+    private readonly transport;
+    constructor(cfg: ResolvedConfig, transport: HttpTransport);
+    /** Creates a subscription for a customer under a plan. */
+    create(accountId: string | undefined, req: CreateSubscriptionRequest, signal?: AbortSignal): Promise<Subscription>;
+    /** Retrieves a subscription by ID. */
+    get(accountId: string | undefined, subscriptionId: string, signal?: AbortSignal): Promise<Subscription>;
+    /** Lists subscriptions matching the given filter. */
+    list(accountId: string | undefined, filter?: ListSubscriptionsFilter, signal?: AbortSignal): Promise<Subscription[]>;
+    /**
+     * Updates a subscription: extend cycles (`numCycles`), apply a discount
+     * (`discountAmount`/`discountNumPayments`), or change `status` directly.
+     * Prefer `cancel`/`suspend`/`reactivate` for status transitions.
+     */
+    update(accountId: string | undefined, subscriptionId: string, req: UpdateSubscriptionRequest, signal?: AbortSignal): Promise<Subscription>;
+    /** Cancels a subscription immediately. */
+    cancel(accountId: string | undefined, subscriptionId: string, signal?: AbortSignal): Promise<Subscription>;
+    /** Pauses billing on a subscription; it can later be reactivated. */
+    suspend(accountId: string | undefined, subscriptionId: string, signal?: AbortSignal): Promise<Subscription>;
+    /**
+     * Re-activates a suspended subscription. The last failed payment is
+     * retried; subsequent cycles resume on their original schedule.
+     */
+    reactivate(accountId: string | undefined, subscriptionId: string, signal?: AbortSignal): Promise<Subscription>;
+}
+
+/** Requests a guaranteed exchange rate quote. Available for Europe & UK merchants. */
+interface GetFxRateRequest {
+    fromCurrency: string;
+    toCurrency: string;
+    amount?: number;
+}
+interface FxRate {
+    id: string;
+    fromCurrency: string;
+    toCurrency: string;
+    rate: number;
+    expiry?: string;
+}
+/**
+ * Outcome of a Customer Identity check.
+ *
+ * - `SUCCESS`: the customer passed.
+ * - `ERROR`: a downstream provider issue occurred — retry with `rerun()`.
+ * - `FAIL`: the customer failed the check outright; do not rerun.
+ * - `OUTSORT`: inconclusive; the merchant should manually verify via documents.
+ */
+type IdentityDecision = "SUCCESS" | "ERROR" | "FAIL" | "OUTSORT";
+/** String-typed DOB shape used by the Customer Identity API. */
+interface IdentityDateOfBirth {
+    day: string;
+    month: string;
+    year: string;
+}
+interface IdentityAddress {
+    street?: string;
+    street2?: string;
+    city?: string;
+    state?: string;
+    country?: string;
+    zip?: string;
+    monthsAtAddress?: string;
+    phone?: string;
+}
+interface IdentityProfileInput {
+    firstName: string;
+    lastName: string;
+    email?: string;
+    currentAddress?: IdentityAddress;
+    dateOfBirth?: IdentityDateOfBirth;
+}
+interface VerifyIdentityRequest {
+    merchantRefNum: string;
+    profile: IdentityProfileInput;
+    customerIp?: string;
+    vendorCheck?: string;
+    workflowId?: string;
+}
+interface IdentityProfile {
+    id: string;
+    merchantRefNum: string;
+    decision: IdentityDecision;
+    providerResponses?: Record<string, unknown>;
+}
+type BankVerificationStatus = "INITIATED" | "COMPLETED" | "FAILED" | "CANCELLED" | "EXPIRED";
+/** The minimal customer profile required to start a Bank Account Validation session. */
+interface BankVerificationProfile {
+    firstName: string;
+    middleName?: string;
+    lastName: string;
+    locale?: string;
+}
+/**
+ * Request body for starting a Bank Account Validation redirect session.
+ * Available for Canada and the United States.
+ */
+interface CreateBankVerificationRequest {
+    merchantRefNum: string;
+    profile: BankVerificationProfile;
+    accountTypes?: string[];
+    currencyCodes?: string[];
+    returnLinks?: PaysafeLink[];
+    bankscheme?: string;
+}
+/**
+ * Request body for starting an Interac AML Assist Verification
+ * (VerifiedMe) redirect session. Available only in Canada.
+ */
+interface CreateInteracVerificationRequest {
+    merchantRefNum: string;
+    accountId?: string;
+    locale?: string;
+    returnLinks?: PaysafeLink[];
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A Bank Account Validation or Interac Verification Service session.
+ * Both products share this redirect-based shape.
+ */
+interface BankVerification {
+    id: string;
+    merchantRefNum?: string;
+    sessionId?: string;
+    status: BankVerificationStatus;
+    bankScheme?: string;
+    accountTypes?: string[];
+    currencyCodes?: string[];
+    links?: PaysafeLink[];
+}
+
+/**
+ * FX Rates API operations: guaranteed exchange rate quotes with expiry
+ * timestamps. Available for Europe & UK merchants.
+ *
+ * The exact request/response JSON shape could not be confirmed against a
+ * concrete example at the time this client was written — the base path
+ * (`/fxrates/v1`) and account-scoped URL pattern are consistent with
+ * every other Payments API resource, but double-check field names
+ * against the current API reference before relying on this in
+ * production.
+ */
+declare class FxRatesResource {
+    private readonly cfg;
+    private readonly transport;
+    constructor(cfg: ResolvedConfig, transport: HttpTransport);
+    /** Gets a guaranteed FX rate for a currency pair. */
+    getRate(accountId: string | undefined, req: GetFxRateRequest, signal?: AbortSignal): Promise<FxRate>;
+    /** Retrieves a specific FX rate by quote ID. */
+    getQuote(accountId: string | undefined, quoteId: string, signal?: AbortSignal): Promise<FxRate>;
+}
+
+/**
+ * Customer Identity (KYC) API: AML/KYC identity verification in a single
+ * API request. Available globally (CA, EU/UK, US). Base path is flat —
+ * not nested under `/accounts/{accountId}` like most other Payments API
+ * resources.
+ */
+declare class CustomerIdentityResource {
+    private readonly cfg;
+    private readonly transport;
+    constructor(cfg: ResolvedConfig, transport: HttpTransport);
+    /** Submits an identity verification request. */
+    verify(req: VerifyIdentityRequest, signal?: AbortSignal): Promise<IdentityProfile>;
+    /** Retrieves a previously submitted identity profile by ID. */
+    get(profileId: string, signal?: AbortSignal): Promise<IdentityProfile>;
+    /**
+     * Reruns a failed identity check. Only rerun a check whose `decision`
+     * was `"ERROR"` — this indicates a transient downstream provider
+     * issue. Do not rerun a check whose `decision` was `"FAIL"`;
+     * resubmitting returns the same `"FAIL"` result again.
+     */
+    rerun(profileId: string, signal?: AbortSignal): Promise<IdentityProfile>;
+}
+
+/**
+ * Bank Account Validation API: a redirect-based open-banking flow that
+ * lets a customer verify bank account ownership before payouts are sent
+ * to that account. Available for Canada and the United States.
+ */
+declare class BankAccountValidationResource {
+    private readonly cfg;
+    private readonly transport;
+    constructor(cfg: ResolvedConfig, transport: HttpTransport);
+    /**
+     * Starts a bank account verification session. Redirect the customer to
+     * {@link bankVerificationRedirectUrl} to complete the flow; there is no
+     * synchronous result.
+     */
+    create(accountId: string | undefined, req: CreateBankVerificationRequest, signal?: AbortSignal): Promise<BankVerification>;
+    /**
+     * Looks up a bank account verification by ID. Returns validated
+     * account details and a single-use payment token once the customer has
+     * completed the redirect flow.
+     */
+    get(verificationId: string, signal?: AbortSignal): Promise<BankVerification>;
+}
+/**
+ * Interac Verification Service (VerifiedMe): AML Assist Verification via
+ * the customer's bank login credentials, through the Interac digital
+ * identity network. Available only in Canada. Shares the
+ * `/bankaccountvalidator/v1` base path with Bank Account Validation,
+ * under `/verifiedme`.
+ */
+declare class InteracVerificationResource {
+    private readonly cfg;
+    private readonly transport;
+    constructor(cfg: ResolvedConfig, transport: HttpTransport);
+    /** Starts an Interac AML Assist verification session. */
+    create(accountId: string | undefined, req: CreateInteracVerificationRequest, signal?: AbortSignal): Promise<BankVerification>;
+    /**
+     * Fetches the user's verified information once they have completed the
+     * redirect flow on Interac's bank page.
+     */
+    get(verificationId: string, signal?: AbortSignal): Promise<BankVerification>;
+}
+/**
+ * Returns the URL the customer should be sent to in order to complete
+ * the bank validation or Interac flow.
+ */
+declare function bankVerificationRedirectUrl(verification: BankVerification): string | undefined;
+
+/** Categorises a webhook event by the resource it concerns. */
+type WebhookTopic = "payment_handle" | "payment" | "settlement" | "refund" | "payout" | "subscription" | "account_updater" | "unknown";
+/** A decoded and verified Paysafe webhook event. */
+interface PaysafeWebhookEvent {
+    eventName: string;
+    eventType?: string;
+    eventDate?: string;
+    type?: string;
+    resourceId?: string;
+    attemptNumber?: string;
+    payload?: Record<string, unknown>;
+    links?: unknown[];
+}
+
+/**
+ * Verifies HMAC-SHA256 webhook signatures and parses event payloads.
+ * Stateless and safe for concurrent use; construct once per HMAC key (or
+ * once and pass the key per call).
+ */
+declare class WebhooksResource {
+    /**
+     * Verifies the HMAC-SHA256 signature of `rawBody` against `signature`
+     * using `hmacKey`, then decodes the payload into a
+     * {@link PaysafeWebhookEvent}.
+     *
+     * @param rawBody - The exact, unmodified request body bytes/text as received.
+     * @param signature - The value of the `Signature` HTTP header.
+     * @param hmacKey - The merchant's webhook HMAC key from the Paysafe portal.
+     *
+     * Verification uses a constant-time comparison to prevent timing
+     * attacks.
+     */
+    verifyAndParse(rawBody: string | Uint8Array, signature: string, hmacKey: string): Promise<PaysafeWebhookEvent>;
+    /**
+     * Verifies the webhook signature without parsing the body. Resolves on
+     * success, or throws a {@link PaysafeError} with
+     * `kind === "webhook_signature_mismatch"` on failure.
+     */
+    verifySignature(rawBody: string | Uint8Array, signature: string, hmacKey: string): Promise<void>;
+    /**
+     * Decodes a webhook body that has already been verified (e.g. by a
+     * signature-checking middleware) into a {@link PaysafeWebhookEvent}.
+     */
+    parse(rawBody: string | Uint8Array): PaysafeWebhookEvent;
+    /**
+     * Parses an already-decoded object into a {@link PaysafeWebhookEvent},
+     * useful when the caller's web framework has already deserialized the
+     * JSON body.
+     */
+    parseObject(obj: Record<string, unknown>): PaysafeWebhookEvent;
+}
+/** Classifies `event` by its `eventName` prefix. */
+declare function webhookTopic(event: PaysafeWebhookEvent): WebhookTopic;
+/**
+ * Extracts the payment-handle lifecycle status implied by `event`'s
+ * name, or `undefined` for non-payment-handle events.
+ */
+declare function webhookPaymentHandleStatus(event: PaysafeWebhookEvent): string | undefined;
+
+/**
+ * The top-level Paysafe SDK client. Construct one with `new
+ * PaysafeClient(options)` or {@link PaysafeClient.fromEnv}, then call
+ * operations through its resource properties (`paymentHandles`,
+ * `payments`, `customers`, `plans`, `subscriptions`, `applications`,
+ * `webhooks`, ...).
+ *
+ * A `PaysafeClient` is safe for concurrent use across multiple requests.
+ *
+ * @example
+ * ```ts
+ * const client = new PaysafeClient({
+ *   username: "1001062690",
+ *   password: "B-qa2-0-...",
+ *   environment: "test",
+ *   accountId: "1009688230",
+ * });
+ *
+ * const handle = await client.paymentHandles.create({
+ *   merchantRefNum: "order-1",
+ *   amount: 5000,
+ *   currencyCode: "USD",
+ *   paymentType: "CARD",
+ *   transactionType: "PAYMENT",
+ *   card: {
+ *     cardNum: "4111111111111111",
+ *     cardExpiry: { month: 12, year: 2030 },
+ *     cvv: "123",
+ *     holderName: "Jane Doe",
+ *   },
+ *   billingDetails: { street: "123 Main St", city: "New York", state: "NY", country: "US", zip: "10001" },
+ * });
+ *
+ * const payment = await client.payments.create({
+ *   merchantRefNum: "payment-001",
+ *   amount: 5000,
+ *   currencyCode: "USD",
+ *   paymentHandleToken: handle.paymentHandleToken,
+ * });
+ * ```
+ */
+declare class PaysafeClient {
+    private readonly cfg;
+    readonly paymentHandles: PaymentHandlesResource;
+    readonly payments: PaymentsResource;
+    readonly settlements: SettlementsResource;
+    readonly refunds: RefundsResource;
+    readonly payouts: PayoutsResource;
+    readonly verifications: VerificationsResource;
+    readonly customers: CustomersResource;
+    readonly plans: PlansResource;
+    readonly subscriptions: SubscriptionsResource;
+    readonly applications: ApplicationsResource;
+    readonly fxRates: FxRatesResource;
+    readonly customerIdentity: CustomerIdentityResource;
+    readonly bankAccountValidation: BankAccountValidationResource;
+    readonly interacVerification: InteracVerificationResource;
+    readonly webhooks: WebhooksResource;
+    constructor(options: PaysafeClientOptions, telemetryHook?: TelemetryHook);
+    /**
+     * Builds a `PaysafeClient` from `PAYSAFE_USERNAME`, `PAYSAFE_PASSWORD`,
+     * `PAYSAFE_ENVIRONMENT`, and `PAYSAFE_ACCOUNT_ID` environment variables
+     * (Node.js only), merged with any additional `overrides` (last-wins).
+     */
+    static fromEnv(overrides?: Partial<PaysafeClientOptions>, telemetryHook?: TelemetryHook): PaysafeClient;
+    /** The client's configured default account ID, if set. */
+    get accountId(): string | undefined;
+    /** The client's configured environment (`"test"` or `"production"`). */
+    get environment(): Environment;
+    /** The resolved base URL the client sends requests to. */
+    get baseUrl(): string;
+}
+
+/**
+ * Structured error taxonomy for the Paysafe SDK, mirroring the reference
+ * Go and Elixir implementations so callers can branch reliably.
+ */
+/** Classifies the failure mode of a {@link PaysafeError}. */
+type PaysafeErrorKind = "api_error" | "http_error" | "rate_limited" | "timeout" | "invalid_config" | "invalid_params" | "webhook_signature_mismatch" | "decode_error" | "context_canceled";
+/** A single field-level validation error returned by the Paysafe API. */
+interface PaysafeFieldError {
+    field: string;
+    error: string;
+}
+interface PaysafeErrorInit {
+    kind: PaysafeErrorKind;
+    message: string;
+    code?: string;
+    httpStatus?: number;
+    fieldErrors?: PaysafeFieldError[];
+    details?: Record<string, unknown>;
+    retryable?: boolean;
+    cause?: unknown;
+}
+/**
+ * The structured error type thrown by every Paysafe SDK operation.
+ * Every rejected promise from this SDK rejects with an instance of
+ * `PaysafeError` (never a bare string or plain object).
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.payments.create(req);
+ * } catch (err) {
+ *   if (err instanceof PaysafeError) {
+ *     console.error(err.kind, err.code, err.message, err.fieldErrors);
+ *   }
+ * }
+ * ```
+ */
+declare class PaysafeError extends Error {
+    readonly kind: PaysafeErrorKind;
+    readonly code?: string;
+    readonly httpStatus?: number;
+    readonly fieldErrors: PaysafeFieldError[];
+    readonly details?: Record<string, unknown>;
+    readonly retryable: boolean;
+    constructor(init: PaysafeErrorInit);
+    /** Whether the SDK's retry policy should attempt this request again. */
+    isRetryable(): boolean;
+    static fromApiResponse(body: Record<string, unknown>, httpStatus: number): PaysafeError;
+    static httpError(cause: unknown, timedOut: boolean): PaysafeError;
+    static rateLimited(): PaysafeError;
+    static invalidParams(message: string): PaysafeError;
+    static invalidConfig(message: string): PaysafeError;
+    static webhookMismatch(): PaysafeError;
+    static decodeError(cause: unknown): PaysafeError;
+    static contextCanceled(cause: unknown): PaysafeError;
+}
+
+export { type Address, type Application, type ApplicationContact, type ApplicationStatus, ApplicationsResource, BankAccountValidationResource, type BankVerification, type BankVerificationProfile, type BankVerificationStatus, type BillingCycle, type BillingDetails, type Card, type CardExpiry, type CreateApplicationRequest, type CreateBankVerificationRequest, type CreateCustomerPaymentHandleRequest, type CreateCustomerRequest, type CreateInteracVerificationRequest, type CreatePaymentHandleRequest, type CreatePaymentRequest, type CreatePayoutRequest, type CreatePlanRequest, type CreateRefundRequest, type CreateSettlementRequest, type CreateSubscriptionRequest, type CreateVerificationRequest, type Customer, CustomerIdentityResource, CustomersResource, type DateOfBirth, type Environment, type ExecutionMode, type FetchLike, type FxRate, FxRatesResource, type GetFxRateRequest, type HandleAction, type HandleStatus, type HandleUsage, type IdentityAddress, type IdentityDateOfBirth, type IdentityDecision, type IdentityProfile, type IdentityProfileInput, type InlineProfile, InteracVerificationResource, type ListPaymentHandlesResponse, type ListPaymentsFilter, type ListPaymentsResponse, type ListPlansResponse, type ListSubscriptionsFilter, type ListSubscriptionsResponse, type NetworkToken, type Payment, type PaymentHandle, PaymentHandlesResource, type PaymentMethodDetails, type PaymentStatus, PaymentsResource, type Payout, PayoutsResource, PaysafeClient, type PaysafeClientOptions, PaysafeError, type PaysafeErrorInit, type PaysafeErrorKind, type PaysafeFieldError, type PaysafeLink, type PaysafeWebhookEvent, type Plan, type PlanStatus, PlansResource, type RateLimitConfig, type Refund, type RefundStatus, RefundsResource, type SavedCard, type Settlement, type SettlementStatus, type SettlementSummary, SettlementsResource, type SingleUseCustomerToken, type Subscription, type SubscriptionStatus, SubscriptionsResource, type TelemetryExceptionMeta, type TelemetryHook, type TelemetryStartMeta, type TelemetryStopMeta, type ThreeDS, type TransactionType, type UpdateCustomerRequest, type UpdatePlanRequest, type UpdateSubscriptionRequest, type UploadDocumentRequest, type Verification, VerificationsResource, type VerifyIdentityRequest, type WebhookTopic, WebhooksResource, bankVerificationRedirectUrl, findLinkByRel, paymentHandleRedirectUrl, paymentHandleRequiresAction, webhookPaymentHandleStatus, webhookTopic };