@zendfi/sdk 1.0.2 → 1.1.0

package/dist/{webhook-handler-61UWBtDI.d.mts → webhook-handler-hUfWh-_Y.d.mts}

@@ -33,6 +33,12 @@ type SubscriptionStatus = 'active' | 'canceled' | 'past_due' | 'paused';
 type InstallmentPlanStatus = 'active' | 'completed' | 'defaulted' | 'cancelled';
 type InvoiceStatus = 'draft' | 'sent' | 'paid';
 type SplitStatus = 'pending' | 'processing' | 'completed' | 'failed' | 'refunded';
+/**
+ * Recipient type discriminator for split recipients
+ * - 'wallet': Direct blockchain transfer to Solana wallet
+ * - 'bank_account': PAJ offramp (USDC → NGN → bank deposit)
+ */
+type RecipientType = 'wallet' | 'bank_account';
 type WebhookEvent = 'payment.created' | 'payment.confirmed' | 'payment.failed' | 'payment.expired' | 'subscription.created' | 'subscription.activated' | 'subscription.canceled' | 'subscription.payment_failed' | 'split.completed' | 'split.failed' | 'installment.due' | 'installment.paid' | 'installment.late' | 'invoice.sent' | 'invoice.paid';
 interface ZendFiConfig {
     apiKey?: string;
@@ -44,13 +50,38 @@ interface ZendFiConfig {
     idempotencyEnabled?: boolean;
     debug?: boolean;
 }
-interface SplitRecipient {
-    recipient_wallet: string;
+/**
+ * Split recipient - base configuration shared across both types
+ */
+interface SplitRecipientBase {
+    recipient_type: RecipientType;
     recipient_name?: string;
     percentage?: number;
     fixed_amount_usd?: number;
     split_order?: number;
 }
+/**
+ * Wallet recipient: direct blockchain transfer to Solana wallet
+ */
+interface WalletSplitRecipient extends SplitRecipientBase {
+    recipient_type: 'wallet';
+    recipient_wallet: string;
+}
+/**
+ * Bank account recipient: PAJ offramp (USDC → NGN → bank deposit)
+ */
+interface BankAccountSplitRecipient extends SplitRecipientBase {
+    recipient_type: 'bank_account';
+    recipient_account_name: string;
+    recipient_bank_account: string;
+    recipient_bank_id: string;
+    recipient_email: string;
+}
+/**
+ * Discriminated union type for split recipients
+ * Use the `recipient_type` field to determine which fields are available
+ */
+type SplitRecipient = WalletSplitRecipient | BankAccountSplitRecipient;
 interface CreatePaymentRequest {
     amount: number;
     currency?: Currency;
@@ -61,6 +92,21 @@ interface CreatePaymentRequest {
     metadata?: Record<string, any>;
     split_recipients?: SplitRecipient[];
 }
+/**
+ * Customer Object for Pre-filled Payment Links
+ */
+interface PaymentLinkCustomerObject {
+    email: string;
+    name?: string;
+    phone?: string;
+    company?: string;
+    billing_address_line1?: string;
+    billing_address_line2?: string;
+    billing_city?: string;
+    billing_state?: string;
+    billing_postal_code?: string;
+    billing_country?: string;
+}
 /**
  * Payment Link - Shareable checkout links
  */
@@ -73,6 +119,32 @@ interface CreatePaymentLinkRequest {
     expires_at?: string;
     metadata?: Record<string, any>;
     onramp?: boolean;
+    /** Original NGN amount for PAJ exact conversion (if using a NGN-denominated link) */
+    amount_ngn?: number;
+    /**
+     * If true, a service charge of max(₦30, ceil(2.5% × amount_ngn)) is added on top
+     * and shown transparently to the payer on checkout.
+     * If false/absent, no service charge is applied (merchant absorbs PAJ slippage).
+     * Only relevant when `onramp` is true.
+     */
+    payer_service_charge?: boolean;
+    /**
+     * If true, checkout shows an expanded customer details form before payment.
+     */
+    collect_customer_info?: boolean;
+    /**
+     * Optional pre-filled customer object. When present:
+     * - the checkout page skips email/info collection and shows "Continue to Pay"
+     * - `max_uses` is automatically forced to 1 (single-use link)
+     * - the customer data is stored on the link and forwarded to the onramp flow
+     */
+    customer?: PaymentLinkCustomerObject;
+    /**
+     * Optional split recipients for this link. When present, all payments created from this link
+     * will automatically apply the splits during settlement. Supports both wallet (direct blockchain transfer)
+     * and bank_account (PAJ offramp: USDC → NGN → bank) recipient types.
+     */
+    split_recipients?: SplitRecipient[];
 }
 interface PaymentLink {
     link_code: string;
@@ -96,6 +168,22 @@ interface PaymentLink {
     uses_count?: number;
     is_active?: boolean;
     onramp?: boolean;
+    /** Whether this link applies a service charge to the payer (onramp only) */
+    payer_service_charge?: boolean;
+    /** Whether the checkout page collects full customer details before payment */
+    collect_customer_info?: boolean;
+    /**
+     * Present only on customer-scoped links (created with a `customer` object).
+     * Forwarded to the checkout and onramp flow so no manual input is needed.
+     */
+    customer_data?: PaymentLinkCustomerObject;
+    /**
+     * Split recipients associated with this payment link.
+     * When split_recipients are present, all payments created from this link
+     * will automatically apply the splits. Supports both wallet (direct blockchain transfer)
+     * and bank_account (PAJ offramp: USDC → NGN → bank) recipient types.
+     */
+    split_recipients?: SplitRecipient[];
 }
 interface Payment {
     id: string;
@@ -115,7 +203,17 @@ interface Payment {
     confirmed_at?: string;
     transaction_signature?: string;
     metadata?: Record<string, any>;
-    split_ids?: string[];
+    /**
+     * Split recipient statuses (if splits were applied to this payment).
+     * Includes split ID, recipient type, amount, and settlement status.
+     */
+    split_statuses?: Array<{
+        split_id: string;
+        recipient_type: RecipientType;
+        amount_usd: number;
+        status: SplitStatus;
+        transaction_signature?: string;
+    }>;
     created_at?: string;
     updated_at?: string;
 }
@@ -317,10 +415,6 @@ type WebhookHandlers = Partial<{
     'installment.due': WebhookEventHandler;
     'installment.paid': WebhookEventHandler;
     'installment.late': WebhookEventHandler;
-    'escrow.funded': WebhookEventHandler;
-    'escrow.released': WebhookEventHandler;
-    'escrow.refunded': WebhookEventHandler;
-    'escrow.disputed': WebhookEventHandler;
     'invoice.sent': WebhookEventHandler;
     'invoice.paid': WebhookEventHandler;
 }>;
@@ -336,4 +430,4 @@ interface WebhookResult {
 }
 declare function processWebhook(a: any, b?: any, c?: any): Promise<WebhookResult>;
 
-export { type ApiKeyMode as A, type Brand as B, type CreatePaymentRequest as C, type PaymentStatus as D, type Environment as E, type SubscriptionStatus as F, type InstallmentPlanStatus as G, type InvoiceStatus as H, type InstallmentPlan as I, type SplitStatus as J, type WebhookEvent as K, type SplitRecipient as L, type MerchantId as M, type ListPaymentsRequest as N, type PaginatedResponse as O, type Payment as P, type InstallmentScheduleItem as Q, type CreateInstallmentPlanResponse as R, type SubscriptionPlan as S, type InvoiceLineItem as T, type VerifyWebhookRequest as V, type WebhookHandlerConfig as W, type ZendFiConfig as Z, type WebhookHandlers as a, type CreateSubscriptionPlanRequest as b, type CreateSubscriptionRequest as c, type Subscription as d, type CreatePaymentLinkRequest as e, type PaymentLink as f, type CreateInstallmentPlanRequest as g, type CreateInvoiceRequest as h, type Invoice as i, type WebhookPayload as j, type WebhookResult as k, type WebhookEventHandler as l, type PaymentId as m, type InvoiceId as n, type SubscriptionId as o, processWebhook as p, type InstallmentPlanId as q, type PaymentLinkCode as r, asPaymentId as s, asMerchantId as t, asInvoiceId as u, asSubscriptionId as v, asInstallmentPlanId as w, asPaymentLinkCode as x, type Currency as y, type PaymentToken as z };
+export { type InvoiceLineItem as $, type ApiKeyMode as A, type Brand as B, type CreatePaymentRequest as C, type PaymentStatus as D, type Environment as E, type SubscriptionStatus as F, type InstallmentPlanStatus as G, type InvoiceStatus as H, type InstallmentPlan as I, type SplitStatus as J, type WebhookEvent as K, type SplitRecipientBase as L, type MerchantId as M, type WalletSplitRecipient as N, type BankAccountSplitRecipient as O, type Payment as P, type SplitRecipient as Q, type RecipientType as R, type SubscriptionPlan as S, type PaymentLinkCustomerObject as T, type ListPaymentsRequest as U, type VerifyWebhookRequest as V, type WebhookHandlerConfig as W, type PaginatedResponse as X, type InstallmentScheduleItem as Y, type ZendFiConfig as Z, type CreateInstallmentPlanResponse as _, type WebhookHandlers as a, type CreateSubscriptionPlanRequest as b, type CreateSubscriptionRequest as c, type Subscription as d, type CreatePaymentLinkRequest as e, type PaymentLink as f, type CreateInstallmentPlanRequest as g, type CreateInvoiceRequest as h, type Invoice as i, type WebhookPayload as j, type WebhookResult as k, type WebhookEventHandler as l, type PaymentId as m, type InvoiceId as n, type SubscriptionId as o, processWebhook as p, type InstallmentPlanId as q, type PaymentLinkCode as r, asPaymentId as s, asMerchantId as t, asInvoiceId as u, asSubscriptionId as v, asInstallmentPlanId as w, asPaymentLinkCode as x, type Currency as y, type PaymentToken as z };

package/dist/{webhook-handler-61UWBtDI.d.ts → webhook-handler-hUfWh-_Y.d.ts}

@@ -33,6 +33,12 @@ type SubscriptionStatus = 'active' | 'canceled' | 'past_due' | 'paused';
 type InstallmentPlanStatus = 'active' | 'completed' | 'defaulted' | 'cancelled';
 type InvoiceStatus = 'draft' | 'sent' | 'paid';
 type SplitStatus = 'pending' | 'processing' | 'completed' | 'failed' | 'refunded';
+/**
+ * Recipient type discriminator for split recipients
+ * - 'wallet': Direct blockchain transfer to Solana wallet
+ * - 'bank_account': PAJ offramp (USDC → NGN → bank deposit)
+ */
+type RecipientType = 'wallet' | 'bank_account';
 type WebhookEvent = 'payment.created' | 'payment.confirmed' | 'payment.failed' | 'payment.expired' | 'subscription.created' | 'subscription.activated' | 'subscription.canceled' | 'subscription.payment_failed' | 'split.completed' | 'split.failed' | 'installment.due' | 'installment.paid' | 'installment.late' | 'invoice.sent' | 'invoice.paid';
 interface ZendFiConfig {
     apiKey?: string;
@@ -44,13 +50,38 @@ interface ZendFiConfig {
     idempotencyEnabled?: boolean;
     debug?: boolean;
 }
-interface SplitRecipient {
-    recipient_wallet: string;
+/**
+ * Split recipient - base configuration shared across both types
+ */
+interface SplitRecipientBase {
+    recipient_type: RecipientType;
     recipient_name?: string;
     percentage?: number;
     fixed_amount_usd?: number;
     split_order?: number;
 }
+/**
+ * Wallet recipient: direct blockchain transfer to Solana wallet
+ */
+interface WalletSplitRecipient extends SplitRecipientBase {
+    recipient_type: 'wallet';
+    recipient_wallet: string;
+}
+/**
+ * Bank account recipient: PAJ offramp (USDC → NGN → bank deposit)
+ */
+interface BankAccountSplitRecipient extends SplitRecipientBase {
+    recipient_type: 'bank_account';
+    recipient_account_name: string;
+    recipient_bank_account: string;
+    recipient_bank_id: string;
+    recipient_email: string;
+}
+/**
+ * Discriminated union type for split recipients
+ * Use the `recipient_type` field to determine which fields are available
+ */
+type SplitRecipient = WalletSplitRecipient | BankAccountSplitRecipient;
 interface CreatePaymentRequest {
     amount: number;
     currency?: Currency;
@@ -61,6 +92,21 @@ interface CreatePaymentRequest {
     metadata?: Record<string, any>;
     split_recipients?: SplitRecipient[];
 }
+/**
+ * Customer Object for Pre-filled Payment Links
+ */
+interface PaymentLinkCustomerObject {
+    email: string;
+    name?: string;
+    phone?: string;
+    company?: string;
+    billing_address_line1?: string;
+    billing_address_line2?: string;
+    billing_city?: string;
+    billing_state?: string;
+    billing_postal_code?: string;
+    billing_country?: string;
+}
 /**
  * Payment Link - Shareable checkout links
  */
@@ -73,6 +119,32 @@ interface CreatePaymentLinkRequest {
     expires_at?: string;
     metadata?: Record<string, any>;
     onramp?: boolean;
+    /** Original NGN amount for PAJ exact conversion (if using a NGN-denominated link) */
+    amount_ngn?: number;
+    /**
+     * If true, a service charge of max(₦30, ceil(2.5% × amount_ngn)) is added on top
+     * and shown transparently to the payer on checkout.
+     * If false/absent, no service charge is applied (merchant absorbs PAJ slippage).
+     * Only relevant when `onramp` is true.
+     */
+    payer_service_charge?: boolean;
+    /**
+     * If true, checkout shows an expanded customer details form before payment.
+     */
+    collect_customer_info?: boolean;
+    /**
+     * Optional pre-filled customer object. When present:
+     * - the checkout page skips email/info collection and shows "Continue to Pay"
+     * - `max_uses` is automatically forced to 1 (single-use link)
+     * - the customer data is stored on the link and forwarded to the onramp flow
+     */
+    customer?: PaymentLinkCustomerObject;
+    /**
+     * Optional split recipients for this link. When present, all payments created from this link
+     * will automatically apply the splits during settlement. Supports both wallet (direct blockchain transfer)
+     * and bank_account (PAJ offramp: USDC → NGN → bank) recipient types.
+     */
+    split_recipients?: SplitRecipient[];
 }
 interface PaymentLink {
     link_code: string;
@@ -96,6 +168,22 @@ interface PaymentLink {
     uses_count?: number;
     is_active?: boolean;
     onramp?: boolean;
+    /** Whether this link applies a service charge to the payer (onramp only) */
+    payer_service_charge?: boolean;
+    /** Whether the checkout page collects full customer details before payment */
+    collect_customer_info?: boolean;
+    /**
+     * Present only on customer-scoped links (created with a `customer` object).
+     * Forwarded to the checkout and onramp flow so no manual input is needed.
+     */
+    customer_data?: PaymentLinkCustomerObject;
+    /**
+     * Split recipients associated with this payment link.
+     * When split_recipients are present, all payments created from this link
+     * will automatically apply the splits. Supports both wallet (direct blockchain transfer)
+     * and bank_account (PAJ offramp: USDC → NGN → bank) recipient types.
+     */
+    split_recipients?: SplitRecipient[];
 }
 interface Payment {
     id: string;
@@ -115,7 +203,17 @@ interface Payment {
     confirmed_at?: string;
     transaction_signature?: string;
     metadata?: Record<string, any>;
-    split_ids?: string[];
+    /**
+     * Split recipient statuses (if splits were applied to this payment).
+     * Includes split ID, recipient type, amount, and settlement status.
+     */
+    split_statuses?: Array<{
+        split_id: string;
+        recipient_type: RecipientType;
+        amount_usd: number;
+        status: SplitStatus;
+        transaction_signature?: string;
+    }>;
     created_at?: string;
     updated_at?: string;
 }
@@ -317,10 +415,6 @@ type WebhookHandlers = Partial<{
     'installment.due': WebhookEventHandler;
     'installment.paid': WebhookEventHandler;
     'installment.late': WebhookEventHandler;
-    'escrow.funded': WebhookEventHandler;
-    'escrow.released': WebhookEventHandler;
-    'escrow.refunded': WebhookEventHandler;
-    'escrow.disputed': WebhookEventHandler;
     'invoice.sent': WebhookEventHandler;
     'invoice.paid': WebhookEventHandler;
 }>;
@@ -336,4 +430,4 @@ interface WebhookResult {
 }
 declare function processWebhook(a: any, b?: any, c?: any): Promise<WebhookResult>;
 
-export { type ApiKeyMode as A, type Brand as B, type CreatePaymentRequest as C, type PaymentStatus as D, type Environment as E, type SubscriptionStatus as F, type InstallmentPlanStatus as G, type InvoiceStatus as H, type InstallmentPlan as I, type SplitStatus as J, type WebhookEvent as K, type SplitRecipient as L, type MerchantId as M, type ListPaymentsRequest as N, type PaginatedResponse as O, type Payment as P, type InstallmentScheduleItem as Q, type CreateInstallmentPlanResponse as R, type SubscriptionPlan as S, type InvoiceLineItem as T, type VerifyWebhookRequest as V, type WebhookHandlerConfig as W, type ZendFiConfig as Z, type WebhookHandlers as a, type CreateSubscriptionPlanRequest as b, type CreateSubscriptionRequest as c, type Subscription as d, type CreatePaymentLinkRequest as e, type PaymentLink as f, type CreateInstallmentPlanRequest as g, type CreateInvoiceRequest as h, type Invoice as i, type WebhookPayload as j, type WebhookResult as k, type WebhookEventHandler as l, type PaymentId as m, type InvoiceId as n, type SubscriptionId as o, processWebhook as p, type InstallmentPlanId as q, type PaymentLinkCode as r, asPaymentId as s, asMerchantId as t, asInvoiceId as u, asSubscriptionId as v, asInstallmentPlanId as w, asPaymentLinkCode as x, type Currency as y, type PaymentToken as z };
+export { type InvoiceLineItem as $, type ApiKeyMode as A, type Brand as B, type CreatePaymentRequest as C, type PaymentStatus as D, type Environment as E, type SubscriptionStatus as F, type InstallmentPlanStatus as G, type InvoiceStatus as H, type InstallmentPlan as I, type SplitStatus as J, type WebhookEvent as K, type SplitRecipientBase as L, type MerchantId as M, type WalletSplitRecipient as N, type BankAccountSplitRecipient as O, type Payment as P, type SplitRecipient as Q, type RecipientType as R, type SubscriptionPlan as S, type PaymentLinkCustomerObject as T, type ListPaymentsRequest as U, type VerifyWebhookRequest as V, type WebhookHandlerConfig as W, type PaginatedResponse as X, type InstallmentScheduleItem as Y, type ZendFiConfig as Z, type CreateInstallmentPlanResponse as _, type WebhookHandlers as a, type CreateSubscriptionPlanRequest as b, type CreateSubscriptionRequest as c, type Subscription as d, type CreatePaymentLinkRequest as e, type PaymentLink as f, type CreateInstallmentPlanRequest as g, type CreateInvoiceRequest as h, type Invoice as i, type WebhookPayload as j, type WebhookResult as k, type WebhookEventHandler as l, type PaymentId as m, type InvoiceId as n, type SubscriptionId as o, processWebhook as p, type InstallmentPlanId as q, type PaymentLinkCode as r, asPaymentId as s, asMerchantId as t, asInvoiceId as u, asSubscriptionId as v, asInstallmentPlanId as w, asPaymentLinkCode as x, type Currency as y, type PaymentToken as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zendfi/sdk",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Zero-config TypeScript SDK for ZendFi. Global payments powered by stablecoins!",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",