{"_id":"@chabifadeen/mtn-momo","name":"@chabifadeen/mtn-momo","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@chabifadeen/mtn-momo","version":"1.0.0","description":"Professional Node.js SDK for MTN Mobile Money API integration","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","test":"jest","test:coverage":"jest --coverage","lint":"eslint src/**/*.ts","format":"prettier --write \"src/**/*.ts\""},"keywords":["mtn","momo","mobile money","sdk","payments","node","typescript"],"author":{"name":"CHABI DOSSOUMON Abdou Fawaz","email":"chabid19@github.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/chabid19/mtn-momo-nodejs.git"},"bugs":{"url":"https://github.com/chabid19/mtn-momo-nodejs/issues"},"homepage":"https://github.com/chabid19/mtn-momo-nodejs#readme","dependencies":{"axios":"^1.7.0","uuid":"^10.0.0"},"devDependencies":{"@types/jest":"^29.5.0","@types/node":"^20.0.0","@types/uuid":"^10.0.0","eslint":"^9.0.0","jest":"^29.7.0","prettier":"^3.3.0","ts-jest":"^29.1.0","typescript":"^5.5.0"},"_id":"@chabifadeen/mtn-momo@1.0.0","gitHead":"3045dad075d2e403b6f79301639f55db24d67281","_nodeVersion":"22.17.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-YU3l6duo9+Le1z6d9XJe2O1BhpkjHiN0c8kwemcZP9IM1F+KxicbTANWeUsWib7JAuw207T8J/syETrdK3Ih0w==","shasum":"a4a3ad7251d6abd6667d98fc11ae491debab5c5f","tarball":"https://registry.npmjs.org/@chabifadeen/mtn-momo/-/mtn-momo-1.0.0.tgz","fileCount":28,"unpackedSize":59167,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDw8Mk6N1OzVTdoLapTCAKWNs79C3bR+ZqrdikrAsK6QwIhANy9aYi9zCvLdYYAqAKGEgzNrlYQjoxp7fN7vTCaruHE"}]},"_npmUser":{"name":"chabifadeen","email":"chabifadeen@gmail.com"},"directories":{},"maintainers":[{"name":"chabifadeen","email":"chabifadeen@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mtn-momo_1.0.0_1765020468452_0.8542383224226029"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-06T11:27:48.357Z","1.0.0":"2025-12-06T11:27:48.599Z","modified":"2025-12-06T11:27:48.897Z"},"maintainers":[{"name":"chabifadeen","email":"chabifadeen@gmail.com"}],"description":"Professional Node.js SDK for MTN Mobile Money API integration","homepage":"https://github.com/chabid19/mtn-momo-nodejs#readme","keywords":["mtn","momo","mobile money","sdk","payments","node","typescript"],"repository":{"type":"git","url":"git+https://github.com/chabid19/mtn-momo-nodejs.git"},"author":{"name":"CHABI DOSSOUMON Abdou Fawaz","email":"chabid19@github.com"},"bugs":{"url":"https://github.com/chabid19/mtn-momo-nodejs/issues"},"license":"MIT","readme":"# mtn-momo-nodejs\nUn kit de développement logiciel (SDK) Node.js professionnel, robuste et facile à utiliser pour l'intégration des API MTN Mobile Money (collecte, décaissement, transfert de fonds).\n# 💰 MTN MoMo SDK for Node.js\n\n[![npm version](https://badge.fury.io/js/%40chabifadeen%2Fmtn-momo.svg)](https://www.npmjs.com/package/@chabifadeen/mtn-momo)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)\n\nA professional, robust, and easy-to-use Node.js SDK for integrating MTN Mobile Money APIs (Collection, Disbursement, Remittance).\n\n## ✨ Features\n\n- 🔐 **Automatic Authentication**: Token generation, caching, and auto-refresh\n- 📦 **Modular Services**: Separate modules for Collection, Disbursement, and Remittance\n- 🛡️ **Full TypeScript Support**: Complete type definitions and IntelliSense\n- ⚡ **Promise-based API**: Modern async/await syntax\n- 🔄 **Sandbox & Production**: Easy environment switching\n- 🧪 **Well Tested**: Comprehensive unit test coverage\n- 🚨 **Error Handling**: Custom error classes for better debugging\n\n## 📦 Installation\n```bash\nnpm install @chabifadeen/mtn-momo\n```\n\nor with yarn:\n```bash\nyarn add @chabifadeen/mtn-momo\n```\n\n## 🚀 Quick Start\n\n### 1. Configuration\n```typescript\nimport { Client, MoMoConfig } from '@chabifadeen/mtn-momo';\n\nconst config: MoMoConfig = {\n  environment: 'sandbox', // or 'production'\n  subscriptionKey: 'YOUR_SUBSCRIPTION_KEY',\n  apiUser: 'YOUR_API_USER',\n  apiKey: 'YOUR_API_KEY',\n  callbackUrl: 'https://your-webhook.com/callback', // Optional\n};\n\nconst client = new Client(config);\n```\n\n### 2. Collection API (Request to Pay)\n\nRequest payment from a customer:\n```typescript\nconst collection = client.collection();\n\n// Request payment\nconst referenceId = await collection.requestToPay({\n  amount: '500',\n  currency: 'EUR',\n  externalId: 'order-123',\n  payer: {\n    partyIdType: 'MSISDN',\n    partyId: '256774290781',\n  },\n  payerMessage: 'Payment for goods',\n  payeeNote: 'Thanks for your purchase',\n});\n\nconsole.log('Transaction Reference:', referenceId);\n\n// Check transaction status\nconst status = await collection.getTransactionStatus(referenceId);\nconsole.log('Status:', status.status); // SUCCESSFUL, FAILED, PENDING\nconsole.log('Amount:', status.amount);\nconsole.log('Currency:', status.currency);\n\n// Get account balance\nconst balance = await collection.getAccountBalance();\nconsole.log('Available Balance:', balance.availableBalance);\n\n// Validate account holder\nconst isValid = await collection.validateAccountHolder({\n  partyIdType: 'MSISDN',\n  partyId: '256774290781',\n});\nconsole.log('Account Valid:', isValid);\n```\n\n### 3. Disbursement API (Transfer Money)\n\nTransfer money to a recipient:\n```typescript\nconst disbursement = client.disbursement();\n\n// Transfer money\nconst referenceId = await disbursement.transfer({\n  amount: '100',\n  currency: 'EUR',\n  externalId: 'salary-001',\n  payee: {\n    partyIdType: 'MSISDN',\n    partyId: '256774290781',\n  },\n  payerMessage: 'Salary payment',\n  payeeNote: 'Monthly salary - November 2024',\n});\n\n// Check transfer status\nconst status = await disbursement.getTransferStatus(referenceId);\nconsole.log('Transfer Status:', status.status);\n\n// Get account balance\nconst balance = await disbursement.getAccountBalance();\nconsole.log('Balance:', balance);\n```\n\n### 4. Remittance API (International Transfers)\n\nSend money internationally:\n```typescript\nconst remittance = client.remittance();\n\n// Send remittance\nconst referenceId = await remittance.transfer({\n  amount: '200',\n  currency: 'EUR',\n  externalId: 'remit-001',\n  payee: {\n    partyIdType: 'MSISDN',\n    partyId: '256774290781',\n  },\n  payerMessage: 'Money transfer',\n  payeeNote: 'Family support',\n});\n\n// Check status\nconst status = await remittance.getTransferStatus(referenceId);\nconsole.log('Remittance Status:', status);\n```\n\n## 🔧 Advanced Usage\n\n### Custom Configuration\n```typescript\nconst config: MoMoConfig = {\n  environment: 'production',\n  subscriptionKey: process.env.MTN_SUBSCRIPTION_KEY!,\n  apiUser: process.env.MTN_API_USER!,\n  apiKey: process.env.MTN_API_KEY!,\n  callbackUrl: 'https://api.myapp.com/webhooks/mtn',\n  timeout: 30000, // Request timeout in ms\n  retryAttempts: 3, // Number of retry attempts\n};\n```\n\n### Environment Variables\n\nCreate a `.env` file:\n```env\nMTN_ENVIRONMENT=sandbox\nMTN_SUBSCRIPTION_KEY=your_subscription_key\nMTN_API_USER=your_api_user\nMTN_API_KEY=your_api_key\nMTN_CALLBACK_URL=https://your-webhook.com/callback\n```\n\nThen use in your code:\n```typescript\nimport * as dotenv from 'dotenv';\ndotenv.config();\n\nconst config: MoMoConfig = {\n  environment: process.env.MTN_ENVIRONMENT as 'sandbox' | 'production',\n  subscriptionKey: process.env.MTN_SUBSCRIPTION_KEY!,\n  apiUser: process.env.MTN_API_USER!,\n  apiKey: process.env.MTN_API_KEY!,\n  callbackUrl: process.env.MTN_CALLBACK_URL,\n};\n```\n\n### Error Handling\n\nThe SDK provides custom error classes for better error handling:\n```typescript\nimport {\n  MoMoError,\n  MoMoAuthError,\n  MoMoValidationError,\n  MoMoTransactionError,\n  MoMoNetworkError\n} from '@chabifadeen/mtn-momo';\n\ntry {\n  const referenceId = await collection.requestToPay({\n    // ... payment details\n  });\n} catch (error) {\n  if (error instanceof MoMoAuthError) {\n    console.error('Authentication failed:', error.message);\n    // Handle authentication issues (refresh credentials, etc.)\n  } else if (error instanceof MoMoValidationError) {\n    console.error('Validation error:', error.message);\n    // Handle validation errors (check input data)\n  } else if (error instanceof MoMoTransactionError) {\n    console.error('Transaction failed:', error.message, error.code);\n    // Handle transaction failures\n  } else if (error instanceof MoMoNetworkError) {\n    console.error('Network error:', error.message);\n    // Handle network issues (retry, etc.)\n  } else if (error instanceof MoMoError) {\n    console.error('MoMo error:', error.message);\n    // Handle generic MoMo errors\n  } else {\n    console.error('Unexpected error:', error);\n  }\n}\n```\n\n### Webhook Handling\n\nHandle MTN callbacks in your Express app:\n```typescript\nimport express from 'express';\n\nconst app = express();\napp.use(express.json());\n\napp.post('/webhooks/mtn', (req, res) => {\n  const notification = req.body;\n  \n  console.log('Payment notification:', notification);\n  console.log('Reference ID:', notification.referenceId);\n  console.log('Status:', notification.status);\n  console.log('Amount:', notification.amount);\n  \n  // Process the notification\n  // Update your database, send confirmation email, etc.\n  \n  res.sendStatus(200);\n});\n\napp.listen(3000);\n```\n\n## 🧪 Testing\n\nThe SDK includes comprehensive tests. Run them with:\n```bash\nnpm test\n```\n\nFor coverage report:\n```bash\nnpm run test:coverage\n```\n\n## 📖 API Reference\n\n### Client\n```typescript\nnew Client(config: MoMoConfig)\n```\n\n### Collection Service\n\n- `requestToPay(params)` - Request payment from customer\n- `getTransactionStatus(referenceId)` - Get transaction status\n- `getAccountBalance()` - Get account balance\n- `validateAccountHolder(params)` - Validate account holder\n- `getAccountInfo(accountHolderId)` - Get account information\n\n### Disbursement Service\n\n- `transfer(params)` - Transfer money to recipient\n- `getTransferStatus(referenceId)` - Get transfer status\n- `getAccountBalance()` - Get account balance\n- `validateAccountHolder(params)` - Validate recipient\n\n### Remittance Service\n\n- `transfer(params)` - Send international transfer\n- `getTransferStatus(referenceId)` - Get transfer status\n- `getAccountBalance()` - Get account balance\n\n## 🌍 Supported Countries\n\nMTN Mobile Money is available in multiple African countries. Check [MTN's official documentation](https://momodeveloper.mtn.com/) for the latest list of supported countries and currencies.\n\n## 📚 Resources\n\n- [MTN MoMo Developer Portal](https://momodeveloper.mtn.com/)\n- [API Documentation](https://momodeveloper.mtn.com/api-documentation)\n- [Sandbox Testing](https://momodeveloper.mtn.com/docs/services/sandbox-provisioning-api)\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## 📝 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 👨‍💻 Author\n\n**CHABI DOSSOUMON Abdou Fawaz**\n\n- GitHub: [@chabid19](https://github.com/chabid19)\n- Email: chabifadeen@gmail.com\n\n## ⭐ Support\n\nIf you find this SDK helpful, please give it a star on GitHub!\n\n---\n\nMade with ❤️ for the African developer community","readmeFilename":"README.md","_rev":"1-a794f3897a2fffbaf9ab62ed745d6b00"}