rpay-sdk 0.0.0-stage → 1.0.0

package/index.d.ts

@@ -0,0 +1,1104 @@
+export type RPayBankKey =
+  | "vietcombank"
+  | "acb"
+  | "mbbank"
+  | "techcombank"
+  | "bidv"
+  | "vietinbank"
+  | "vpbank"
+  | "tpbank"
+  | "agribank"
+  | "msb"
+  | "ocb"
+  | "seabank"
+  | "eximbank"
+  | "bvbank"
+  | "viettelpay";
+
+export type RPayBankCode =
+  | "VCB"
+  | "ACB"
+  | "MB"
+  | "TCB"
+  | "BIDV"
+  | "ICB"
+  | "VPB"
+  | "TPB"
+  | "VBA"
+  | "MSB"
+  | "OCB"
+  | "SEAB"
+  | "EIB"
+  | "BVB"
+  | "VTP";
+
+export type RPayUsdtNetworkCode =
+  | "TRC20"
+  | "BEP20"
+  | "ERC20"
+  | "POLYGON"
+  | "ARBITRUM"
+  | "OPTIMISM"
+  | "SOLANA"
+  | "TON"
+  | "BASE"
+  | "AVALANCHE"
+  | "APTOS"
+  | "SUI"
+  | "OPBNB"
+  | "CELO"
+  | "SCROLL"
+  | "KAVA"
+  | "POLKADOT"
+  | "OSMOSIS";
+
+export type RPayCryptoTokenSymbol = "USDT" | "USDC";
+export type RPayPaymentChannel = "bank" | "usdt";
+
+export interface RPayBankSpec {
+  readonly key: RPayBankKey;
+  readonly code: RPayBankCode;
+  readonly shortName: string;
+  readonly fullName: string;
+  readonly bin: string;
+  readonly apiSlug: string;
+  readonly primarySlug: string;
+  readonly aliases: readonly string[];
+  readonly logo: string;
+  readonly v3UsesPhonePin: boolean;
+}
+
+export interface RPayUsdtNetworkSpec {
+  readonly network: RPayUsdtNetworkCode;
+  readonly name: string;
+  readonly chainKey: string;
+  readonly tokenStandard: string;
+  readonly decimals: number;
+  readonly usdtContract: string;
+  readonly usdcContract: string;
+  readonly explorerBaseUrl: string;
+  readonly avgConfirmSeconds: number;
+  readonly recommendedFeeText: string;
+}
+
+export interface RPayErrorOptions {
+  code?: string;
+  status?: number;
+  details?: unknown;
+  endpoint?: string;
+  method?: string;
+  rawResponse?: unknown;
+}
+
+export declare class RPayError extends Error {
+  code: string;
+  status: number;
+  details: unknown;
+  endpoint: string;
+  method: string;
+  rawResponse: unknown;
+  constructor(message: string, options?: RPayErrorOptions);
+}
+
+export interface RPayClientConfig {
+  /** Base URL of the RPAY API server (default: `"https://api.rpay.vn"` or `process.env.RPAY_DOMAIN`). */
+  baseUrl?: string;
+  /** Target domain or origin (e.g. `"pay.shopa.vn"`, `"https://pay.shopa.vn"`, or `"auto"` in browser). */
+  domain?: string;
+  /** White-label child site domain forwarded in `X-Site-Domain` and `X-Forwarded-Host`. */
+  siteDomain?: string;
+  /** Tenant Site ID forwarded in `X-Site-ID`. */
+  siteId?: string;
+  /** Default Bank API Token (`rpay_<slug>_live_...` or `process.env.RPAY_BANK_TOKEN`). */
+  apiToken?: string;
+  /** Alias for `apiToken` or `usdtApiKey`. */
+  apiKey?: string;
+  /** Alias for `apiToken`. */
+  bankToken?: string;
+  /** Default Merchant ID for USDT/USDC Crypto Store Gateway (`MRCH-...` or `process.env.RPAY_MERCHANT_ID`). */
+  merchantId?: string;
+  /** Default API Key for USDT/USDC Crypto Store Gateway (`process.env.RPAY_USDT_API_KEY`). */
+  usdtApiKey?: string;
+  /** Alias for `usdtApiKey`. */
+  usdtKey?: string;
+  /** Default Webhook HMAC-SHA256 Secret or STC Signature Key (`process.env.RPAY_WEBHOOK_SECRET`). */
+  webhookSecret?: string;
+  /** Alias for `webhookSecret`. */
+  signatureKey?: string;
+  /** Alias for `webhookSecret`. */
+  secret?: string;
+  /** Request timeout in milliseconds (default: `60000`). */
+  timeoutMs?: number;
+  /** Custom `fetch` implementation. */
+  fetch?: typeof globalThis.fetch;
+  /** Default HTTP headers included in every request. */
+  headers?: Record<string, string>;
+}
+
+export interface RPayRequestOptions {
+  domain?: string;
+  siteDomain?: string;
+  siteId?: string;
+  timeoutMs?: number;
+  headers?: Record<string, string>;
+  idempotencyKey?: string;
+  apiToken?: string;
+  apiKey?: string;
+}
+
+export type RPayBankInvoiceStatus =
+  | "pending"
+  | "paid"
+  | "reconciled"
+  | "expired"
+  | "cancelled";
+
+export type RPayQRLogoMode =
+  | "bank"
+  | "rpay"
+  | "custom_url"
+  | "custom_upload"
+  | "none";
+
+export interface RPayCreateBankInvoiceInput {
+  amountVnd?: number;
+  amount?: number;
+  orderId?: string;
+  transferContent?: string;
+  description?: string;
+  expireMinutes?: number;
+  qrLogoMode?: RPayQRLogoMode;
+  qrLogoUrl?: string;
+  redirectUrl?: string;
+  cancelUrl?: string;
+  callbackUrl?: string;
+  webhookSecret?: string;
+  provider?: "bank" | "vnpay" | "sepay";
+  apiToken?: string;
+  api_token?: string;
+  token?: string;
+  idempotencyKey?: string;
+  domain?: string;
+  siteDomain?: string;
+  siteId?: string;
+}
+
+export interface RPayBankInvoiceBeneficiaryDTO {
+  bankKey: string;
+  bankCode: string;
+  bankShortName: string;
+  bankFullName: string;
+  bankBin: string;
+  bankLogo: string;
+  accountNumber: string;
+  accountHolder: string;
+}
+
+export interface RPayBankInvoiceQRDTO {
+  content: string;
+  imageUrl: string;
+  dataUrl?: string;
+  logoMode: RPayQRLogoMode;
+  logoUrl?: string;
+}
+
+export interface RPayBankInvoiceDTO {
+  invoiceId: string;
+  invoiceCode: string;
+  orderId?: string;
+  status: RPayBankInvoiceStatus;
+  provider: string;
+  amountVnd: number;
+  paidAmountVnd: number;
+  currency: "VND";
+  transferContent: string;
+  description?: string;
+  beneficiary: RPayBankInvoiceBeneficiaryDTO;
+  qr: RPayBankInvoiceQRDTO;
+  paymentUrl: string;
+  checkoutUrl: string;
+  checkoutUrls: {
+    bank: string;
+    vnpay: string;
+    sepay: string;
+  };
+  redirectUrl?: string;
+  cancelUrl?: string;
+  hasCallback: boolean;
+  cancelToken?: string;
+  matchedTransactionId?: string;
+  matchedTransactionDate?: string;
+  matchedDescription?: string;
+  remainingSeconds: number;
+  expiresAt: string;
+  paidAt?: string;
+  cancelledAt?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/**
+ * Unified Invoice DTO compatible with BOTH Bank (VND) and Crypto (USDT / USDC).
+ */
+export interface RPayUnifiedInvoiceDTO {
+  channel: RPayPaymentChannel;
+  invoiceId: string;
+  invoiceCode: string;
+  txCode?: string;
+  orderId: string;
+  status: "pending" | "paid" | "expired" | "cancelled";
+  rawStatus: string;
+  isPaid: boolean;
+  amount: number;
+  paidAmount: number;
+  currency: "VND" | "USDT" | "USDC" | string;
+  networkOrBank: string;
+  bankBin: string;
+  recipientAddress: string;
+  recipientName: string;
+  transferContent: string;
+  description: string;
+  paymentUrl: string;
+  qrContent: string;
+  qrImageUrl: string;
+  qrDataUrl: string;
+  cancelToken?: string;
+  transactionId?: string;
+  remainingSeconds: number;
+  expiresAt?: string;
+  paidAt?: string;
+  raw: Record<string, unknown>;
+}
+
+/**
+ * Unified Transaction DTO (LSGD) compatible with BOTH Bank (POS/V2/V3) and Crypto (USDT/USDC).
+ */
+export interface RPayUnifiedTransactionDTO {
+  channel: RPayPaymentChannel;
+  transactionID: string;
+  invoiceCode: string;
+  orderId: string;
+  type: "IN" | "OUT";
+  status: "completed" | "pending" | "expired" | "cancelled";
+  amount: number;
+  currency: "VND" | "USDT" | "USDC" | string;
+  networkOrBank: string;
+  recipientAddress: string;
+  senderAddress: string;
+  description: string;
+  transactionDate: string;
+  txHash: string;
+  raw: Record<string, unknown>;
+}
+
+export interface RPayUnifiedCreateInvoiceInput {
+  channel?: "bank" | "usdt" | "crypto";
+  type?: "bank" | "usdt" | "crypto";
+  currency?: "VND" | "USDT" | "USDC" | string;
+  token?: string;
+  amount?: number;
+  amountVnd?: number;
+  amountUsdt?: number;
+  orderId?: string;
+  request_id?: string;
+  description?: string;
+  transferContent?: string;
+  network?: RPayUsdtNetworkCode | string;
+  walletAddress?: string;
+  address?: string;
+  expireMinutes?: number;
+  qrLogoMode?: RPayQRLogoMode;
+  qrLogoUrl?: string;
+  callbackUrl?: string;
+  redirectUrl?: string;
+  returnUrl?: string;
+  cancelUrl?: string;
+  webhookSecret?: string;
+  apiToken?: string;
+  apiKey?: string;
+  merchantId?: string;
+  idempotencyKey?: string;
+  useStandardGateway?: boolean;
+  domain?: string;
+  siteDomain?: string;
+  siteId?: string;
+}
+
+export interface RPayUnifiedHistoryQueryParams {
+  channel?: "bank" | "usdt" | "all" | "both";
+  type?: "bank" | "usdt" | "all" | "both";
+  version?: "v2" | "pos" | "v3" | "v1";
+  bank?: string;
+  token?: string;
+  bankToken?: string;
+  cryptoToken?: RPayCryptoTokenSymbol;
+  password?: string;
+  accountNumber?: string;
+  phone?: string;
+  pin?: string;
+  merchantId?: string;
+  usdtApiKey?: string;
+  network?: RPayUsdtNetworkCode | string;
+  status?: string;
+  fromDate?: string;
+  toDate?: string;
+  limit?: number;
+  page?: number;
+  domain?: string;
+  siteDomain?: string;
+  siteId?: string;
+}
+
+export interface RPayUnifiedHistoryResult {
+  channel: "bank" | "usdt" | "all";
+  count: number;
+  transactions: RPayUnifiedTransactionDTO[];
+  bankTransactions?: RPayUnifiedTransactionDTO[];
+  usdtTransactions?: RPayUnifiedTransactionDTO[];
+  raw: unknown;
+}
+
+export interface RPayEnvelope<T> {
+  isSuccess: boolean;
+  success: boolean;
+  status: number;
+  code: string;
+  message: string;
+  data: T;
+}
+
+export interface RPayStandardBankTransaction {
+  transactionID: string;
+  amount: string | number;
+  description: string;
+  transactionDate: string;
+  type: "IN" | "OUT";
+}
+
+export interface RPayPosTransactionsResponse {
+  status: "success" | "error";
+  msg: string;
+  bankKey?: string;
+  bankCode?: string;
+  bankShortName?: string;
+  bankBin?: string;
+  accountNumber?: string;
+  accountHolder?: string;
+  transactions: RPayStandardBankTransaction[];
+}
+
+export interface RPayV2TransactionsResponse {
+  status: "success" | "error";
+  msg: string;
+  transactions: RPayStandardBankTransaction[];
+}
+
+export interface RPayBankHistoryQueryParams {
+  token?: string;
+  bank?: string;
+  fromDate?: string;
+  toDate?: string;
+  limit?: number;
+  method?: "POST" | "GET";
+  domain?: string;
+  siteDomain?: string;
+  siteId?: string;
+}
+
+export interface RPayBankV3QueryParams extends RPayBankHistoryQueryParams {
+  password?: string;
+  accountNumber?: string;
+  phone?: string;
+  pin?: string;
+}
+
+export interface RPayTransactionMatchCriteria {
+  expectedAmount?: number | string;
+  orderCode?: string;
+  transferContent?: string;
+  exactAmount?: boolean;
+  ignoreSeparators?: boolean;
+  processedIds?: Iterable<string>;
+  mutateProcessedIds?: boolean;
+}
+
+export interface RPayUnifiedMatchCriteria extends RPayTransactionMatchCriteria {
+  channel?: "bank" | "usdt" | "all";
+  orderId?: string;
+  txHash?: string;
+}
+
+export interface RPayMatchedTransaction extends RPayStandardBankTransaction {
+  numericAmount: number;
+}
+
+export interface RPayBankTrafficNodeSnapshot {
+  bankKey: string;
+  bankCode: string;
+  shortName: string;
+  bin: string;
+  logo: string;
+  connected: boolean;
+  linkedCount: number;
+  activeCount: number;
+  errorCount: number;
+  inFlightCount: number;
+  totalRequests: number;
+  successRequests: number;
+  failedRequests: number;
+  coalescedHits: number;
+  lastLatencyMs: number;
+  lastPollAt?: string;
+  status: "online" | "busy" | "error" | "standby";
+}
+
+export interface RPayBankTrafficSnapshot {
+  updatedAt: string;
+  connectedBanksCount: number;
+  totalBanksCount: number;
+  totalSystemRequests: number;
+  totalInFlightRequests: number;
+  coalescedRequests: number;
+  banks: RPayBankTrafficNodeSnapshot[];
+}
+
+export interface RPayCreateVietQRInput {
+  bank?: string;
+  bankBin?: string;
+  bankNumber?: string;
+  account?: string;
+  accountNumber?: string;
+  amount?: string | number;
+  purpose?: string;
+  memo?: string;
+  content?: string;
+  transferContent?: string;
+  orderId?: string;
+  size?: number;
+  withLogo?: boolean;
+  logo?: RPayQRLogoMode;
+  logoUrl?: string;
+  logoDataUrl?: string;
+  domain?: string;
+  siteDomain?: string;
+  siteId?: string;
+}
+
+export interface RPayVietQRResultDTO {
+  bank: {
+    code: string;
+    shortName: string;
+    fullName: string;
+    bin: string;
+    logoUrl: string;
+  };
+  bankNumber: string;
+  amount?: string;
+  purpose?: string;
+  isDynamic: boolean;
+  withLogo: boolean;
+  logoMode: string;
+  size: number;
+  content: string;
+  qrDataUrl: string;
+  qrImageUrl: string;
+}
+
+export interface RPayUsdtAddInvoiceInput {
+  merchant_id?: string;
+  merchantId?: string;
+  api_key?: string;
+  apiKey?: string;
+  name?: string;
+  description?: string;
+  amount: number | string;
+  token?: RPayCryptoTokenSymbol;
+  request_id?: string;
+  orderId?: string;
+  callback_url?: string;
+  callbackUrl?: string;
+  success_url?: string;
+  returnUrl?: string;
+  redirectUrl?: string;
+  cancel_url?: string;
+  cancelUrl?: string;
+  network?: RPayUsdtNetworkCode | string;
+  address?: string;
+  expireMinutes?: number;
+  domain?: string;
+  siteDomain?: string;
+  siteId?: string;
+}
+
+export interface RPayCreatePublicUsdtInvoiceInput {
+  apiKey?: string;
+  api_key?: string;
+  apiToken?: string;
+  merchantId?: string;
+  merchant_id?: string;
+  orderId?: string;
+  order_id?: string;
+  amountUsdt?: number;
+  amount?: number;
+  exchangeRate?: number;
+  network?: RPayUsdtNetworkCode | string;
+  token?: RPayCryptoTokenSymbol;
+  walletAddress?: string;
+  address?: string;
+  expireMinutes?: number;
+  description?: string;
+  callbackUrl?: string;
+  returnUrl?: string;
+  cancelUrl?: string;
+  domain?: string;
+  siteDomain?: string;
+  siteId?: string;
+}
+
+export interface RPaySelectUsdtPaymentOptionInput {
+  token?: RPayCryptoTokenSymbol;
+  network?: RPayUsdtNetworkCode | string;
+  walletId?: string;
+  walletAddress?: string;
+}
+
+export interface RPayWebhookVerificationResult {
+  verified: boolean;
+  reason: string;
+  scheme: string;
+  event: string;
+  canonicalPayload?: string;
+  bank?: string;
+  accountNumber?: string;
+  payload: Record<string, unknown> | null;
+}
+
+export interface RPayUnifiedWebhookEvent extends RPayWebhookVerificationResult {
+  channel: RPayPaymentChannel;
+  invoiceCode: string;
+  orderId: string;
+  status: string;
+  amount: number;
+  paidAmount: number;
+  currency: string;
+  networkOrBank: string;
+  transactionId: string;
+  transferContent: string;
+  recipientAddress: string;
+  senderAddress: string;
+  transactions: RPayStandardBankTransaction[];
+}
+
+export interface RPayWebhookHandlerCallbacks {
+  secret?: string;
+  onPaid?: (event: RPayUnifiedWebhookEvent, req?: unknown) => Promise<void> | void;
+  onTransactions?: (event: RPayUnifiedWebhookEvent, req?: unknown) => Promise<void> | void;
+  onEvent?: (event: RPayUnifiedWebhookEvent, req?: unknown) => Promise<void> | void;
+  onError?: (err: unknown, req?: unknown, res?: unknown) => void;
+}
+
+export interface RPayRouteOptions {
+  /** Action override (`"lsgd"`, `"history"`, `"transactions"`, `"invoice"`). */
+  action?: string;
+  /** Channel (`"bank"`, `"usdt"`, `"all"`). */
+  channel?: "bank" | "usdt" | "all" | "both";
+  /** Target domain override (e.g. `"pay.shopa.vn"`). */
+  domain?: string;
+  siteDomain?: string;
+  siteId?: string;
+  /** Router provider name (e.g. `"9ROUTER"`). */
+  provider?: string;
+  /** Security mode (e.g. `"HMAC_256"`). */
+  security?: string;
+  /** Coalesced request counter label (e.g. `"498.310 req"`). */
+  coalesced?: string;
+  /** Target bank code, slug, or BIN (e.g. `"VCB"`). */
+  bank?: string;
+  /** Target bank BIN (e.g. `"970436"`). */
+  bankBin?: string;
+  /** Recipient bank account number (when generating VietQR directly). */
+  bankNumber?: string;
+  accountNumber?: string;
+  account?: string;
+  /** Payment amount in VND or USDT. */
+  amount?: number;
+  amountVnd?: number;
+  amountUsdt?: number;
+  /** Merchant order reference. */
+  orderId?: string;
+  transferContent?: string;
+  description?: string;
+  memo?: string;
+  /** Blockchain network code for crypto payments (`"TRC20"`, `"BEP20"`, ...). */
+  network?: RPayUsdtNetworkCode | string;
+  /** Crypto token symbol (`"USDT"` | `"USDC"`). */
+  token?: string;
+  currency?: string;
+  /** Incoming webhook payload to verify & auto-route. */
+  payload?: Record<string, unknown> | string | Uint8Array;
+  /** Raw webhook request body for `X-RPay-Body-Signature` / `X-STC-HMAC-SHA256` verification. */
+  rawBody?: string | Uint8Array;
+  /** Incoming HTTP request headers for webhook verification. */
+  headers?: Record<string, string | string[] | undefined> | Headers;
+  /** Webhook secret or signature key. */
+  secret?: string;
+  webhookSecret?: string;
+  signatureKey?: string;
+  /** Bank API token override. */
+  apiToken?: string;
+  apiKey?: string;
+  /** Skip network call in router mode and use local snapshot. */
+  offline?: boolean;
+  /** Throw HTTP errors instead of falling back in router mode. */
+  strictHttp?: boolean;
+  [key: string]: unknown;
+}
+
+export interface RPayRouteResult {
+  ok: boolean;
+  mode: "router" | "payment" | "vietqr" | "crypto" | "webhook" | "lsgd";
+  provider: string;
+  security: string;
+  coalesced?: string;
+  socketLive?: boolean;
+  connectedBanksCount?: number;
+  totalBanksCount?: number;
+  badge?: string;
+  snapshot?: RPayBankTrafficSnapshot;
+  bank?: RPayBankSpec | { code: string } | null;
+  amount?: number;
+  network?: string;
+  invoice?: RPayUnifiedInvoiceDTO | RPayBankInvoiceDTO | Record<string, unknown>;
+  qr?: RPayVietQRResultDTO | Record<string, unknown>;
+  transactions?: RPayUnifiedTransactionDTO[];
+  data?: unknown;
+  verified?: boolean;
+  reason?: string;
+  scheme?: string;
+  event?: string;
+  payload?: Record<string, unknown> | null;
+}
+
+export declare class RPayClient {
+  config: Required<
+    Pick<
+      RPayClientConfig,
+      | "baseUrl"
+      | "domain"
+      | "siteDomain"
+      | "siteId"
+      | "apiToken"
+      | "merchantId"
+      | "usdtApiKey"
+      | "webhookSecret"
+      | "timeoutMs"
+      | "headers"
+    >
+  > & {
+    fetch?: typeof globalThis.fetch;
+  };
+
+  constructor(config?: RPayClientConfig);
+
+  configure(nextConfig?: Partial<RPayClientConfig>): this;
+
+  /** Alias for `configure(...)` — Khởi tạo nhanh cấu hình RPAY SDK. */
+  init(nextConfig?: Partial<RPayClientConfig>): this;
+
+  /** Registers or updates a domain-scoped client (`"pay.shopa.vn"`). */
+  registerDomain(domain: string, overrides?: Partial<RPayClientConfig>): RPayClient;
+
+  /** Retrieves or creates a domain-scoped client (`"pay.shopa.vn"`). */
+  forDomain(domain: string, overrides?: Partial<RPayClientConfig>): RPayClient;
+
+  /** Lists all registered domain hostnames. */
+  listDomains(): string[];
+
+  request<T = unknown>(options: {
+    method: string;
+    path: string;
+    domain?: string;
+    siteDomain?: string;
+    siteId?: string;
+    query?: Record<string, unknown>;
+    body?: unknown;
+    headers?: Record<string, string>;
+    bearerToken?: string;
+    apiKey?: string;
+    idempotencyKey?: string;
+    timeoutMs?: number;
+    allowLogicError?: boolean;
+  }): Promise<T>;
+
+  /** Unified Invoice Creation — works for BOTH Bank (VND) & Crypto (USDT/USDC). */
+  createInvoice(
+    input: RPayUnifiedCreateInvoiceInput,
+    reqOptions?: RPayRequestOptions
+  ): Promise<RPayUnifiedInvoiceDTO>;
+
+  /** Shorthand one-liner for `createInvoice(input)` — Tạo thanh toán nhanh cho cả Bank (VNĐ) & USDT/USDC. */
+  pay(
+    input: RPayUnifiedCreateInvoiceInput,
+    reqOptions?: RPayRequestOptions
+  ): Promise<RPayUnifiedInvoiceDTO>;
+
+  /** Shorthand one-liner to generate a VietQR code (`{ bank, account, amount, memo }`). */
+  qr(
+    input: RPayCreateVietQRInput,
+    reqOptions?: RPayRequestOptions
+  ): Promise<RPayVietQRResultDTO>;
+
+  /** Unified Invoice Status Lookup — works for BOTH Bank (`RPINV...`) & USDT (`USINV...`/`USTX...`). */
+  getInvoice(
+    invoiceCode: string,
+    options?: RPayRequestOptions & { channel?: RPayPaymentChannel }
+  ): Promise<RPayUnifiedInvoiceDTO>;
+
+  /** Shorthand alias for `getInvoice(code, options)`. */
+  status(
+    invoiceCode: string,
+    options?: RPayRequestOptions & { channel?: RPayPaymentChannel }
+  ): Promise<RPayUnifiedInvoiceDTO>;
+
+  /** Unified Immediate Live Reconciliation Check — works for BOTH Bank & USDT. */
+  checkInvoice(
+    invoiceCode: string,
+    options?: RPayRequestOptions & { channel?: RPayPaymentChannel }
+  ): Promise<RPayUnifiedInvoiceDTO>;
+
+  /** Shorthand alias for `checkInvoice(code, options)`. */
+  check(
+    invoiceCode: string,
+    options?: RPayRequestOptions & { channel?: RPayPaymentChannel }
+  ): Promise<RPayUnifiedInvoiceDTO>;
+
+  /** Unified Payment Polling — works for BOTH Bank & USDT. */
+  waitForPayment(
+    invoiceCode: string,
+    options?: RPayRequestOptions & {
+      channel?: RPayPaymentChannel;
+      intervalMs?: number;
+      timeoutMs?: number;
+      triggerLiveCheck?: boolean;
+      onTick?: (invoice: RPayUnifiedInvoiceDTO) => void;
+    }
+  ): Promise<RPayUnifiedInvoiceDTO>;
+
+  /** Unified Transaction History (LSGD) — works for `"bank"`, `"usdt"`, or `"all"` (both in parallel). */
+  getHistory(params?: RPayUnifiedHistoryQueryParams): Promise<RPayUnifiedHistoryResult>;
+
+  /** Alias for `getHistory` — Tra cứu Lịch sử Giao dịch (LSGD) hợp nhất Bank & USDT. */
+  lsgd(params?: RPayUnifiedHistoryQueryParams): Promise<RPayUnifiedHistoryResult>;
+
+  /** Alias for `getHistory` — Tra cứu danh sách giao dịch hợp nhất Bank & USDT. */
+  getTransactions(params?: RPayUnifiedHistoryQueryParams): Promise<RPayUnifiedHistoryResult>;
+
+  /** Unified Idempotent Payment Matcher across Bank & USDT transactions. */
+  matchPayment(
+    transactions: RPayUnifiedTransactionDTO[],
+    criteria?: RPayUnifiedMatchCriteria
+  ): RPayUnifiedTransactionDTO[];
+
+  route(options?: RPayRouteOptions): Promise<RPayRouteResult>;
+
+  invoices: {
+    create(
+      input: RPayCreateBankInvoiceInput,
+      reqOptions?: RPayRequestOptions
+    ): Promise<RPayEnvelope<RPayBankInvoiceDTO>>;
+    createUnified(
+      input: RPayUnifiedCreateInvoiceInput,
+      reqOptions?: RPayRequestOptions
+    ): Promise<RPayUnifiedInvoiceDTO>;
+    get(
+      invoiceCode: string,
+      reqOptions?: RPayRequestOptions
+    ): Promise<RPayEnvelope<RPayBankInvoiceDTO>>;
+    check(
+      invoiceCode: string,
+      reqOptions?: RPayRequestOptions
+    ): Promise<RPayEnvelope<RPayBankInvoiceDTO>>;
+    cancel(
+      invoiceCode: string,
+      cancelToken: string,
+      reqOptions?: RPayRequestOptions
+    ): Promise<RPayEnvelope<RPayBankInvoiceDTO>>;
+    waitForSettlement(
+      invoiceCode: string,
+      pollOptions?: {
+        domain?: string;
+        siteId?: string;
+        intervalMs?: number;
+        timeoutMs?: number;
+        triggerLiveCheck?: boolean;
+        onTick?: (invoice: RPayBankInvoiceDTO) => void;
+      }
+    ): Promise<RPayBankInvoiceDTO>;
+  };
+
+  banks: {
+    listLocalCatalog(): readonly RPayBankSpec[];
+    resolve(identifier: string): RPayBankSpec | null;
+    catalog(reqOptions?: RPayRequestOptions): Promise<RPayEnvelope<RPayBankSpec[]>>;
+    status(reqOptions?: RPayRequestOptions): Promise<RPayEnvelope<unknown>>;
+    trafficSnapshot(
+      reqOptions?: RPayRequestOptions
+    ): Promise<RPayEnvelope<RPayBankTrafficSnapshot>>;
+    buildTrafficStreamUrl(domain?: string): string;
+    buildTrafficWebSocketUrl(domain?: string): string;
+    pos(
+      params?: RPayBankHistoryQueryParams | string
+    ): Promise<RPayPosTransactionsResponse>;
+    v2(
+      params?: RPayBankHistoryQueryParams | string
+    ): Promise<RPayV2TransactionsResponse>;
+    buildV3GetUrl(params: RPayBankV3QueryParams): string;
+    v3(params: RPayBankV3QueryParams): Promise<RPayV2TransactionsResponse>;
+    v1(params?: RPayBankHistoryQueryParams | string): Promise<unknown>;
+    matchTransactions(
+      transactions: RPayStandardBankTransaction[],
+      criteria?: RPayTransactionMatchCriteria
+    ): RPayMatchedTransaction[];
+    findMatchingTransaction(
+      transactions: RPayStandardBankTransaction[],
+      criteria?: RPayTransactionMatchCriteria
+    ): RPayMatchedTransaction | null;
+  };
+
+  history: RPayClient["banks"];
+
+  pos: {
+    getTransactions(
+      params?: RPayBankHistoryQueryParams | string
+    ): Promise<RPayPosTransactionsResponse>;
+  };
+
+  vietqr: {
+    listBanks(reqOptions?: RPayRequestOptions): Promise<RPayEnvelope<unknown>>;
+    getBankLogoUrl(bankOrBin: string, domain?: string): string;
+    create(
+      input: RPayCreateVietQRInput,
+      reqOptions?: RPayRequestOptions
+    ): Promise<RPayEnvelope<RPayVietQRResultDTO>>;
+    buildPngUrl(input: RPayCreateVietQRInput): string;
+  };
+
+  usdt: {
+    listLocalNetworks(): readonly RPayUsdtNetworkSpec[];
+    resolveNetwork(network: string): RPayUsdtNetworkSpec | null;
+    listPublicNetworks(
+      reqOptions?: RPayRequestOptions
+    ): Promise<RPayEnvelope<RPayUsdtNetworkSpec[]>>;
+    addInvoice(
+      input: RPayUsdtAddInvoiceInput,
+      reqOptions?: RPayRequestOptions
+    ): Promise<Record<string, unknown>>;
+    getInvoiceStatus(
+      input: {
+        merchant_id?: string;
+        merchantId?: string;
+        api_key?: string;
+        apiKey?: string;
+        trans_id: string;
+        network?: string;
+        address?: string;
+        domain?: string;
+        siteId?: string;
+      },
+      reqOptions?: RPayRequestOptions
+    ): Promise<Record<string, unknown>>;
+    getInvoiceHistory(
+      input?: Record<string, unknown>,
+      reqOptions?: RPayRequestOptions
+    ): Promise<Record<string, unknown>>;
+    getNetworks(
+      input?: Record<string, unknown>,
+      reqOptions?: RPayRequestOptions
+    ): Promise<Record<string, unknown>>;
+    createPublicInvoice(
+      input: RPayCreatePublicUsdtInvoiceInput,
+      reqOptions?: RPayRequestOptions
+    ): Promise<RPayEnvelope<Record<string, unknown>>>;
+    getPublicInvoice(
+      code: string,
+      reqOptions?: RPayRequestOptions
+    ): Promise<RPayEnvelope<Record<string, unknown>>>;
+    selectPaymentOption(
+      code: string,
+      selection: RPaySelectUsdtPaymentOptionInput,
+      reqOptions?: RPayRequestOptions
+    ): Promise<RPayEnvelope<Record<string, unknown>>>;
+    checkPublicInvoice(
+      code: string,
+      reqOptions?: RPayRequestOptions
+    ): Promise<RPayEnvelope<Record<string, unknown>>>;
+    waitForSettlement(
+      code: string,
+      pollOptions?: {
+        domain?: string;
+        siteId?: string;
+        intervalMs?: number;
+        timeoutMs?: number;
+        triggerOnChainCheck?: boolean;
+        onTick?: (invoice: Record<string, unknown>) => void;
+      }
+    ): Promise<Record<string, unknown>>;
+  };
+
+  webhooks: {
+    buildCanonicalPayloadString: typeof buildCanonicalPayloadString;
+    hmacSha256Hex: typeof hmacSha256Hex;
+    safeCompareSignature: typeof safeCompareSignature;
+    signCanonicalPayload: typeof signCanonicalPayload;
+    signRawBody: typeof signRawBody;
+    normalizeUnifiedWebhookEvent: typeof normalizeUnifiedWebhookEvent;
+    verifyBankInvoice(options: {
+      payload?: Record<string, unknown> | string | Uint8Array;
+      rawBody?: string | Uint8Array;
+      headers?: Record<string, string | string[] | undefined> | Headers;
+      secret?: string;
+    }): RPayWebhookVerificationResult;
+    verifyUsdt(options: {
+      payload?: Record<string, unknown> | string | Uint8Array;
+      headers?: Record<string, string | string[] | undefined> | Headers;
+      secret?: string;
+    }): RPayWebhookVerificationResult;
+    verifyTransaction(options: {
+      payload?: Record<string, unknown> | string | Uint8Array;
+      rawBody?: string | Uint8Array;
+      headers?: Record<string, string | string[] | undefined> | Headers;
+      signatureKey?: string;
+      secret?: string;
+    }): RPayWebhookVerificationResult;
+    verify(options: {
+      payload?: Record<string, unknown> | string | Uint8Array;
+      rawBody?: string | Uint8Array;
+      headers?: Record<string, string | string[] | undefined> | Headers;
+      secret?: string;
+      signatureKey?: string;
+    }): RPayUnifiedWebhookEvent;
+    /** Plug-and-play Express.js / Connect route handler. */
+    expressHandler(
+      callbacks?: RPayWebhookHandlerCallbacks
+    ): (req: any, res: any) => Promise<unknown>;
+    /** Plug-and-play Next.js App Router (`POST`) route handler. */
+    nextAppRouterHandler(
+      callbacks?: RPayWebhookHandlerCallbacks
+    ): (request: Request) => Promise<Response>;
+  };
+}
+
+export declare const RPAY_DEFAULT_BASE_URL: "https://api.rpay.vn";
+export declare const RPAY_DEFAULT_TIMEOUT_MS: 60000;
+export declare const RPAY_BANKS: readonly RPayBankSpec[];
+export declare const RPAY_USDT_NETWORKS: readonly RPayUsdtNetworkSpec[];
+
+export declare function resolveBankSpec(rawIdentifier: string): RPayBankSpec | null;
+export declare function resolveUsdtNetworkSpec(rawNetwork: string): RPayUsdtNetworkSpec | null;
+export declare function normalizeBaseUrl(urlOrDomain?: string): string;
+export declare function extractHostFromUrl(urlOrDomain?: string): string;
+export declare function encodeUrlSegment(segment: string): string;
+export declare function appendQueryParams(
+  basePath: string,
+  query?: Record<string, unknown>
+): string;
+export declare function detectPaymentChannel(
+  inputOrCode: Record<string, unknown> | string,
+  fallback?: RPayPaymentChannel
+): RPayPaymentChannel;
+export declare function normalizeInvoiceStatus(
+  rawStatus?: string
+): "pending" | "paid" | "expired" | "cancelled";
+export declare function normalizeUnifiedInvoice(
+  rawResponse: unknown,
+  hintChannel?: RPayPaymentChannel
+): RPayUnifiedInvoiceDTO;
+export declare function normalizeUnifiedTransaction(
+  rawTx: unknown,
+  channel: RPayPaymentChannel,
+  context?: { bankCode?: string; accountNumber?: string }
+): RPayUnifiedTransactionDTO;
+export declare function matchUnifiedTransactions(
+  unifiedTransactions: RPayUnifiedTransactionDTO[],
+  criteria?: RPayUnifiedMatchCriteria
+): RPayUnifiedTransactionDTO[];
+export declare function normalizeUnifiedWebhookEvent(
+  verification: RPayWebhookVerificationResult
+): RPayUnifiedWebhookEvent;
+export declare function buildCanonicalPayloadString(
+  payload: Record<string, unknown>
+): string;
+export declare function hmacSha256Hex(
+  secret: string,
+  message: string | Uint8Array
+): string;
+export declare function safeCompareSignature(
+  expected: string,
+  received: string
+): boolean;
+export declare function signCanonicalPayload(
+  payload: Record<string, unknown>,
+  secret: string
+): { signature: string; canonicalPayload: string };
+export declare function signRawBody(
+  rawBody: string | Uint8Array,
+  secret: string
+): string;
+export declare function normalizeHeaders(
+  headers?: Record<string, string | string[] | undefined> | Headers
+): Record<string, string>;
+export declare function verifyBankInvoiceWebhook(options: {
+  payload?: Record<string, unknown> | string | Uint8Array;
+  rawBody?: string | Uint8Array;
+  headers?: Record<string, string | string[] | undefined> | Headers;
+  secret: string;
+}): RPayWebhookVerificationResult;
+export declare function verifyUsdtWebhook(options: {
+  payload?: Record<string, unknown> | string | Uint8Array;
+  headers?: Record<string, string | string[] | undefined> | Headers;
+  secret: string;
+}): RPayWebhookVerificationResult;
+export declare function verifyTransactionWebhook(options: {
+  payload?: Record<string, unknown> | string | Uint8Array;
+  rawBody?: string | Uint8Array;
+  headers?: Record<string, string | string[] | undefined> | Headers;
+  signatureKey: string;
+}): RPayWebhookVerificationResult;
+export declare function verifyAnyWebhook(options: {
+  payload?: Record<string, unknown> | string | Uint8Array;
+  rawBody?: string | Uint8Array;
+  headers?: Record<string, string | string[] | undefined> | Headers;
+  secret: string;
+}): RPayUnifiedWebhookEvent;
+export declare function normalizeTransferText(
+  value: string,
+  ignoreSeparators?: boolean
+): string;
+export declare function matchTransactions(
+  transactions: RPayStandardBankTransaction[],
+  criteria?: RPayTransactionMatchCriteria
+): RPayMatchedTransaction[];
+export declare function findMatchingTransaction(
+  transactions: RPayStandardBankTransaction[],
+  criteria?: RPayTransactionMatchCriteria
+): RPayMatchedTransaction | null;
+export declare function createRPayClient(config?: RPayClientConfig): RPayClient;
+
+export type RPayDefaultInstance = RPayClient & {
+  RPayClient: typeof RPayClient;
+  RPayError: typeof RPayError;
+  createClient: typeof createRPayClient;
+  createRPayClient: typeof createRPayClient;
+  RPAY_BANKS: readonly RPayBankSpec[];
+  RPAY_USDT_NETWORKS: readonly RPayUsdtNetworkSpec[];
+  resolveBankSpec: typeof resolveBankSpec;
+  resolveUsdtNetworkSpec: typeof resolveUsdtNetworkSpec;
+  detectPaymentChannel: typeof detectPaymentChannel;
+  normalizeUnifiedInvoice: typeof normalizeUnifiedInvoice;
+  normalizeUnifiedTransaction: typeof normalizeUnifiedTransaction;
+  matchUnifiedTransactions: typeof matchUnifiedTransactions;
+  normalizeUnifiedWebhookEvent: typeof normalizeUnifiedWebhookEvent;
+};
+
+export declare const rpay: RPayDefaultInstance;
+export default rpay;