pi-spi-sdk 0.1.0

package/dist/services/demandes-paiement-en-masse.js

@@ -0,0 +1,139 @@
+/**
+ * Bulk Payment Requests (Demandes de Paiement en Masse) service wrapper
+ *
+ * Provides methods for creating and managing bulk payment requests.
+ *
+ * **Bulk Payment Request Features:**
+ * - Send multiple payment requests in a single operation
+ * - Useful for invoicing multiple customers
+ * - Each request can have different amounts and recipients
+ * - All requests share the same `instructionId`
+ * - Can confirm entire bulk at once
+ *
+ * **Use Cases:**
+ * - Mass invoicing
+ * - Subscription billing
+ * - Bulk bill collection
+ * - Multiple invoice requests
+ *
+ * @example
+ * ```typescript
+ * // Create bulk payment requests
+ * const bulkRequests = await sdk.demandesPaiementEnMasse.create({
+ *   comptePaye: 'CIC2344256727788288822',
+ *   transactions: [
+ *     { txId: 'INV-001', payeurAlias: 'alias1', montant: 50000, motif: 'Facture' },
+ *     { txId: 'INV-002', payeurAlias: 'alias2', montant: 75000, motif: 'Facture' }
+ *   ]
+ * });
+ * ```
+ */
+import { BaseService } from './base';
+export class DemandesPaiementEnMasseService extends BaseService {
+    /**
+     * Create bulk payment requests
+     *
+     * **Bulk Request Process:**
+     * 1. Create bulk with multiple payment requests
+     * 2. All requests are created with status `INITIE`
+     * 3. Confirm bulk to send all requests to recipients
+     * 4. Each recipient receives their individual payment request
+     *
+     * **Confirmation:**
+     * - Use `confirm()` method to send all requests
+     * - Individual requests can be accepted/rejected by recipients
+     * - Each request follows standard payment request flow
+     *
+     * @param request - Bulk payment request creation data
+     * @param request.comptePaye - Business account number (payee)
+     * @param request.transactions - Array of payment request transactions
+     * @param request.transactions[].txId - Unique transaction ID (must be unique within bulk)
+     * @param request.transactions[].payeurAlias - Customer alias (payer)
+     * @param request.transactions[].montant - Amount in centimes (e.g., 50000 = 500 XOF)
+     * @param request.transactions[].motif - Payment reason/description
+     * @param request.transactions[].categorie - Request category (optional, defaults to '401')
+     * @param request.transactions[].dateLimitePaiement - Payment due date (optional)
+     * @param request.transactions[].refDocType - Reference document type (optional)
+     * @param request.transactions[].refDocNumero - Reference document number (optional)
+     * @returns Bulk payment request response
+     * @throws {PiSpiValidationError} If bulk fails validation (e.g., duplicate txId, invalid alias)
+     *
+     * @example
+     * ```typescript
+     * // Create bulk invoice requests
+     * await sdk.demandesPaiementEnMasse.create({
+     *   comptePaye: 'CIC2344256727788288822',
+     *   transactions: [
+     *     {
+     *       txId: 'INV-2023-001',
+     *       payeurAlias: '9b1b3499-3e50-435b-b757-ac7a83d8aa96',
+     *       montant: 150000, // 1,500 XOF
+     *       motif: 'Facture électricité mars 2023',
+     *       categorie: '401',
+     *       dateLimitePaiement: '2023-12-31T23:59:59.999Z',
+     *       refDocType: 'CINV',
+     *       refDocNumero: 'FACT-ELEC-202303-001'
+     *     },
+     *     {
+     *       txId: 'INV-2023-002',
+     *       payeurAlias: '8b1b2499-3e50-435b-b757-ac7a83d8aa7f',
+     *       montant: 200000, // 2,000 XOF
+     *       motif: 'Facture téléphone mars 2023',
+     *       categorie: '401',
+     *       dateLimitePaiement: '2023-12-31T23:59:59.999Z',
+     *       refDocType: 'CINV',
+     *       refDocNumero: 'FACT-TEL-202303-002'
+     *     }
+     *   ]
+     * });
+     * ```
+     */
+    async create(request) {
+        return this.execute(async () => {
+            throw new Error('Service not yet generated. Run "pnpm run generate" first.');
+        });
+    }
+    /**
+     * Get bulk payment request details and status
+     *
+     * **Response Includes:**
+     * - Overall bulk status
+     * - Individual request statuses
+     * - Accepted/rejected counts
+     * - Payment statuses
+     *
+     * @param instructionId - Bulk instruction ID
+     * @returns Bulk payment request details with individual request statuses
+     * @throws {PiSpiNotFoundError} If bulk payment request not found
+     */
+    async get(instructionId) {
+        return this.execute(async () => {
+            throw new Error('Service not yet generated. Run "pnpm run generate" first.');
+        });
+    }
+    /**
+     * Confirm and send bulk payment requests
+     *
+     * **Confirmation Process:**
+     * - All requests in bulk are sent to recipients
+     * - Each recipient receives their individual payment request
+     * - Recipients can accept/reject independently
+     * - Bulk status updates as recipients respond
+     *
+     * @param instructionId - Bulk instruction ID
+     * @returns Confirmation response
+     * @throws {PiSpiNotFoundError} If bulk payment request not found
+     * @throws {PiSpiError} If bulk already confirmed
+     *
+     * @example
+     * ```typescript
+     * // Confirm and send all requests
+     * await sdk.demandesPaiementEnMasse.confirm('BULK-INV-2023-03');
+     * ```
+     */
+    async confirm(instructionId) {
+        return this.execute(async () => {
+            throw new Error('Service not yet generated. Run "pnpm run generate" first.');
+        });
+    }
+}

package/dist/services/demandes-paiement.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Payment Requests (Demandes de Paiement) service wrapper
+ *
+ * Provides methods for creating and managing payment requests (bills, invoices, etc.).
+ *
+ * **Payment Request Types:**
+ * - **E-commerce** (`categorie: 521`): Online payment requests with 3-minute expiry
+ * - **Point of Sale** (`categorie: 500`): Physical store payment requests
+ * - **Invoice/Bill** (`categorie: 401`): Invoice payment requests with due dates
+ * - **PICO**: Purchase with cash withdrawal (combined purchase + cashback)
+ * - **PICASH**: Cash withdrawal only
+ *
+ * **Payment Request Flow:**
+ * 1. Business creates payment request
+ * 2. Customer receives request (via alias)
+ * 3. Customer can: Accept & Pay Now, Accept & Pay Later, Reject, or Ignore
+ * 4. If accepted, payment is processed automatically
+ *
+ * @example
+ * ```typescript
+ * // Create invoice payment request
+ * const request = await sdk.demandesPaiement.create({
+ *   comptePaye: 'CIC2344256727788288822',
+ *   payeurAlias: '9b1b3499-3e50-435b-b757-ac7a83d8aa96',
+ *   montant: 150000,
+ *   categorie: '401',
+ *   dateLimitePaiement: '2023-12-31T23:59:59.999Z',
+ *   motif: 'Facture électricité mars 2023'
+ * });
+ * ```
+ */
+import { BaseService } from './base';
+import type { QueryParams } from '../query-builder';
+export declare class DemandesPaiementService extends BaseService {
+    /**
+     * Create a payment request
+     *
+     * **Request Types:**
+     * - **E-commerce** (`categorie: 521`): Max 3 minutes validity
+     * - **POS** (`categorie: 500`): Max 24 hours validity
+     * - **Invoice** (`categorie: 401`): Custom due date (up to 90 days)
+     *
+     * **Confirmation Options:**
+     * - `confirmation: false`: Request sent immediately (default for POS)
+     * - `confirmation: true`: Returns payer info for verification before sending
+     *
+     * **Customer Actions:**
+     * - Accept & Pay Now: Payment processed immediately
+     * - Accept & Pay Later: Payment scheduled (if dateLimiteReponse > 24h)
+     * - Reject: Request rejected with reason
+     * - Ignore: Request expires after dateLimiteReponse
+     *
+     * @param request - Payment request creation data
+     * @param request.comptePaye - Business account number (payee)
+     * @param request.payeurAlias - Customer alias (payer)
+     * @param request.montant - Amount in centimes (e.g., 150000 = 1,500 XOF)
+     * @param request.categorie - Request category: '500' (POS), '521' (E-commerce), '401' (Invoice)
+     * @param request.motif - Payment reason/description
+     * @param request.txId - Unique transaction ID (optional)
+     * @param request.dateLimitePaiement - Payment due date (required for e-commerce and invoices)
+     * @param request.dateLimiteReponse - Response deadline (default: 90 days from creation)
+     * @param request.confirmation - Whether to require confirmation (default: false for POS, true for invoices)
+     * @param request.refDocType - Reference document type (e.g., 'CINV' for invoice)
+     * @param request.refDocNumero - Reference document number (e.g., invoice number)
+     * @returns Payment request response
+     * @throws {PiSpiValidationError} If request fails validation
+     *
+     * @example
+     * ```typescript
+     * // E-commerce payment request (3-minute expiry)
+     * await sdk.demandesPaiement.create({
+     *   comptePaye: 'CIC2344256727788288822',
+     *   payeurAlias: '9b1b3499-3e50-435b-b757-ac7a83d8aa96',
+     *   montant: 25000, // 250 XOF
+     *   categorie: '521',
+     *   dateLimitePaiement: '2023-02-21T15:37:00.000Z', // 3 minutes from now
+     *   motif: 'Paiement du livre Manuel des écritures comptables'
+     * });
+     *
+     * // Invoice payment request
+     * await sdk.demandesPaiement.create({
+     *   comptePaye: 'CIC2344256727788288822',
+     *   payeurAlias: '9b1b3499-3e50-435b-b757-ac7a83d8aa96',
+     *   montant: 150000, // 1,500 XOF
+     *   categorie: '401',
+     *   dateLimitePaiement: '2023-12-31T23:59:59.999Z',
+     *   motif: 'Facture électricité mars 2023',
+     *   refDocType: 'CINV',
+     *   refDocNumero: 'FACT-ELEC-202303',
+     *   confirmation: true
+     * });
+     * ```
+     */
+    create(request: {
+        comptePaye: string;
+        payeurAlias: string;
+        montant: number;
+        categorie: string;
+        motif: string;
+        txId?: string;
+        dateLimitePaiement?: string;
+        dateLimiteReponse?: string;
+        confirmation?: boolean;
+        refDocType?: string;
+        refDocNumero?: string;
+    }): Promise<never>;
+    /**
+     * List payment requests with filtering and pagination
+     *
+     * @param params - Query parameters for filtering and pagination
+     * @returns Paginated list of payment requests
+     */
+    list(params?: QueryParams): Promise<never>;
+    /**
+     * Get payment request details
+     *
+     * @param id - Payment request transaction ID
+     * @returns Payment request details
+     * @throws {PiSpiNotFoundError} If request not found
+     */
+    get(id: string): Promise<never>;
+    /**
+     * Accept a payment request
+     *
+     * **Note:** This is typically called by the customer's payment app, not the business.
+     * The business receives notification when customer accepts.
+     *
+     * @param id - Payment request transaction ID
+     * @param immediate - Whether to pay immediately (true) or schedule payment (false)
+     * @returns Payment confirmation response
+     */
+    accept(id: string, immediate?: boolean): Promise<never>;
+    /**
+     * Reject a payment request
+     *
+     * **Note:** This is typically called by the customer's payment app, not the business.
+     * The business receives notification when customer rejects.
+     *
+     * @param id - Payment request transaction ID
+     * @param reason - Rejection reason code (optional)
+     * @returns Rejection confirmation response
+     */
+    reject(id: string, reason?: string): Promise<never>;
+}

package/dist/services/demandes-paiement.js

@@ -0,0 +1,151 @@
+/**
+ * Payment Requests (Demandes de Paiement) service wrapper
+ *
+ * Provides methods for creating and managing payment requests (bills, invoices, etc.).
+ *
+ * **Payment Request Types:**
+ * - **E-commerce** (`categorie: 521`): Online payment requests with 3-minute expiry
+ * - **Point of Sale** (`categorie: 500`): Physical store payment requests
+ * - **Invoice/Bill** (`categorie: 401`): Invoice payment requests with due dates
+ * - **PICO**: Purchase with cash withdrawal (combined purchase + cashback)
+ * - **PICASH**: Cash withdrawal only
+ *
+ * **Payment Request Flow:**
+ * 1. Business creates payment request
+ * 2. Customer receives request (via alias)
+ * 3. Customer can: Accept & Pay Now, Accept & Pay Later, Reject, or Ignore
+ * 4. If accepted, payment is processed automatically
+ *
+ * @example
+ * ```typescript
+ * // Create invoice payment request
+ * const request = await sdk.demandesPaiement.create({
+ *   comptePaye: 'CIC2344256727788288822',
+ *   payeurAlias: '9b1b3499-3e50-435b-b757-ac7a83d8aa96',
+ *   montant: 150000,
+ *   categorie: '401',
+ *   dateLimitePaiement: '2023-12-31T23:59:59.999Z',
+ *   motif: 'Facture électricité mars 2023'
+ * });
+ * ```
+ */
+import { BaseService } from './base';
+export class DemandesPaiementService extends BaseService {
+    /**
+     * Create a payment request
+     *
+     * **Request Types:**
+     * - **E-commerce** (`categorie: 521`): Max 3 minutes validity
+     * - **POS** (`categorie: 500`): Max 24 hours validity
+     * - **Invoice** (`categorie: 401`): Custom due date (up to 90 days)
+     *
+     * **Confirmation Options:**
+     * - `confirmation: false`: Request sent immediately (default for POS)
+     * - `confirmation: true`: Returns payer info for verification before sending
+     *
+     * **Customer Actions:**
+     * - Accept & Pay Now: Payment processed immediately
+     * - Accept & Pay Later: Payment scheduled (if dateLimiteReponse > 24h)
+     * - Reject: Request rejected with reason
+     * - Ignore: Request expires after dateLimiteReponse
+     *
+     * @param request - Payment request creation data
+     * @param request.comptePaye - Business account number (payee)
+     * @param request.payeurAlias - Customer alias (payer)
+     * @param request.montant - Amount in centimes (e.g., 150000 = 1,500 XOF)
+     * @param request.categorie - Request category: '500' (POS), '521' (E-commerce), '401' (Invoice)
+     * @param request.motif - Payment reason/description
+     * @param request.txId - Unique transaction ID (optional)
+     * @param request.dateLimitePaiement - Payment due date (required for e-commerce and invoices)
+     * @param request.dateLimiteReponse - Response deadline (default: 90 days from creation)
+     * @param request.confirmation - Whether to require confirmation (default: false for POS, true for invoices)
+     * @param request.refDocType - Reference document type (e.g., 'CINV' for invoice)
+     * @param request.refDocNumero - Reference document number (e.g., invoice number)
+     * @returns Payment request response
+     * @throws {PiSpiValidationError} If request fails validation
+     *
+     * @example
+     * ```typescript
+     * // E-commerce payment request (3-minute expiry)
+     * await sdk.demandesPaiement.create({
+     *   comptePaye: 'CIC2344256727788288822',
+     *   payeurAlias: '9b1b3499-3e50-435b-b757-ac7a83d8aa96',
+     *   montant: 25000, // 250 XOF
+     *   categorie: '521',
+     *   dateLimitePaiement: '2023-02-21T15:37:00.000Z', // 3 minutes from now
+     *   motif: 'Paiement du livre Manuel des écritures comptables'
+     * });
+     *
+     * // Invoice payment request
+     * await sdk.demandesPaiement.create({
+     *   comptePaye: 'CIC2344256727788288822',
+     *   payeurAlias: '9b1b3499-3e50-435b-b757-ac7a83d8aa96',
+     *   montant: 150000, // 1,500 XOF
+     *   categorie: '401',
+     *   dateLimitePaiement: '2023-12-31T23:59:59.999Z',
+     *   motif: 'Facture électricité mars 2023',
+     *   refDocType: 'CINV',
+     *   refDocNumero: 'FACT-ELEC-202303',
+     *   confirmation: true
+     * });
+     * ```
+     */
+    async create(request) {
+        return this.execute(async () => {
+            throw new Error('Service not yet generated. Run "pnpm run generate" first.');
+        });
+    }
+    /**
+     * List payment requests with filtering and pagination
+     *
+     * @param params - Query parameters for filtering and pagination
+     * @returns Paginated list of payment requests
+     */
+    async list(params) {
+        return this.execute(async () => {
+            throw new Error('Service not yet generated. Run "pnpm run generate" first.');
+        });
+    }
+    /**
+     * Get payment request details
+     *
+     * @param id - Payment request transaction ID
+     * @returns Payment request details
+     * @throws {PiSpiNotFoundError} If request not found
+     */
+    async get(id) {
+        return this.execute(async () => {
+            throw new Error('Service not yet generated. Run "pnpm run generate" first.');
+        });
+    }
+    /**
+     * Accept a payment request
+     *
+     * **Note:** This is typically called by the customer's payment app, not the business.
+     * The business receives notification when customer accepts.
+     *
+     * @param id - Payment request transaction ID
+     * @param immediate - Whether to pay immediately (true) or schedule payment (false)
+     * @returns Payment confirmation response
+     */
+    async accept(id, immediate = true) {
+        return this.execute(async () => {
+            throw new Error('Service not yet generated. Run "pnpm run generate" first.');
+        });
+    }
+    /**
+     * Reject a payment request
+     *
+     * **Note:** This is typically called by the customer's payment app, not the business.
+     * The business receives notification when customer rejects.
+     *
+     * @param id - Payment request transaction ID
+     * @param reason - Rejection reason code (optional)
+     * @returns Rejection confirmation response
+     */
+    async reject(id, reason) {
+        return this.execute(async () => {
+            throw new Error('Service not yet generated. Run "pnpm run generate" first.');
+        });
+    }
+}

package/dist/services/paiements-en-masse.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Bulk Payments (Paiements en Masse) service wrapper
+ *
+ * Provides methods for creating and managing bulk payment operations.
+ *
+ * **Bulk Payment Features:**
+ * - Process multiple payments in a single request
+ * - Linked by unique `instructionId`
+ * - Can retry failed payments
+ * - Supports up to 10,000 transactions per bulk (recommended: 500-5,000)
+ *
+ * **Transaction Size:**
+ * - Max size per transaction: ~310 bytes
+ * - Max bulk size: ~3.1 MB for 10,000 transactions
+ * - Recommended: 500-5,000 transactions per bulk
+ *
+ * **Use Cases:**
+ * - Salary payments
+ * - Vendor payments
+ * - Bulk disbursements
+ * - Mass refunds
+ *
+ * @example
+ * ```typescript
+ * // Create bulk payment
+ * const bulkPayment = await sdk.paiementsEnMasse.createBulk({
+ *   comptePayeur: 'CIC2344256727788288822',
+ *   instructionId: 'BULK-2023-001',
+ *   transactions: [
+ *     { txId: 'TX001', payeAlias: 'alias1', montant: 100000, motif: 'Salaire' },
+ *     { txId: 'TX002', payeAlias: 'alias2', montant: 150000, motif: 'Salaire' }
+ *   ]
+ * });
+ * ```
+ */
+import { BaseService } from './base';
+export declare class PaiementsEnMasseService extends BaseService {
+    /**
+     * Create bulk payments
+     *
+     * **Bulk Processing:**
+     * - All transactions share the same `instructionId`
+     * - Each transaction needs unique `txId`
+     * - Transactions are processed in parallel
+     * - Failed transactions can be retried
+     *
+     * **Performance Considerations:**
+     * - Larger bulks take longer to process
+     * - May hit HTTP timeout for very large bulks
+     * - Recommended: 500-5,000 transactions per bulk
+     * - For >10,000 transactions, split into multiple bulks
+     *
+     * **Response Status:**
+     * - `INITIE`: Bulk created, awaiting confirmation
+     * - `ENVOYE`: Bulk sent, transactions processing
+     * - `IRREVOCABLE`: All transactions completed
+     * - `PARTIEL`: Some transactions succeeded, some failed
+     * - `REJETE`: Bulk rejected (validation failed)
+     *
+     * @param payment - Bulk payment creation data
+     * @param payment.comptePayeur - Payer account number
+     * @param payment.instructionId - Unique bulk instruction ID
+     * @param payment.transactions - Array of payment transactions
+     * @param payment.transactions[].txId - Unique transaction ID (must be unique within bulk)
+     * @param payment.transactions[].payeAlias - Payee alias (SHID, MCOD, or MBNO)
+     * @param payment.transactions[].montant - Amount in centimes
+     * @param payment.transactions[].motif - Payment reason/description
+     * @param payment.transactions[].refDocType - Reference document type (optional)
+     * @param payment.transactions[].refDocNumero - Reference document number (optional)
+     * @returns Bulk payment response with status and summary
+     * @throws {PiSpiValidationError} If bulk fails validation (e.g., duplicate txId, invalid alias)
+     * @throws {PiSpiError} If account blocked or insufficient funds
+     *
+     * @example
+     * ```typescript
+     * // Create bulk payment for salary disbursement
+     * await sdk.paiementsEnMasse.createBulk({
+     *   comptePayeur: 'CIC2344256727788288822',
+     *   instructionId: 'SALARY-2023-03',
+     *   transactions: [
+     *     {
+     *       txId: 'SAL-001',
+     *       payeAlias: '8b1b2499-3e50-435b-b757-ac7a83d8aa7f',
+     *       montant: 500000, // 5,000 XOF
+     *       motif: 'Salaire mars 2023'
+     *     },
+     *     {
+     *       txId: 'SAL-002',
+     *       payeAlias: '4r5ty499-3e50-435b-b757-ac7a83d67juio',
+     *       montant: 750000, // 7,500 XOF
+     *       motif: 'Salaire mars 2023'
+     *     }
+     *   ]
+     * });
+     * ```
+     */
+    createBulk(payment: {
+        comptePayeur: string;
+        instructionId: string;
+        transactions: Array<{
+            txId: string;
+            payeAlias: string;
+            montant: number;
+            motif: string;
+            refDocType?: string;
+            refDocNumero?: string;
+        }>;
+    }): Promise<never>;
+    /**
+     * Get bulk payment details and status
+     *
+     * **Response Includes:**
+     * - Overall bulk status
+     * - Transaction counts (total, succeeded, failed)
+     * - Individual transaction statuses
+     * - Failed transaction details
+     *
+     * @param instructionId - Bulk instruction ID
+     * @returns Bulk payment details with transaction statuses
+     * @throws {PiSpiNotFoundError} If bulk payment not found
+     *
+     * @example
+     * ```typescript
+     * const bulk = await sdk.paiementsEnMasse.get('SALARY-2023-03');
+     * console.log('Status:', bulk.statut); // 'IRREVOCABLE'
+     * console.log('Succeeded:', bulk.nombreSuccess); // 98
+     * console.log('Failed:', bulk.nombreEchec); // 2
+     * ```
+     */
+    get(instructionId: string): Promise<never>;
+    /**
+     * Retry failed payments in a bulk payment
+     *
+     * **Retry Process:**
+     * - Only failed transactions are retried
+     * - Successful transactions are not affected
+     * - Uses same `instructionId`
+     * - Can retry multiple times if needed
+     *
+     * @param instructionId - Bulk instruction ID
+     * @returns Retry response with updated status
+     * @throws {PiSpiNotFoundError} If bulk payment not found
+     * @throws {PiSpiError} If no failed transactions to retry
+     *
+     * @example
+     * ```typescript
+     * // Retry failed transactions
+     * await sdk.paiementsEnMasse.retry('SALARY-2023-03');
+     * ```
+     */
+    retry(instructionId: string): Promise<never>;
+}