softycomp-node 1.0.5 → 1.1.1

package/README.md

@@ -10,14 +10,36 @@ Accept once-off and recurring payments via card, EFT, and debit order with a sim
 
 ## Features
 
-- **Bill Presentment** — Create payment links for once-off or recurring bills
-- **Debit Orders** — Monthly and yearly recurring collections
+- **Bill Presentment** — Create, update, expire payment links for once-off or recurring bills
+- **Debit Orders** — Monthly and yearly recurring collections via Mobi-Mandate
+- **Client Management** — Create and manage customer profiles
 - **Refunds** — Process full or partial refunds via credit transactions
+- **Payouts** — Credit distribution to bank accounts
+- **Re-authentication** — Handle card expiry with automated bill re-creation
+- **Audit Trail** — List bill presentment audit logs
 - **Webhooks** — Real-time payment notifications with signature validation
 - **TypeScript** — Fully typed for autocomplete and type safety
 - **Zero Dependencies** — Uses native `fetch()` (Node.js 18+)
 - **Sandbox Support** — Test with sandbox environment before going live
 
+## Developer Playground
+
+Try the interactive API explorer at `playground/` — a beautiful web interface to test all SoftyComp features:
+
+```bash
+cd playground
+npm install
+npm start
+```
+
+Then visit http://localhost:4021 to explore:
+- Create bills (once-off, monthly, weekly, yearly, subscription)
+- Manage bills (status, update, expire, audit trail, re-auth)
+- Debit orders (Mobi-Mandate)
+- Client management & payouts
+- Live webhook feed
+- Code examples & API reference
+
 ## Installation
 
 ```bash
@@ -185,6 +207,100 @@ const status = await client.getBillStatus('BILL-REF-123');
 }
 ```
 
+### Bill Management
+
+#### Expire a Bill
+
+Set a bill to expired status (e.g., for cancelling a recurring bill):
+
+```typescript
+await client.setBillToExpiredStatus('BILL-REF-123', 'USER-REF-123');
+```
+
+#### Update Bill Presentment
+
+Update details of an existing bill:
+
+```typescript
+await client.updateBillPresentment({
+  reference: 'BILL-REF-123',
+  amount: 399.00,
+  description: 'Updated description',
+  customerEmail: 'newemail@example.com'
+});
+```
+
+#### List Bill Audit Trail
+
+Get the audit trail for a bill:
+
+```typescript
+const audits = await client.listBillPresentmentAudits('BILL-REF-123', 'USER-REF-123');
+
+// Returns array of:
+{
+  auditId: number;
+  timestamp: string;
+  description: string;
+  user: string;
+  raw: any;
+}
+```
+
+### Client Management
+
+Create a new client profile:
+
+```typescript
+const clientId = await client.createClient({
+  name: 'John',
+  surname: 'Doe',
+  email: 'john@example.com',
+  phone: '0825551234',
+  idNumber: '8001015009087'  // Optional SA ID number
+});
+
+console.log(`Created client ID: ${clientId}`);
+```
+
+### Mobi-Mandate (Debit Orders)
+
+Create a Mobi-Mandate request for debit order sign-up. This generates a URL where customers can enter their bank details and sign a debit order mandate.
+
+```typescript
+const mandate = await client.createMobiMandate({
+  customerEmail: 'john@example.com',
+  customerPhone: '0825551234',
+  surname: 'Doe',
+  initials: 'J',
+  amount: 99.00,              // Monthly/yearly charge amount
+  frequency: 'monthly',       // or 'yearly'
+  debitDay: 1,                // Day of month to charge (1-28)
+  description: 'Monthly subscription',
+  successUrl: 'https://myapp.com/success',
+  callbackUrl: 'https://myapp.com/webhook'
+});
+
+// Redirect customer to sign the mandate
+console.log(mandate.url);  // e.g., https://popay.co.za/xxx
+
+// Returns:
+{
+  url: string;      // Mandate sign-up URL
+  success: boolean;
+  message: string;
+}
+```
+
+#### Cancel a Debit Order Collection
+
+```typescript
+await client.updateCollectionStatus({
+  collectionId: 12345,
+  statusTypeId: 6  // 6 = Cancelled
+});
+```
+
 ### Refund Payment
 
 Process a full or partial refund (credit transaction).
@@ -209,6 +325,50 @@ const refund = await client.refund({
 }
 ```
 
+### Credit Distribution (Payouts)
+
+Send money to a bank account:
+
+```typescript
+const result = await client.createCreditDistribution({
+  amount: 500.00,
+  accountNumber: '1234567890',
+  branchCode: '123456',
+  accountName: 'John Doe',
+  reference: 'PAYOUT-001'
+});
+
+// Returns:
+{
+  distributionId: string;
+  success: boolean;
+  messages: string[];
+}
+```
+
+### Re-authentication (Card Expiry)
+
+Handle card expiry by expiring the old bill and creating a new one with a different reference:
+
+```typescript
+const newBill = await client.createReauthBill({
+  oldReference: 'OLD-BILL-123',
+  newReference: 'NEW-BILL-456',  // MUST be different
+  amount: 99.00,
+  customerName: 'John Doe',
+  customerEmail: 'john@example.com',
+  customerPhone: '0825551234',
+  description: 'Monthly subscription',
+  billingCycle: 'MONTHLY',  // or 'YEARLY'
+  successUrl: 'https://myapp.com/success',
+  cancelUrl: 'https://myapp.com/cancel',
+  notifyUrl: 'https://myapp.com/webhook'
+});
+
+// Customer re-enters card details at newBill.paymentUrl
+console.log(newBill.paymentUrl);
+```
+
 ### Webhook Handling
 
 SoftyComp sends real-time payment notifications to your `notifyUrl`.
@@ -366,7 +526,16 @@ import {
   PaymentStatus,
   WebhookEvent,
   CreateBillParams,
-  RefundParams
+  RefundParams,
+  CreateClientParams,
+  CreateMobiMandateParams,
+  MobiMandateResult,
+  UpdateBillParams,
+  BillAudit,
+  CreditDistributionParams,
+  CreditDistributionResult,
+  CreateReauthBillParams,
+  UpdateCollectionStatusParams
 } from 'softycomp-node';
 ```
 

package/dist/index.d.ts

@@ -109,6 +109,146 @@ export interface BillStatusResult {
     /** Raw response data */
     data: any;
 }
+export interface UpdateBillParams {
+    /** Bill reference to update */
+    reference: string;
+    /** New amount in Rands */
+    amount?: number;
+    /** New description */
+    description?: string;
+    /** Update customer details */
+    customerName?: string;
+    customerEmail?: string;
+    customerPhone?: string;
+}
+export interface BillAudit {
+    /** Audit entry ID */
+    auditId: number;
+    /** Timestamp of change */
+    timestamp: string;
+    /** Description of change */
+    description: string;
+    /** User who made the change */
+    user: string;
+    /** Raw audit data */
+    raw: any;
+}
+export interface CreateClientParams {
+    /** Client full name */
+    name: string;
+    /** Client surname */
+    surname: string;
+    /** Client email address */
+    email: string;
+    /** Client phone number */
+    phone: string;
+    /** Client ID number (optional) */
+    idNumber?: string;
+}
+export interface CreateMobiMandateParams {
+    /** Customer email */
+    customerEmail: string;
+    /** Customer phone number */
+    customerPhone: string;
+    /** Contract code / reference */
+    contractCode?: string;
+    /** Customer surname */
+    surname: string;
+    /** Customer initials */
+    initials?: string;
+    /** Customer ID number */
+    idNumber?: string;
+    /** Product ID */
+    productId?: string;
+    /** Recurring amount in Rands */
+    amount: number;
+    /** Initial amount (defaults to amount) */
+    initialAmount?: number;
+    /** Account name */
+    accountName?: string;
+    /** Account number */
+    accountNumber?: string;
+    /** Branch code */
+    branchCode?: string;
+    /** Account type (1=Savings, 2=Cheque, 3=Credit Card) */
+    accountType?: number;
+    /** Expiry date (YYYY-MM-DD) */
+    expiryDate?: string;
+    /** Commencement date (YYYY-MM-DD) */
+    commencementDate?: string;
+    /** Collection frequency: 'monthly' | 'yearly' */
+    frequency: 'monthly' | 'yearly';
+    /** Collection method type ID (4=NAEDO) */
+    collectionMethodTypeId?: number;
+    /** Debit day (1-28) */
+    debitDay?: number;
+    /** Description */
+    description?: string;
+    /** Maximum collection amount (defaults to amount * 1.5) */
+    maxCollectionAmount?: number;
+    /** Success redirect URL */
+    successUrl?: string;
+    /** Webhook callback URL */
+    callbackUrl?: string;
+}
+export interface MobiMandateResult {
+    /** Mandate URL for customer to sign */
+    url: string;
+    /** Success status */
+    success: boolean;
+    /** Message from SoftyComp */
+    message: string;
+}
+export interface UpdateCollectionStatusParams {
+    /** Collection ID to update */
+    collectionId: number;
+    /** New status type ID (6=Cancelled) */
+    statusTypeId: number;
+}
+export interface CreditDistributionParams {
+    /** Amount in Rands */
+    amount: number;
+    /** Recipient account number */
+    accountNumber: string;
+    /** Recipient branch code */
+    branchCode: string;
+    /** Recipient account name */
+    accountName: string;
+    /** Payment reference */
+    reference: string;
+}
+export interface CreditDistributionResult {
+    /** Distribution ID */
+    distributionId: string;
+    /** Success status */
+    success: boolean;
+    /** Messages from SoftyComp */
+    messages: string[];
+}
+export interface CreateReauthBillParams {
+    /** Old bill reference to expire */
+    oldReference: string;
+    /** New bill reference (must be different) */
+    newReference: string;
+    /** Amount in Rands */
+    amount: number;
+    /** Customer name */
+    customerName: string;
+    /** Customer email */
+    customerEmail: string;
+    /** Customer phone */
+    customerPhone: string;
+    /** Bill description */
+    description: string;
+    /** Billing cycle */
+    billingCycle: 'MONTHLY' | 'YEARLY';
+    /** Success URL */
+    successUrl: string;
+    /** Cancel URL */
+    cancelUrl: string;
+    /** Webhook URL */
+    notifyUrl: string;
+}
 export declare class SoftyComp {
     private apiKey;
     private secretKey;
@@ -165,6 +305,37 @@ export declare class SoftyComp {
      * ```
      */
     getBillStatus(reference: string): Promise<BillStatusResult>;
+    /**
+     * Set a bill to expired status
+     *
+     * @example
+     * ```typescript
+     * await client.setBillToExpiredStatus('BILL-REF-123', 'USER-REF-123');
+     * ```
+     */
+    setBillToExpiredStatus(reference: string, userReference: string): Promise<void>;
+    /**
+     * Update bill presentment details
+     *
+     * @example
+     * ```typescript
+     * await client.updateBillPresentment({
+     *   reference: 'BILL-REF-123',
+     *   amount: 399.00,
+     *   description: 'Updated description'
+     * });
+     * ```
+     */
+    updateBillPresentment(params: UpdateBillParams): Promise<void>;
+    /**
+     * List bill presentment audit trail
+     *
+     * @example
+     * ```typescript
+     * const audits = await client.listBillPresentmentAudits('BILL-REF-123', 'USER-REF-123');
+     * ```
+     */
+    listBillPresentmentAudits(reference: string, userReference: string): Promise<BillAudit[]>;
     /**
      * Process a refund (credit transaction)
      *
@@ -219,6 +390,91 @@ export declare class SoftyComp {
      * ```
      */
     parseWebhook(body: any): WebhookEvent;
+    /**
+     * Create a new client
+     *
+     * @example
+     * ```typescript
+     * const clientId = await client.createClient({
+     *   name: 'John',
+     *   surname: 'Doe',
+     *   email: 'john@example.com',
+     *   phone: '0825551234',
+     *   idNumber: '8001015009087'
+     * });
+     * ```
+     */
+    createClient(params: CreateClientParams): Promise<number>;
+    /**
+     * Create a Mobi-Mandate request for debit order sign-up
+     *
+     * @example
+     * ```typescript
+     * const mandate = await client.createMobiMandate({
+     *   customerEmail: 'john@example.com',
+     *   customerPhone: '0825551234',
+     *   surname: 'Doe',
+     *   initials: 'J',
+     *   amount: 99.00,
+     *   frequency: 'monthly',
+     *   debitDay: 1,
+     *   description: 'Monthly subscription',
+     *   successUrl: 'https://myapp.com/success'
+     * });
+     *
+     * // Redirect customer to mandate.url to sign
+     * console.log(mandate.url);
+     * ```
+     */
+    createMobiMandate(params: CreateMobiMandateParams): Promise<MobiMandateResult>;
+    /**
+     * Update collection status (e.g., cancel a debit order)
+     *
+     * @example
+     * ```typescript
+     * await client.updateCollectionStatus({
+     *   collectionId: 12345,
+     *   statusTypeId: 6  // 6 = Cancelled
+     * });
+     * ```
+     */
+    updateCollectionStatus(params: UpdateCollectionStatusParams): Promise<void>;
+    /**
+     * Create a credit distribution (payout to bank account)
+     *
+     * @example
+     * ```typescript
+     * const result = await client.createCreditDistribution({
+     *   amount: 500.00,
+     *   accountNumber: '1234567890',
+     *   branchCode: '123456',
+     *   accountName: 'John Doe',
+     *   reference: 'PAYOUT-001'
+     * });
+     * ```
+     */
+    createCreditDistribution(params: CreditDistributionParams): Promise<CreditDistributionResult>;
+    /**
+     * Handle card expiry / re-auth: expire old bill and create new one
+     *
+     * @example
+     * ```typescript
+     * const newBill = await client.createReauthBill({
+     *   oldReference: 'OLD-BILL-123',
+     *   newReference: 'NEW-BILL-456',
+     *   amount: 99.00,
+     *   customerName: 'John Doe',
+     *   customerEmail: 'john@example.com',
+     *   customerPhone: '0825551234',
+     *   description: 'Monthly subscription',
+     *   billingCycle: 'MONTHLY',
+     *   successUrl: 'https://myapp.com/success',
+     *   cancelUrl: 'https://myapp.com/cancel',
+     *   notifyUrl: 'https://myapp.com/webhook'
+     * });
+     * ```
+     */
+    createReauthBill(params: CreateReauthBillParams): Promise<CreateBillResult>;
     /**
      * Map SoftyComp status type ID to payment status
      * @internal

package/dist/index.js

@@ -214,6 +214,76 @@ class SoftyComp {
             data: result,
         };
     }
+    // ==================== Bill Management ====================
+    /**
+     * Set a bill to expired status
+     *
+     * @example
+     * ```typescript
+     * await client.setBillToExpiredStatus('BILL-REF-123', 'USER-REF-123');
+     * ```
+     */
+    async setBillToExpiredStatus(reference, userReference) {
+        await this.apiRequest('POST', `/api/paygatecontroller/setBillToExpiredStatus/${encodeURIComponent(reference)}/${encodeURIComponent(userReference)}`, '');
+    }
+    /**
+     * Update bill presentment details
+     *
+     * @example
+     * ```typescript
+     * await client.updateBillPresentment({
+     *   reference: 'BILL-REF-123',
+     *   amount: 399.00,
+     *   description: 'Updated description'
+     * });
+     * ```
+     */
+    async updateBillPresentment(params) {
+        // First, get the current bill to retrieve full structure
+        const currentBill = await this.apiRequest('GET', `/api/paygatecontroller/listBillPresentmentDetails/${params.reference}/${params.reference}`);
+        const updateData = {
+            Reference: params.reference,
+            UserReference: currentBill.userReference || params.reference,
+            Items: currentBill.items || [],
+        };
+        if (params.customerName !== undefined) {
+            updateData.Name = params.customerName;
+        }
+        if (params.customerEmail !== undefined) {
+            updateData.Emailaddress = params.customerEmail;
+        }
+        if (params.customerPhone !== undefined) {
+            updateData.Cellno = params.customerPhone;
+        }
+        // Update item fields if amount or description changed
+        if (updateData.Items.length > 0) {
+            if (params.amount !== undefined) {
+                updateData.Items[0].Amount = parseFloat(params.amount.toFixed(2));
+            }
+            if (params.description !== undefined) {
+                updateData.Items[0].Description = params.description;
+            }
+        }
+        await this.apiRequest('POST', '/api/paygatecontroller/updateBillPresentment', updateData);
+    }
+    /**
+     * List bill presentment audit trail
+     *
+     * @example
+     * ```typescript
+     * const audits = await client.listBillPresentmentAudits('BILL-REF-123', 'USER-REF-123');
+     * ```
+     */
+    async listBillPresentmentAudits(reference, userReference) {
+        const result = await this.apiRequest('GET', `/api/paygatecontroller/listBillPresentmentAudits/${encodeURIComponent(reference)}/${encodeURIComponent(userReference)}`);
+        return (result || []).map((audit) => ({
+            auditId: audit.auditId || 0,
+            timestamp: audit.timestamp || audit.date || '',
+            description: audit.description || audit.action || '',
+            user: audit.user || audit.userName || '',
+            raw: audit,
+        }));
+    }
     // ==================== Refunds ====================
     /**
      * Process a refund (credit transaction)
@@ -330,6 +400,228 @@ class SoftyComp {
             raw: event,
         };
     }
+    // ==================== Client Management ====================
+    /**
+     * Create a new client
+     *
+     * @example
+     * ```typescript
+     * const clientId = await client.createClient({
+     *   name: 'John',
+     *   surname: 'Doe',
+     *   email: 'john@example.com',
+     *   phone: '0825551234',
+     *   idNumber: '8001015009087'
+     * });
+     * ```
+     */
+    async createClient(params) {
+        const result = await this.apiRequest('POST', '/api/clients/createclient', {
+            clientId: 0,
+            clientTypeId: 1, // Individual
+            contractCode: `C${Date.now().toString().slice(-13)}`, // Max 14 chars
+            initials: params.name.charAt(0),
+            surname: params.surname,
+            idnumber: params.idNumber || '',
+            clientStatusTypeId: 1, // Active
+            cellphoneNumber: params.phone,
+            emailAddress: params.email,
+            sendSmsDonotifications: true,
+            sendSmsUnpaidsNotifications: true,
+            isSouthAfricanCitizen: true,
+            fullNames: params.name,
+        });
+        if (!result.success) {
+            throw new Error(`SoftyComp create client failed: ${result.messages.join(', ')}`);
+        }
+        return result.value;
+    }
+    // ==================== Mobi-Mandate (Debit Orders) ====================
+    /**
+     * Create a Mobi-Mandate request for debit order sign-up
+     *
+     * @example
+     * ```typescript
+     * const mandate = await client.createMobiMandate({
+     *   customerEmail: 'john@example.com',
+     *   customerPhone: '0825551234',
+     *   surname: 'Doe',
+     *   initials: 'J',
+     *   amount: 99.00,
+     *   frequency: 'monthly',
+     *   debitDay: 1,
+     *   description: 'Monthly subscription',
+     *   successUrl: 'https://myapp.com/success'
+     * });
+     *
+     * // Redirect customer to mandate.url to sign
+     * console.log(mandate.url);
+     * ```
+     */
+    async createMobiMandate(params) {
+        const frequencyMap = {
+            monthly: 2,
+            yearly: 4,
+        };
+        const today = new Date();
+        const tomorrow = new Date(today);
+        tomorrow.setDate(tomorrow.getDate() + 1);
+        const defaultCommencementDate = tomorrow.toISOString().split('T')[0];
+        const mandateData = {
+            EmailAddress: params.customerEmail,
+            CellphoneNumber: params.customerPhone,
+            ContractCode: params.contractCode || `M${Date.now().toString().slice(-5)}`, // Max 6 chars
+            Surname: params.surname,
+            Initials: params.initials || params.surname.charAt(0),
+            IDNumber: params.idNumber || '',
+            ProductID: params.productId ? parseInt(params.productId, 10) : null,
+            Amount: parseFloat(params.amount.toFixed(2)),
+            InitialAmount: params.initialAmount ? parseFloat(params.initialAmount.toFixed(2)) : parseFloat(params.amount.toFixed(2)),
+            AccountName: params.accountName || '',
+            AccountNumber: params.accountNumber || '',
+            BranchCode: params.branchCode || '',
+            AccountType: params.accountType || 1,
+            ExpiryDate: params.expiryDate || null,
+            CommencementDate: params.commencementDate || defaultCommencementDate,
+            CollectionFrequencyTypeID: frequencyMap[params.frequency] || 2,
+            CollectionMethodTypeID: params.collectionMethodTypeId || 4, // NAEDO
+            DebitDay: params.debitDay || 1,
+            Description: params.description || 'Debit Order',
+            DebitMonth: null,
+            TransactionDate1: null,
+            TransactionDate2: null,
+            TransactionDate3: null,
+            TransactionDate4: null,
+            NaedoTrackingCodeID: 12,
+            EntryClassCodeTypeID: 1,
+            AdjustmentCategoryTypeID: 2,
+            DebiCheckMaximumCollectionAmount: params.maxCollectionAmount || (params.amount * 1.5),
+            DateAdjustmentAllowed: false,
+            AdjustmentAmount: 0,
+            AdjustmentRate: 0,
+            DebitValueTypeID: 1,
+            RedirectURL: params.successUrl || '',
+            CallbackURL: params.callbackUrl || '',
+            SendCorrespondence: true,
+            ExternalRequest: true,
+            HideHomeTel: true,
+            HideWorkTel: true,
+            HideProductDetail: false,
+            HideExpiryDate: true,
+            HideAdditionalInfo: true,
+            HideDescription: false,
+        };
+        const result = await this.apiRequest('POST', '/api/mobimandate/generateMobiMandateRequest', mandateData);
+        if (!result.success) {
+            throw new Error(`SoftyComp Mobi-Mandate failed: ${result.message}`);
+        }
+        return {
+            url: result.tinyURL,
+            success: result.success,
+            message: result.message,
+        };
+    }
+    /**
+     * Update collection status (e.g., cancel a debit order)
+     *
+     * @example
+     * ```typescript
+     * await client.updateCollectionStatus({
+     *   collectionId: 12345,
+     *   statusTypeId: 6  // 6 = Cancelled
+     * });
+     * ```
+     */
+    async updateCollectionStatus(params) {
+        await this.apiRequest('POST', '/api/collections/updateCollectionStatus', {
+            collectionID: params.collectionId,
+            collectionStatusTypeID: params.statusTypeId,
+        });
+    }
+    // ==================== Credit Distribution (Payouts) ====================
+    /**
+     * Create a credit distribution (payout to bank account)
+     *
+     * @example
+     * ```typescript
+     * const result = await client.createCreditDistribution({
+     *   amount: 500.00,
+     *   accountNumber: '1234567890',
+     *   branchCode: '123456',
+     *   accountName: 'John Doe',
+     *   reference: 'PAYOUT-001'
+     * });
+     * ```
+     */
+    async createCreditDistribution(params) {
+        const result = await this.apiRequest('POST', '/api/creditdistribution/createCreditDistribution', {
+            creditFileTransactions: [
+                {
+                    amount: parseFloat(params.amount.toFixed(2)),
+                    accountNumber: params.accountNumber,
+                    branchCode: params.branchCode,
+                    accountName: params.accountName,
+                    reference: params.reference,
+                    userReference: params.reference, // Required by SoftyComp API
+                },
+            ],
+        });
+        return {
+            distributionId: result?.value?.toString() || `dist_${Date.now()}`,
+            success: result?.success || false,
+            messages: result?.messages || [],
+        };
+    }
+    // ==================== Re-authentication ====================
+    /**
+     * Handle card expiry / re-auth: expire old bill and create new one
+     *
+     * @example
+     * ```typescript
+     * const newBill = await client.createReauthBill({
+     *   oldReference: 'OLD-BILL-123',
+     *   newReference: 'NEW-BILL-456',
+     *   amount: 99.00,
+     *   customerName: 'John Doe',
+     *   customerEmail: 'john@example.com',
+     *   customerPhone: '0825551234',
+     *   description: 'Monthly subscription',
+     *   billingCycle: 'MONTHLY',
+     *   successUrl: 'https://myapp.com/success',
+     *   cancelUrl: 'https://myapp.com/cancel',
+     *   notifyUrl: 'https://myapp.com/webhook'
+     * });
+     * ```
+     */
+    async createReauthBill(params) {
+        // Step 1: Expire the old bill
+        try {
+            await this.setBillToExpiredStatus(params.oldReference, params.oldReference);
+        }
+        catch (err) {
+            console.warn(`[SoftyComp] Could not expire old bill ${params.oldReference}:`, err);
+            // Continue — the old bill may already be expired
+        }
+        // Step 2: Create a new bill with a different reference
+        const isMonthly = params.billingCycle === 'MONTHLY';
+        const tomorrow = new Date();
+        tomorrow.setDate(tomorrow.getDate() + 1);
+        return this.createBill({
+            amount: params.amount,
+            customerName: params.customerName,
+            customerEmail: params.customerEmail,
+            customerPhone: params.customerPhone,
+            reference: params.newReference,
+            description: params.description,
+            frequency: isMonthly ? 'monthly' : 'yearly',
+            commencementDate: tomorrow.toISOString().split('T')[0],
+            recurringDay: tomorrow.getDate(),
+            recurringMonth: isMonthly ? undefined : (tomorrow.getMonth() + 1),
+            returnUrl: params.successUrl,
+            cancelUrl: params.cancelUrl,
+            notifyUrl: params.notifyUrl,
+        });
+    }
     // ==================== Helpers ====================
     /**
      * Map SoftyComp status type ID to payment status
@@ -342,6 +634,8 @@ class SoftyComp {
             case 3: return 'failed'; // Failed
             case 4: return 'cancelled'; // Expired
             case 5: return 'cancelled'; // Cancelled
+            case 6: return 'failed'; // Arrears (card expired / payment failed)
+            case 7: return 'failed'; // ReAuth required
             default: return 'pending';
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "softycomp-node",
-  "version": "1.0.5",
+  "version": "1.1.1",
   "description": "Node.js SDK for SoftyComp — South African bill presentment and debit order platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",