{"_id":"@charleslit/payment-gateway-kenya","name":"@charleslit/payment-gateway-kenya","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@charleslit/payment-gateway-kenya","version":"1.0.0","description":"A flexible payment gateway package for Kenya supporting multiple payment providers","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","build:watch":"tsc --watch","clean":"rm -rf dist","prepublishOnly":"npm run clean && npm run build","test":"echo \"Tests will be added later\" && exit 0","publish:private":"npm publish --access restricted"},"keywords":["payment","gateway","kenya","pesapal","mpesa","typescript","nodejs"],"author":{"name":"Photon Power"},"license":"MIT","dependencies":{"axios":"^1.7.9","zod":"^3.23.8"},"devDependencies":{"@types/node":"^22.5.5","typescript":"^5.5.3"},"peerDependencies":{"@supabase/supabase-js":"^2.48.1"},"engines":{"node":">=16.0.0"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/photon-power/payment-gateway-kenya.git"},"bugs":{"url":"https://github.com/photon-power/payment-gateway-kenya/issues"},"homepage":"https://github.com/photon-power/payment-gateway-kenya#readme","gitHead":"77b141d002b9416de74f94c096413698394edca0","_id":"@charleslit/payment-gateway-kenya@1.0.0","_nodeVersion":"20.19.2","_npmVersion":"9.2.0","dist":{"integrity":"sha512-svydsSwtSheyvaAv1JvTKTutC6did1hZrEa+9HixCJuoxPULDZ/LxjvW7ySe13KlMmF6Oi/cxMWb9nkeQ9GpJQ==","shasum":"e86dd968ed610ecc08b446d49a1405ce7944a3cb","tarball":"https://registry.npmjs.org/@charleslit/payment-gateway-kenya/-/payment-gateway-kenya-1.0.0.tgz","fileCount":26,"unpackedSize":86878,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGN6lAa+QPf2f+6PFqrjaMm5GOfZmFXGrzgH0nUdWVyyAiEAopfusmU0VEOHhx6D3ytk5RCUaVOklS3qYS5PAEGdejM="}]},"_npmUser":{"name":"charleslit","email":"momanyicharles109@gmail.com"},"directories":{},"maintainers":[{"name":"charleslit","email":"momanyicharles109@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/payment-gateway-kenya_1.0.0_1758699594692_0.6643143086388701"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-24T07:39:54.629Z","1.0.0":"2025-09-24T07:39:54.868Z","modified":"2025-09-24T07:39:55.105Z"},"maintainers":[{"name":"charleslit","email":"momanyicharles109@gmail.com"}],"description":"A flexible payment gateway package for Kenya supporting multiple payment providers","homepage":"https://github.com/photon-power/payment-gateway-kenya#readme","keywords":["payment","gateway","kenya","pesapal","mpesa","typescript","nodejs"],"repository":{"type":"git","url":"git+https://github.com/photon-power/payment-gateway-kenya.git"},"author":{"name":"Photon Power"},"bugs":{"url":"https://github.com/photon-power/payment-gateway-kenya/issues"},"license":"MIT","readme":"# Payment Gateway Kenya\n\nA flexible, TypeScript-first payment gateway package for Kenya supporting multiple payment providers including Pesapal, M-Pesa, and more.\n\n## Features\n\n- 🏦 **Multiple Payment Providers** - Currently supports Pesapal with easy extensibility for more providers\n- 💳 **Multiple Payment Methods** - M-Pesa, Card payments, Bank transfers, and Cash on Delivery\n- 🔒 **Type Safe** - Full TypeScript support with comprehensive type definitions\n- 🔧 **Configurable** - Environment-based configuration with validation\n- 🔌 **Extensible** - Plugin architecture for adding new payment providers\n- 📊 **Database Integration** - Optional Supabase integration for transaction storage\n- 🚀 **Framework Agnostic** - Works with any Node.js framework (Express, Next.js, etc.)\n\n## Installation\n\n```bash\nnpm install @photon-power/payment-gateway-kenya\n```\n\n## Quick Start\n\n### Basic Setup\n\n```typescript\nimport { PaymentGateway, createPesapalConfig } from '@photon-power/payment-gateway-kenya';\n\n// Create configuration\nconst config = createPesapalConfig(\n  'your-pesapal-consumer-key',\n  'your-pesapal-consumer-secret',\n  {\n    callbackUrl: 'https://your-domain.com/api/payments/callback',\n    ipnId: 'your-pesapal-ipn-id',\n    currency: 'KES'\n  }\n);\n\n// Initialize payment gateway\nconst paymentGateway = new PaymentGateway(config);\n```\n\n### Environment Variables Setup\n\n```bash\n# Pesapal Configuration\nPESAPAL_CONSUMER_KEY=your_consumer_key\nPESAPAL_CONSUMER_SECRET=your_consumer_secret\nPESAPAL_BASE_URL=https://pay.pesapal.com/v3\nPESAPAL_CALLBACK_URL=https://your-domain.com/api/payments/callback\nPESAPAL_IPN_ID=your_ipn_id\n\n# General Configuration\nCURRENCY=KES\nNODE_ENV=production\n```\n\n```typescript\nimport { createPaymentGatewayFromEnv } from '@photon-power/payment-gateway-kenya';\n\n// Create gateway from environment variables\nconst paymentGateway = createPaymentGatewayFromEnv();\n```\n\n## Usage Examples\n\n### Initiating a Payment\n\n```typescript\nimport { PaymentRequest } from '@photon-power/payment-gateway-kenya';\n\nconst paymentRequest: PaymentRequest = {\n  customer: {\n    fullName: 'John Doe',\n    email: 'john@example.com',\n    phone: '+254700000000',\n    address: '123 Main St',\n    city: 'Nairobi',\n    county: 'Nairobi',\n    postalCode: '00100'\n  },\n  paymentMethod: 'MPESA',\n  items: [\n    {\n      id: 'item-1',\n      name: 'Solar Panel',\n      price: 15000,\n      quantity: 1\n    }\n  ],\n  totals: {\n    subtotal: 15000,\n    shipping: 500,\n    tax: 2325,\n    total: 17825\n  },\n  acceptedPolicyHashes: {\n    'privacy': 'hash123',\n    'terms': 'hash456'\n  }\n};\n\ntry {\n  const response = await paymentGateway.initiatePayment(paymentRequest);\n  \n  if (response.success) {\n    if (response.redirectUrl) {\n      // Redirect user to payment page\n      console.log('Redirect to:', response.redirectUrl);\n    } else if (response.cod) {\n      // Handle cash on delivery\n      console.log('Cash on delivery order created');\n    }\n  }\n} catch (error) {\n  console.error('Payment initiation failed:', error);\n}\n```\n\n### Verifying a Payment\n\n```typescript\ntry {\n  const verification = await paymentGateway.verifyPayment('order-tracking-id');\n  \n  console.log('Payment Status:', verification.status);\n  console.log('Payment Method:', verification.paymentMethod);\n  console.log('Amount:', verification.amount);\n} catch (error) {\n  console.error('Payment verification failed:', error);\n}\n```\n\n### Handling Payment Callbacks\n\n```typescript\n// Express.js example\napp.post('/api/payments/callback', async (req, res) => {\n  try {\n    const result = await paymentGateway.handleCallback(req.body, 'pesapal');\n    \n    // Update your application state based on payment status\n    console.log('Payment callback processed:', result);\n    \n    res.status(200).send('OK');\n  } catch (error) {\n    console.error('Callback processing failed:', error);\n    res.status(500).send('ERROR');\n  }\n});\n```\n\n## Configuration\n\n### Complete Configuration Example\n\n```typescript\nimport { PaymentGatewayConfig } from '@photon-power/payment-gateway-kenya';\n\nconst config: PaymentGatewayConfig = {\n  providers: {\n    pesapal: {\n      name: 'pesapal',\n      enabled: true,\n      credentials: {\n        consumerKey: 'your-consumer-key',\n        consumerSecret: 'your-consumer-secret',\n        baseUrl: 'https://pay.pesapal.com/v3',\n        callbackUrl: 'https://your-domain.com/callback',\n        ipnId: 'your-ipn-id'\n      },\n      settings: {\n        currency: 'KES',\n        timeout: 10000\n      }\n    }\n  },\n  database: {\n    client: supabaseClient, // Optional: Supabase client for transaction storage\n    transactionsTable: 'transactions'\n  },\n  currency: 'KES',\n  environment: 'production'\n};\n```\n\n### Database Integration (Optional)\n\nIf you want automatic transaction storage, provide a Supabase client:\n\n```typescript\nimport { createClient } from '@supabase/supabase-js';\n\nconst supabaseClient = createClient(\n  'your-supabase-url',\n  'your-supabase-service-role-key'\n);\n\nconst config = {\n  // ... other config\n  database: {\n    client: supabaseClient,\n    transactionsTable: 'transactions' // optional, defaults to 'transactions'\n  }\n};\n```\n\n## API Reference\n\n### PaymentGateway\n\nMain class for handling payments.\n\n#### Methods\n\n- `initiatePayment(request: PaymentRequest, preferredProvider?: string): Promise<PaymentResponse>`\n- `verifyPayment(orderTrackingId: string, providerName?: string): Promise<PaymentVerificationResponse>`\n- `handleCallback(callbackData: any, providerName: string): Promise<PaymentVerificationResponse>`\n- `getProvider(name: string): PaymentProvider | undefined`\n- `getProviders(): PaymentProvider[]`\n\n### Payment Methods\n\nSupported payment methods:\n- `MPESA` - M-Pesa mobile money\n- `Card` - Credit/Debit card payments\n- `Bank` - Bank transfer\n- `Cash` - Cash on delivery\n\n### Payment Status\n\n- `PENDING` - Payment initiated but not completed\n- `COMPLETED` - Payment successful\n- `FAILED` - Payment failed\n- `CANCELLED` - Payment cancelled\n- `PENDING_COD` - Cash on delivery order created\n- `UNKNOWN` - Status unknown\n\n## Adding New Payment Providers\n\nTo add a new payment provider, extend the `PaymentProvider` base class:\n\n```typescript\nimport { PaymentProvider } from '@photon-power/payment-gateway-kenya';\n\nexport class MyCustomProvider extends PaymentProvider {\n  getSupportedPaymentMethods() {\n    return ['MPESA', 'Card'];\n  }\n\n  async initiatePayment(request) {\n    // Implementation\n  }\n\n  async verifyPayment(orderTrackingId) {\n    // Implementation\n  }\n\n  validateConfig() {\n    // Validate configuration\n  }\n\n  getRequiredConfigFields() {\n    return ['apiKey', 'secretKey'];\n  }\n}\n```\n\n## Error Handling\n\nThe package provides specific error types:\n\n```typescript\nimport { PaymentGatewayError, ValidationError, ProviderError } from '@photon-power/payment-gateway-kenya';\n\ntry {\n  await paymentGateway.initiatePayment(request);\n} catch (error) {\n  if (error instanceof ValidationError) {\n    console.log('Validation failed:', error.validationErrors);\n  } else if (error instanceof ProviderError) {\n    console.log('Provider error:', error.provider, error.message);\n  } else if (error instanceof PaymentGatewayError) {\n    console.log('Gateway error:', error.code, error.message);\n  }\n}\n```\n\n## License\n\nMIT\n\n## Contributing\n\nContributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.\n\n## Support\n\nFor support, please open an issue on our GitHub repository or contact us at support@photon-power.com.\n","readmeFilename":"README.md","_rev":"1-bb80e6f9fa169022b6f8a23d1ca083a3"}