paybridge 0.1.2 → 0.2.1

package/dist/providers/softycomp.d.ts

@@ -4,6 +4,7 @@
  */
 import { PaymentProvider } from './base';
 import { CreatePaymentParams, PaymentResult, CreateSubscriptionParams, SubscriptionResult, RefundParams, RefundResult, WebhookEvent } from '../types';
+import { ProviderCapabilities } from '../routing-types';
 interface SoftyCompConfig {
     apiKey: string;
     secretKey: string;
@@ -29,6 +30,111 @@ export declare class SoftyCompProvider extends PaymentProvider {
     refund(params: RefundParams): Promise<RefundResult>;
     parseWebhook(body: any, _headers?: any): WebhookEvent;
     verifyWebhook(body: string | Buffer, headers?: any): boolean;
+    /**
+     * Set a bill to expired status
+     */
+    setBillToExpiredStatus(reference: string, userReference: string): Promise<void>;
+    /**
+     * Update bill presentment details
+     */
+    updateBillPresentment(params: {
+        reference: string;
+        amount?: number;
+        description?: string;
+        customerName?: string;
+        customerEmail?: string;
+        customerPhone?: string;
+    }): Promise<void>;
+    /**
+     * List bill presentment audit trail
+     */
+    listBillPresentmentAudits(reference: string, userReference: string): Promise<Array<{
+        auditId: number;
+        timestamp: string;
+        description: string;
+        user: string;
+        raw: any;
+    }>>;
+    /**
+     * Create a new client
+     */
+    createClient(params: {
+        name: string;
+        surname: string;
+        email: string;
+        phone: string;
+        idNumber?: string;
+    }): Promise<number>;
+    /**
+     * Create a Mobi-Mandate request for debit order sign-up
+     */
+    createMobiMandate(params: {
+        customerEmail: string;
+        customerPhone: string;
+        surname: string;
+        initials?: string;
+        idNumber?: string;
+        amount: number;
+        frequency: 'monthly' | 'yearly';
+        debitDay?: number;
+        description?: string;
+        contractCode?: string;
+        initialAmount?: number;
+        accountName?: string;
+        accountNumber?: string;
+        branchCode?: string;
+        accountType?: number;
+        expiryDate?: string;
+        commencementDate?: string;
+        collectionMethodTypeId?: number;
+        productId?: string;
+        maxCollectionAmount?: number;
+        successUrl?: string;
+        callbackUrl?: string;
+    }): Promise<{
+        url: string;
+        success: boolean;
+        message: string;
+    }>;
+    /**
+     * Update collection status (e.g., cancel a debit order)
+     */
+    updateCollectionStatus(params: {
+        collectionId: number;
+        statusTypeId: number;
+    }): Promise<void>;
+    /**
+     * Create a credit distribution (payout to bank account)
+     */
+    createCreditDistribution(params: {
+        amount: number;
+        accountNumber: string;
+        branchCode: string;
+        accountName: string;
+        reference: string;
+        userReference?: string;
+    }): Promise<{
+        distributionId: string;
+        success: boolean;
+        messages: string[];
+    }>;
+    /**
+     * Handle card expiry / re-auth: expire old bill and create new one
+     */
+    createReauthBill(params: {
+        oldReference: string;
+        newReference: string;
+        amount: number;
+        customerName: string;
+        customerEmail: string;
+        customerPhone: string;
+        description: string;
+        billingCycle: 'MONTHLY' | 'YEARLY';
+        successUrl: string;
+        cancelUrl: string;
+        notifyUrl: string;
+    }): Promise<SubscriptionResult>;
+    getCapabilities(): ProviderCapabilities;
     private mapBillStatus;
 }
 export {};

package/dist/providers/softycomp.js

@@ -120,16 +120,14 @@ class SoftyCompProvider extends base_1.PaymentProvider {
     }
     async createSubscription(params) {
         this.validateCurrency(params.currency);
-        // Map interval to SoftyComp frequency: 2=monthly, 6=yearly (valid range is 1-6)
-        let frequencyTypeID;
-        if (params.interval === 'monthly') {
-            frequencyTypeID = 2;
-        }
-        else if (params.interval === 'yearly') {
-            frequencyTypeID = 6;
-        }
-        else {
-            throw new Error(`SoftyComp does not support ${params.interval} subscriptions. Use monthly or yearly.`);
+        // Map interval to SoftyComp frequency from official docs:
+        // 1=Once Off, 2=Monthly, 3=Weekly, 4=Yearly, 5=To Collect Amount, 6=Subscription
+        const frequencyMap = {
+            'weekly': 3, 'monthly': 2, 'yearly': 4
+        };
+        const frequencyTypeID = frequencyMap[params.interval];
+        if (!frequencyTypeID) {
+            throw new Error(`SoftyComp does not support ${params.interval} subscriptions. Use weekly, monthly, or yearly.`);
         }
         // Parse and validate start date
         let startDate;
@@ -279,6 +277,232 @@ class SoftyCompProvider extends base_1.PaymentProvider {
             .digest('hex');
         return signature === expectedSignature || signature === `sha256=${expectedSignature}`;
     }
+    // ==================== Bill Management ====================
+    /**
+     * Set a bill to expired status
+     */
+    async setBillToExpiredStatus(reference, userReference) {
+        await this.apiRequest('POST', `/api/paygatecontroller/setBillToExpiredStatus/${encodeURIComponent(reference)}/${encodeURIComponent(userReference)}`, '' // Empty body required
+        );
+    }
+    /**
+     * Update bill presentment details
+     */
+    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
+     */
+    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,
+        }));
+    }
+    // ==================== Client Management ====================
+    /**
+     * Create a new client
+     */
+    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
+     */
+    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)
+     */
+    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)
+     */
+    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.userReference || params.reference,
+                },
+            ],
+        });
+        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
+     */
+    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 subscription with a different reference
+        const isMonthly = params.billingCycle === 'MONTHLY';
+        const tomorrow = new Date();
+        tomorrow.setDate(tomorrow.getDate() + 1);
+        return this.createSubscription({
+            amount: params.amount,
+            currency: 'ZAR',
+            interval: isMonthly ? 'monthly' : 'yearly',
+            reference: params.newReference,
+            description: params.description,
+            customer: {
+                name: params.customerName,
+                email: params.customerEmail,
+                phone: params.customerPhone,
+            },
+            urls: {
+                success: params.successUrl,
+                cancel: params.cancelUrl,
+                webhook: params.notifyUrl,
+            },
+            startDate: tomorrow.toISOString().split('T')[0],
+            billingDay: tomorrow.getDate(),
+        });
+    }
+    // ==================== Capabilities ====================
+    getCapabilities() {
+        return {
+            fees: {
+                fixed: 0,
+                percent: 2.5,
+                currency: 'ZAR',
+            },
+            currencies: this.supportedCurrencies,
+            country: 'ZA',
+            avgLatencyMs: 800,
+        };
+    }
     // ==================== Helpers ====================
     mapBillStatus(statusTypeID) {
         switch (Number(statusTypeID)) {

package/dist/providers/stripe.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Stripe payment provider
+ * Global payment processor supporting 135+ currencies
+ * @see https://stripe.com/docs/api
+ */
+import { PaymentProvider } from './base';
+import { CreatePaymentParams, PaymentResult, CreateSubscriptionParams, SubscriptionResult, RefundParams, RefundResult, WebhookEvent } from '../types';
+import { ProviderCapabilities } from '../routing-types';
+interface StripeConfig {
+    apiKey: string;
+    webhookSecret?: string;
+    sandbox?: boolean;
+}
+export declare class StripeProvider extends PaymentProvider {
+    readonly name = "stripe";
+    readonly supportedCurrencies: string[];
+    private apiKey;
+    private webhookSecret?;
+    private sandbox;
+    private baseUrl;
+    constructor(config: StripeConfig);
+    private buildFormData;
+    private apiRequest;
+    createPayment(params: CreatePaymentParams): Promise<PaymentResult>;
+    createSubscription(params: CreateSubscriptionParams): Promise<SubscriptionResult>;
+    getPayment(id: string): Promise<PaymentResult>;
+    refund(params: RefundParams): Promise<RefundResult>;
+    parseWebhook(body: any, _headers?: any): WebhookEvent;
+    /**
+     * Verify webhook signature using Stripe's scheme.
+     *
+     * CRITICAL: body must be the raw string or Buffer from the webhook request.
+     * Passing a parsed JSON object will cause signature verification to fail.
+     */
+    verifyWebhook(body: string | Buffer, headers?: any): boolean;
+    getCapabilities(): ProviderCapabilities;
+}
+export {};