{"_id":"@elgiosoft/elgiopay-sdk","name":"@elgiosoft/elgiopay-sdk","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@elgiosoft/elgiopay-sdk","version":"1.0.0","description":"Node.js SDK for ElgioPay Service - Mobile Money payments for Cameroon and West Africa","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","dev":"tsc --watch","test":"jest","lint":"eslint src/**/*.ts","prepare":"npm run build","example":"ts-node examples/basic-usage.ts"},"keywords":["payment","mobile-money","mtn","orange-money","cameroon","xaf","west-africa","fintech","api","sdk","nodejs","typescript"],"author":{"name":"Elgiosoft LLC","email":"developers@elgiosoft.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/elgiosoft/elgiopay-sdk-node.git"},"homepage":"https://elgiopay.com","bugs":{"url":"https://github.com/elgiosoft/elgiopay-sdk-node/issues"},"dependencies":{"axios":"^1.6.0"},"devDependencies":{"@types/jest":"^29.5.0","@types/node":"^20.0.0","@typescript-eslint/eslint-plugin":"^6.0.0","@typescript-eslint/parser":"^6.0.0","eslint":"^8.0.0","jest":"^29.5.0","ts-jest":"^29.1.0","ts-node":"^10.9.0","typescript":"^5.0.0"},"engines":{"node":">=16.0.0"},"_id":"@elgiosoft/elgiopay-sdk@1.0.0","gitHead":"852f151420aa60520738feae356a4b24bdebd9f4","_nodeVersion":"20.19.4","_npmVersion":"10.8.2","dist":{"integrity":"sha512-EB05YSEDpZ4ksOvRri+PtofIVGHqcCJTFKlKugv+Ovr3vxMk7L74ZG1ZRN6o1crWl4HpdCn/TuQdlCq64ytRfg==","shasum":"03a9f5b1918067cf1a679400f0043962b0c261c2","tarball":"https://registry.npmjs.org/@elgiosoft/elgiopay-sdk/-/elgiopay-sdk-1.0.0.tgz","fileCount":35,"unpackedSize":110906,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAnzejxZWP1SjaBcpkUya02xZujcrZng2nZRCEviJ4/3AiA8Dzn4fbgjiSqc360TCeGcTwFK9EYgw4Y4A8r6OwFKMg=="}]},"_npmUser":{"name":"ngambmicheal","email":"ngambmicheal@gmail.com"},"directories":{},"maintainers":[{"name":"ngambmicheal","email":"ngambmicheal@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/elgiopay-sdk_1.0.0_1786380594370_0.40652415127932806"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-10T16:49:54.139Z","1.0.0":"2026-08-10T16:49:54.556Z","modified":"2026-08-10T16:49:54.849Z"},"maintainers":[{"name":"ngambmicheal","email":"ngambmicheal@gmail.com"}],"description":"Node.js SDK for ElgioPay Service - Mobile Money payments for Cameroon and West Africa","homepage":"https://elgiopay.com","keywords":["payment","mobile-money","mtn","orange-money","cameroon","xaf","west-africa","fintech","api","sdk","nodejs","typescript"],"repository":{"type":"git","url":"git+https://github.com/elgiosoft/elgiopay-sdk-node.git"},"author":{"name":"Elgiosoft LLC","email":"developers@elgiosoft.com"},"bugs":{"url":"https://github.com/elgiosoft/elgiopay-sdk-node/issues"},"license":"MIT","readme":"# ElgioPay Node.js SDK\n\n[![npm version](https://badge.fury.io/js/%40elgiosoft%2Felgiopay-sdk.svg)](https://badge.fury.io/js/%40elgiosoft%2Felgiopay-sdk)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)\n\nNode.js/TypeScript SDK for integrating with the ElgioPay API. Optimized for mobile money payments in Cameroon and West Africa.\n\n## Features\n\n- 🇨🇲 **Cameroon-First**: Optimized for XAF currency and Cameroon phone formats\n- 📱 **Mobile Money**: MTN Mobile Money and Orange Money support\n- 🔄 **Auto-Retry**: Built-in payment retry mechanism with exponential backoff\n- ✅ **Phone Validation**: Automatic phone number normalization for Cameroon\n- 🛡️ **Error Handling**: Comprehensive error handling with detailed messages\n- 🔗 **TypeScript**: Full TypeScript support with type definitions\n- 💰 **Multi-Currency**: Support for XAF, XOF, and EUR currencies\n- 🧪 **Testing**: Built-in utilities for testing and development\n\n## Installation\n\n```bash\nnpm install @elgiosoft/elgiopay-sdk\n```\n\n## Requirements\n\n- Node.js 16.0.0 or higher\n- TypeScript 5.0+ (for TypeScript projects)\n\n## Quick Start\n\n### Using Environment Variables (Recommended)\n\nCreate a `.env` file in your project root:\n\n```env\nELGIOPAY_API_KEY=pk_test_your_api_key\nELGIOPAY_ENV=sandbox\n```\n\n#### JavaScript (ES6+)\n\n```javascript\nconst { ElgioPayClient } = require('@elgiosoft/elgiopay-sdk');\n\n// Automatically reads from ELGIOPAY_API_KEY and ELGIOPAY_ENV\nconst client = new ElgioPayClient();\n\n// Or with manual configuration:\n// const client = new ElgioPayClient({\n//   apiKey: 'pk_test_your_api_key',\n//   environment: 'sandbox'\n// });\n\n// Create payment\nasync function createPayment() {\n  try {\n    const result = await client.initiatePayment({\n      amount: 5000, // 5000 XAF\n      currency: 'XAF',\n      payment_method: 'mtn_mobile_money',\n      customer_phone: '+237677123456',\n      customer_name: 'Jean Dupont',\n      reference: 'FACTURE-001',\n    });\n\n    console.log('Payment created:', result.transaction_id);\n  } catch (error) {\n    console.error('Payment failed:', error.message);\n  }\n}\n```\n\n#### TypeScript\n\n```typescript\nimport { ElgioPayClient, ElgioPayConfig, PaymentResponse } from '@elgiosoft/elgiopay-sdk';\n\n// Using environment variables\nconst client = new ElgioPayClient();\n\n// Or with manual configuration:\n// const config: ElgioPayConfig = {\n//   apiKey: 'pk_test_your_api_key',\n//   environment: 'sandbox'\n// };\n// const client = new ElgioPayClient(config);\n\nasync function createPayment(): Promise<void> {\n  try {\n    const result: PaymentResponse = await client.initiatePayment({\n      amount: 5000,\n      currency: 'XAF',\n      payment_method: 'mtn_mobile_money',\n      customer_phone: '+237677123456',\n      customer_name: 'Jean Dupont',\n      reference: 'FACTURE-001',\n    });\n\n    console.log('Payment created:', result.transaction_id);\n  } catch (error) {\n    console.error('Payment failed:', error);\n  }\n}\n```\n\n## API Reference\n\n### Client Configuration\n\n```typescript\nconst client = new ElgioPayClient({\n  apiKey: 'your_api_key',        // Required — falls back to ELGIOPAY_API_KEY env var\n  environment: 'sandbox',        // Optional — 'sandbox' | 'prod' (default: 'prod')\n  timeout: 30000,                // Optional — request timeout in ms (default: 30000)\n});\n```\n\n### Payment Methods\n\nEvery payment — MTN, Orange, current markets and any we add later — goes\nthrough a single method: `initiatePayment()`. Pick the `payment_method`\nyou need and pass a `PaymentData` payload.\n\n```typescript\n// Signature\nclient.initiatePayment(paymentData: PaymentData): Promise<PaymentResponse>\n\n// PaymentData\ninterface PaymentData {\n  amount: number;\n  currency?: Currency;               // XAF | XOF | EUR | USD\n  payment_method: PaymentMethod;     // mtn_mobile_money | orange_money\n  customer_phone: string;            // E.164, e.g. +237677123456\n  customer_name?: string;\n  customer_email?: string;\n  reference?: string;\n  metadata?: Record<string, any>;\n  /** Optional surcharge routed to the SURCHARGE wallet — see billing profile. */\n  surcharge?: number;\n}\n```\n\n#### MTN Mobile Money (Cameroon)\n\n```typescript\nconst payment = await client.initiatePayment({\n  amount: 1000,\n  currency: 'XAF',\n  payment_method: 'mtn_mobile_money',\n  customer_phone: '+237677123456',\n  customer_name: 'Jean Dupont',\n  customer_email: 'jean@example.com',\n  reference: 'ORDER-123',\n  metadata: { order_id: 456, product: 'Premium Plan' },\n});\n```\n\n#### Orange Money (Cameroon)\n\n```typescript\nconst payment = await client.initiatePayment({\n  amount: 2500,\n  currency: 'XAF',\n  payment_method: 'orange_money',\n  customer_phone: '+237677123456',\n  customer_name: 'Marie Ngozi',\n  reference: 'INV-789',\n});\n```\n\n#### Normalising Cameroon phone numbers\n\nIf your customer input arrives in mixed formats (`677…`, `237…`,\n`+237…`), pipe it through `normalizeCameroonPhone()` before calling\n`initiatePayment()`.\n\n```typescript\nimport { normalizeCameroonPhone } from '@elgiosoft/elgiopay-sdk';\n\nconst payment = await client.initiatePayment({\n  amount: 1000,\n  currency: 'XAF',\n  payment_method: 'mtn_mobile_money',\n  customer_phone: normalizeCameroonPhone('677123456'), // → +237677123456\n});\n```\n\n### Payment Status and Verification\n\n```typescript\n// Get payment status\nconst status = await client.getPaymentStatus('txn_abc123');\nconsole.log('Status:', status.status); // 'pending', 'completed', 'failed', etc.\n\n// Verify payment\nconst verification = await client.verifyPayment('txn_abc123');\nif (verification.verified) {\n  console.log('Payment verified successfully!');\n}\n```\n\n### Error Handling\n\n```typescript\nimport { ElgioPayError } from '@elgiosoft/elgiopay-sdk';\n\ntry {\n  const result = await client.initiatePayment({\n    amount: 50,\n    currency: 'XAF',\n    payment_method: 'mtn_mobile_money',\n    customer_phone: 'invalid-phone',\n  });\n} catch (error) {\n  if (error instanceof ElgioPayError) {\n    console.log('Error code:', error.code);\n    console.log('Error message:', error.message);\n    console.log('API response:', error.response);\n  }\n}\n```\n\n### Retry Mechanism\n\n```typescript\n// Automatic retry with exponential backoff\nconst result = await client.createPaymentWithRetry({\n  amount: 1000,\n  payment_method: 'mtn_mobile_money',\n  customer_phone: '+237677123456',\n  currency: 'XAF'\n}, 3); // max 3 retries\n```\n\n## Utilities\n\n### Phone Number Utilities\n\n```typescript\nimport { normalizeCameroonPhone, isValidCameroonPhone } from '@elgiosoft/elgiopay-sdk';\n\n// Normalize phone numbers\nconst normalized = normalizeCameroonPhone('677123456'); // '+237677123456'\nconst normalized2 = normalizeCameroonPhone('237677123456'); // '+237677123456'\n\n// Validate phone numbers\nconst isValid = isValidCameroonPhone('+237677123456'); // true\nconst isInvalid = isValidCameroonPhone('123456789'); // false\n```\n\n### Amount Utilities\n\n```typescript\nimport { validateAmount, formatAmount } from '@elgiosoft/elgiopay-sdk';\n\n// Validate amounts (minimum 100 XAF)\nconst isValidAmount = validateAmount(1000, 'XAF'); // true\nconst isInvalidAmount = validateAmount(50, 'XAF'); // false\n\n// Format amounts for display\nconst formatted = formatAmount(5000, 'XAF'); // \"5 000 FCFA\"\n```\n\n## Environment Configuration\n\n### Development/Testing\n\n```typescript\nconst client = new ElgioPayClient({\n  apiKey: 'pk_test_your_sandbox_key',\n  environment: 'sandbox',\n});\n```\n\n### Production\n\n```typescript\nconst client = new ElgioPayClient({\n  apiKey: 'pk_live_your_live_key',\n  environment: 'prod',\n});\n```\n\n### Environment Variables\n\n```bash\n# .env file\nELGIOPAY_API_KEY=pk_test_your_api_key\nELGIOPAY_ENV=sandbox\n```\n\n```typescript\n// Both are picked up automatically — no config needed.\nconst client = new ElgioPayClient();\n```\n\n## Testing\n\n### Getting API Keys\n\n1. Sign up at [sandbox.elgiopay.com](https://sandbox.elgiopay.com)\n2. Create a new application\n3. Copy your API keys:\n   - `pk_test_...` for sandbox\n   - `pk_live_...` for production\n\n### Test Phone Numbers\n\nFor sandbox testing, use these test phone numbers:\n- MTN: `677123456`, `677123457`, `677123458`\n- Orange: `677123456`, `677123457`, `677123458`\n\nAll sandbox payments will automatically succeed after a few seconds.\n\n### Example Test\n\n```typescript\nimport { ElgioPayClient } from '@elgiosoft/elgiopay-sdk';\n\ndescribe('ElgioPay', () => {\n  const client = new ElgioPayClient({\n    apiKey: 'pk_test_sandbox_key',\n    environment: 'sandbox',\n  });\n\n  it('should create MTN payment', async () => {\n    const result = await client.initiatePayment({\n      amount: 1000,\n      currency: 'XAF',\n      payment_method: 'mtn_mobile_money',\n      customer_phone: '+237677123456',\n      reference: 'TEST-001',\n    });\n\n    expect(result.success).toBe(true);\n    expect(result.transaction_id).toBeDefined();\n  });\n});\n```\n\n## Error Codes\n\n| Code | Description |\n|------|-------------|\n| 400  | Bad Request - Invalid data |\n| 401  | Unauthorized - Invalid API key |\n| 402  | Payment Required - Insufficient funds |\n| 404  | Not Found - Transaction not found |\n| 422  | Validation Error - Invalid input |\n| 500  | Server Error - Internal error |\n\n## Supported Countries & Currencies\n\n| Country | Currency | MTN | Orange |\n|---------|----------|-----|--------|\n| Cameroon | XAF | ✅ | ✅ |\n| Côte d'Ivoire | XOF | ✅ | ✅ |\n| Burkina Faso | XOF | ✅ | ✅ |\n| Ghana | GHS | ✅ | ❌ |\n| Mali | XOF | ❌ | ✅ |\n| Senegal | XOF | ❌ | ✅ |\n\n## Webhooks\n\nSet up webhooks to receive payment status updates:\n\n```typescript\n// Express.js webhook handler\napp.post('/webhooks/elgiopay', (req, res) => {\n  const { transaction_id, status, amount } = req.body;\n  \n  if (status === 'completed') {\n    // Payment successful\n    console.log(`Payment ${transaction_id} completed: ${amount} XAF`);\n    // Update your database\n  } else if (status === 'failed') {\n    // Payment failed\n    console.log(`Payment ${transaction_id} failed`);\n  }\n  \n  res.status(200).send('OK');\n});\n```\n\n## TypeScript Support\n\nThis SDK is written in TypeScript and provides full type definitions:\n\n```typescript\nimport {\n  ElgioPayClient,\n  PaymentResponse,\n  PaymentStatusResponse,\n  ElgioPayError,\n  Currency,\n  PaymentMethod\n} from '@elgiosoft/elgiopay-sdk';\n\n// All types are fully typed\nconst client: ElgioPayClient = new ElgioPayClient({ apiKey: 'key' });\nconst payment: PaymentResponse = await client.initiatePayment({\n  amount: 1000,\n  currency: 'XAF',\n  payment_method: 'mtn_mobile_money',\n  customer_phone: '+237677123456',\n});\n```\n\n## Contributing\n\nWe welcome contributions! Please feel free to submit a Pull Request.\n\n## Support\n\n- 📖 **Documentation**: [https://docs.elgiopay.com](https://docs.elgiopay.com)\n- 🐛 **Issues**: [GitHub Issues](https://github.com/elgiosoft/elgiopay-sdk-node/issues)\n- 💬 **Support**: [developers@elgiosoft.com](mailto:developers@elgiosoft.com)\n- 🌐 **Website**: [https://elgiopay.com](https://elgiopay.com)\n\n## License\n\nMIT License - see the [LICENSE](LICENSE) file for details.\n\n## About Elgiosoft\n\nThis SDK is developed by [Elgiosoft Ltd](https://elgiosoft.com), a leading fintech company specializing in mobile money solutions for Africa.","readmeFilename":"README.md","_rev":"1-f514e110aa3ca88b80e8cc0f21f0ce2a"}