{"_id":"9bridge","_rev":"6-12a3f11758bdd4f2c37c6eddff672ee6","name":"9bridge","dist-tags":{"latest":"1.0.5"},"versions":{"1.0.0":{"name":"9bridge","version":"1.0.0","keywords":["paystack","monnify","flutterwave","stellar","x402","nigeria","fintech","payment-gateway","soroban"],"license":"MIT","_id":"9bridge@1.0.0","maintainers":[{"name":"orjinameh","email":"Orjinameh@icloud.com"}],"dist":{"shasum":"ee324009b13579951d30c214be1c56bca12bda08","tarball":"https://registry.npmjs.org/9bridge/-/9bridge-1.0.0.tgz","fileCount":41,"integrity":"sha512-cd4VpanDD7tGQoOv+Mp2U2N282vVJvoMSX+XgzQQBC+KiIsOS35PUUNFykDSC4vCpN7X7uxtBUkK9Jb/lWGxXQ==","signatures":[{"sig":"MEYCIQCAGLq2uR+wtFbuwoMYpJC0Ybh9YijGfu8Kz1401lJd+gIhAOlPyS+f18un0bjLbWk7Rdz/eltLSkZkxPjxRoyLjhJi","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":77720},"main":"dist/index.js","types":"dist/index.d.ts","gitHead":"c7b877f21a789e14bf957cbbebf911be9edeb294","scripts":{"dev":"tsc --watch","lint":"eslint 'src/**/*.ts'","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"orjinameh","email":"Orjinameh@icloud.com"},"_npmVersion":"11.9.0","description":"Aggregates native Nigerian payment gateways, handles local currency webhooks, and outputs Stellar x402 payment challenge layouts","directories":{},"_nodeVersion":"24.14.0","dependencies":{"axios":"^1.7.0","crypto":"^1.0.1","express":"^4.21.0","stellar-sdk":"^12.3.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.5.0","@types/node":"^20.14.0","@types/express":"^4.17.21"},"_npmOperationalInternal":{"tmp":"tmp/9bridge_1.0.0_1787166476788_0.7332744569240304","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"9bridge","version":"1.0.1","keywords":["paystack","monnify","flutterwave","stellar","x402","nigeria","fintech","payment-gateway","soroban"],"license":"MIT","_id":"9bridge@1.0.1","maintainers":[{"name":"orjinameh","email":"Orjinameh@icloud.com"}],"dist":{"shasum":"ff6fc53b44ec56053379551c6f8842b4c14de497","tarball":"https://registry.npmjs.org/9bridge/-/9bridge-1.0.1.tgz","fileCount":42,"integrity":"sha512-Muc3u6JBNxiW7n8giJkH059sI0vp1aOU/dl17h/rjdr8eBordRFlrxcsrbKU2xbsDegsqG4EOTfIf2FLUrgCrQ==","signatures":[{"sig":"MEUCIQCxwUs1uZBy/Qfyrr2gxn8lPeDh7TxweRnaGRyrlox3sAIgKs/vnalceF7dDFeSdA5VSyn9sZcAuqng27KWPOgMLLk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":84443},"main":"dist/index.js","types":"dist/index.d.ts","gitHead":"c7b877f21a789e14bf957cbbebf911be9edeb294","scripts":{"dev":"tsc --watch","lint":"eslint 'src/**/*.ts'","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"orjinameh","email":"Orjinameh@icloud.com"},"_npmVersion":"11.9.0","description":"Aggregates native Nigerian payment gateways, handles local currency webhooks, and outputs Stellar x402 payment challenge layouts","directories":{},"_nodeVersion":"24.14.0","dependencies":{"axios":"^1.7.0","crypto":"^1.0.1","express":"^4.21.0","stellar-sdk":"^12.3.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.5.0","@types/node":"^20.14.0","@types/express":"^4.17.21"},"_npmOperationalInternal":{"tmp":"tmp/9bridge_1.0.1_1787166697543_0.0012235410730629948","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"9bridge","version":"1.0.2","keywords":["paystack","monnify","flutterwave","stellar","x402","nigeria","fintech","payment-gateway","soroban"],"license":"MIT","_id":"9bridge@1.0.2","maintainers":[{"name":"orjinameh","email":"Orjinameh@icloud.com"}],"dist":{"shasum":"63e9e4bee75c8dec75d3094e7334705250f97428","tarball":"https://registry.npmjs.org/9bridge/-/9bridge-1.0.2.tgz","fileCount":46,"integrity":"sha512-bZfRi2DDB90TZnbEXw2WeL74lMjsObggSV/Xd23sTir+YAyVh7JgXdw1Lz4vth2tw3982mE2CBLufBW3yyHtuQ==","signatures":[{"sig":"MEUCIDDOrI+t4ELweVM9BM7hcWwN4xv1Yw+e0hHGSkQEc+w8AiEA+9unYFgJREYT7qnHEUwrG6Nsabtcups/vk7TSex10eM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":93051},"main":"dist/index.js","types":"dist/index.d.ts","gitHead":"c7b877f21a789e14bf957cbbebf911be9edeb294","scripts":{"dev":"tsc --watch","lint":"eslint 'src/**/*.ts'","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"orjinameh","email":"Orjinameh@icloud.com"},"_npmVersion":"11.9.0","description":"Aggregates native Nigerian payment gateways, handles local currency webhooks, and outputs Stellar x402 payment challenge layouts","directories":{},"_nodeVersion":"24.14.0","dependencies":{"axios":"^1.7.0","crypto":"^1.0.1","express":"^4.21.0","stellar-sdk":"^12.3.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.5.0","@types/node":"^20.14.0","@types/express":"^4.17.21"},"_npmOperationalInternal":{"tmp":"tmp/9bridge_1.0.2_1787168653310_0.1944220621392616","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"9bridge","version":"1.0.3","keywords":["paystack","monnify","flutterwave","stellar","x402","nigeria","fintech","payment-gateway","soroban"],"license":"MIT","_id":"9bridge@1.0.3","maintainers":[{"name":"orjinameh","email":"Orjinameh@icloud.com"}],"dist":{"shasum":"1499e2daf5f771e8d2371909dd25c31b82f80ead","tarball":"https://registry.npmjs.org/9bridge/-/9bridge-1.0.3.tgz","fileCount":46,"integrity":"sha512-vwszdKkexozUlbLgW6vORhTF8Z5l0fnrjhGxMrWlAC1Sa6ZuMXoxdS03imlRiMDZgGw2bAUdE0IeyPVkQ0o+Qw==","signatures":[{"sig":"MEUCIF0UsNsSCNLZFa8yeW+FpCEEaVOtTnukiUELJ9Zr1YNkAiEAkub37nfw4WdEF66qOz/TJJ9BpaH4IF5S4EUvRQZKRJY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":93051},"main":"dist/index.js","types":"dist/index.d.ts","gitHead":"c7b877f21a789e14bf957cbbebf911be9edeb294","scripts":{"dev":"tsc --watch","lint":"eslint 'src/**/*.ts'","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"orjinameh","email":"Orjinameh@icloud.com"},"_npmVersion":"11.9.0","description":"Aggregates native Nigerian payment gateways, handles local currency webhooks, and outputs Stellar x402 payment challenge layouts","directories":{},"_nodeVersion":"24.14.0","dependencies":{"axios":"^1.7.0","crypto":"^1.0.1","express":"^4.21.0","stellar-sdk":"^12.3.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.5.0","@types/node":"^20.14.0","@types/express":"^4.17.21"},"_npmOperationalInternal":{"tmp":"tmp/9bridge_1.0.3_1787168824566_0.5343069824586602","host":"s3://npm-registry-packages-npm-production"}},"1.0.4":{"name":"9bridge","version":"1.0.4","keywords":["paystack","monnify","flutterwave","stellar","x402","nigeria","fintech","payment-gateway","soroban"],"license":"MIT","_id":"9bridge@1.0.4","maintainers":[{"name":"orjinameh","email":"Orjinameh@icloud.com"}],"dist":{"shasum":"f4fb82e4c35af2a93f7320ebfbbfd1eae2d9aa42","tarball":"https://registry.npmjs.org/9bridge/-/9bridge-1.0.4.tgz","fileCount":46,"integrity":"sha512-bYwxiIErZKJJSFxyiZnCJ12Qd9Bv9eNpOwLQ9+4YPSxZF1KEGG45qH5eilEpRhcm2S0fxGaxnkWxaYd2HySVhQ==","signatures":[{"sig":"MEYCIQD4fK2egRdZFS7X5DFK27EkDfD8+1rSKfjspgt6R7/zIAIhAO0NOsZHu4dcH8vRW8I0vnCYG5H1HJGVD5xfdUd2ls5p","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":93051},"main":"dist/index.js","types":"dist/index.d.ts","gitHead":"c7b877f21a789e14bf957cbbebf911be9edeb294","scripts":{"dev":"tsc --watch","lint":"eslint 'src/**/*.ts'","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"orjinameh","email":"Orjinameh@icloud.com"},"_npmVersion":"11.9.0","description":"Aggregates native Nigerian payment gateways, handles local currency webhooks, and outputs Stellar x402 payment challenge layouts","directories":{},"_nodeVersion":"24.14.0","dependencies":{"axios":"^1.7.0","crypto":"^1.0.1","express":"^4.21.0","stellar-sdk":"^12.3.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.5.0","@types/node":"^20.14.0","@types/express":"^4.17.21"},"_npmOperationalInternal":{"tmp":"tmp/9bridge_1.0.4_1787168902105_0.6162965525113944","host":"s3://npm-registry-packages-npm-production"}},"1.0.5":{"name":"9bridge","version":"1.0.5","description":"Aggregates native Nigerian payment gateways, handles local currency webhooks, and outputs Stellar x402 payment challenge layouts","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","dev":"tsc --watch","lint":"eslint 'src/**/*.ts'","prepublishOnly":"npm run build"},"keywords":["paystack","monnify","flutterwave","stellar","x402","nigeria","fintech","payment-gateway","soroban"],"license":"MIT","dependencies":{"axios":"^1.7.0","crypto":"^1.0.1","express":"^4.21.0","stellar-sdk":"^12.3.0"},"devDependencies":{"@types/express":"^4.17.21","@types/node":"^20.14.0","typescript":"^5.5.0"},"gitHead":"c7b877f21a789e14bf957cbbebf911be9edeb294","_id":"9bridge@1.0.5","_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-Vu82DeD99Z5qEfwR6L5EfXQodwsW8+/fgLQkxcInx5gcIkGZv2WoaX0eVg80tkz7hdqOpRYm0W6vN01kzeVN2Q==","shasum":"b63c93b19dbf265e2c47cdff067d302bd6f255fc","tarball":"https://registry.npmjs.org/9bridge/-/9bridge-1.0.5.tgz","fileCount":46,"unpackedSize":94955,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD9/qzr1jo2bzwB5riSPbY3K16fGNmhpTv1mnWiB/4eCAIhAMGCE1MGkfdkjYI5gew8+nJ84076LuAAhhBImbFcInsq"}]},"_npmUser":{"name":"orjinameh","email":"Orjinameh@icloud.com"},"directories":{},"maintainers":[{"name":"orjinameh","email":"Orjinameh@icloud.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/9bridge_1.0.5_1787169041053_0.055063814435433844"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-19T19:07:56.471Z","modified":"2026-08-19T19:50:41.319Z","1.0.0":"2026-08-19T19:07:56.947Z","1.0.1":"2026-08-19T19:11:37.712Z","1.0.2":"2026-08-19T19:44:13.448Z","1.0.3":"2026-08-19T19:47:04.717Z","1.0.4":"2026-08-19T19:48:22.241Z","1.0.5":"2026-08-19T19:50:41.192Z"},"license":"MIT","keywords":["paystack","monnify","flutterwave","stellar","x402","nigeria","fintech","payment-gateway","soroban"],"description":"Aggregates native Nigerian payment gateways, handles local currency webhooks, and outputs Stellar x402 payment challenge layouts","maintainers":[{"name":"orjinameh","email":"Orjinameh@icloud.com"}],"readme":"# 9bridge\n\nNigerian payment gateway aggregator with Stellar x402 payment challenge output.\n\nAggregates **Paystack**, **Monnify**, and **Flutterwave** behind a single interface, normalizes webhooks into a unified event schema, and converts verified fiat payments into Stellar USDC via Soroban smart contracts following the [x402](https://x402.org/) protocol.\n\n## Install\n\n```bash\nnpm install 9bridge\n```\n\n## Quick Start\n\n```ts\nimport { create9bridge } from '9bridge';\nimport express from 'express';\n\nconst app = express();\n\n// Capture raw body for signature verification\napp.use(express.json({\n  verify: (req, _res, buf) => { (req as any).rawBody = buf.toString(); }\n}));\n\nconst { gatewayFactory, webhookRouter } = create9bridge(\n  {\n    paystack:    { apiKey: 'sk_live_...' },\n    monnify:     { apiKey: '...', secretKey: '...', contractCode: '...' },\n    flutterwave: { apiKey: 'FLWSECK-...' },\n  },\n  {\n    paystackSecret:    'whsec_...',\n    flutterwaveSecret: 'FLWSECK-...',\n    stellarPayTo:      'G...YOUR_STELLAR_PUBLIC_KEY',\n    sorobanContractId: 'C...YOUR_CONTRACT_ID',\n    stellarNetwork:    'testnet',\n  }\n);\n\n// Mount the webhook endpoint\napp.use(webhookRouter);\n\n// Use adapters directly\nconst paystack = gatewayFactory.resolve('card');\nconst { data } = await paystack.initializePayment({\n  amount: 5000,\n  currency: 'NGN',\n  email: 'buyer@example.com',\n});\n\napp.listen(3000);\n```\n\n## Payment Channels\n\n| Channel | Gateway | Trigger Methods |\n|---------|---------|-----------------|\n| `card` | Paystack | `card`, `cards`, `debit_card`, `checkout` |\n| `transfer` | Monnify | `transfer`, `bank_transfer`, `virtual_account` |\n| `ussd_wallet` | Flutterwave | `ussd`, `wallet`, `opay`, `palmpay`, `mobile_money` |\n\n## API Reference\n\n### `create9bridge(gatewayConfig, webhookConfig)`\n\nEntry point. Returns `{ gatewayFactory, webhookRouter }`.\n\n### `GatewayFactory`\n\n```ts\nimport { GatewayFactory } from '9bridge';\n\nconst factory = new GatewayFactory(config);\nfactory.initialize();\n\n// Resolve by channel name\nconst adapter = factory.resolve('card');\n\n// Resolve by any supported alias\nconst adapter = factory.resolveByMethod('checkout');\n\n// List configured channels\nfactory.getAvailableChannels(); // ['card', 'transfer', 'ussd_wallet']\n```\n\n### `PaystackAdapter`\n\n```ts\nconst paystack = factory.resolve('card');\n\n// Initialize\nconst init = await paystack.initializePayment({\n  amount: 5000,\n  currency: 'NGN',\n  email: 'buyer@example.com',\n  reference: 'custom-ref-123',\n  metadata: { orderId: '42' },\n});\n// init.data.authorization_url → redirect user here\n\n// Verify\nconst verification = await paystack.verifyPayment('custom-ref-123');\n// verification.data.status === 'success'\n\n// List banks (optional)\nconst banks = await paystack.listBanks();\n```\n\n### `MonnifyAdapter`\n\n```ts\nconst monnify = factory.resolve('transfer');\n\n// Initialize bank transfer\nconst init = await monnify.initializePayment({\n  amount: 10000,\n  currency: 'NGN',\n  email: 'buyer@example.com',\n});\n\n// Create virtual account for a customer\nconst account = await monnify.createVirtualAccount('customer-123');\n// account.data.accounts[0].account_number → share with customer\n\n// Initiate outbound transfer\nconst transfer = await monnify.initiateTransfer({\n  amount: 5000,\n  currency: 'NGN',\n  destination_bank_code: '044',\n  destination_account_number: '1234567890',\n  reference: 'disb-001',\n});\n```\n\n### `FlutterwaveAdapter`\n\n```ts\nconst flutterwave = factory.resolve('ussd_wallet');\n\n// Initialize payment\nconst init = await flutterwave.initializePayment({\n  amount: 2000,\n  currency: 'NGN',\n  email: 'buyer@example.com',\n});\n\n// Initiate USSD\nconst ussd = await flutterwave.initiateUSSD({\n  amount: 2000,\n  currency: 'NGN',\n  email: 'buyer@example.com',\n  phone_number: '+2348012345678',\n  ussd_type: 'generic',\n});\n\n// Verify\nconst verification = await flutterwave.verifyPayment('FW-txref-123');\n```\n\n## Webhook Endpoint\n\n**POST** `/api/v1/webhooks/payment-listener`\n\nThe router handles four steps:\n\n1. **Detects gateway** from headers (`x-paystack-signature`, `flutterwave-signature`, `monnify-signature`)\n2. **Verifies signature** using the configured secret\n3. **Normalizes payload** into `IVerifiedPaymentEvent`\n4. **Builds x402 response** with Soroban swap simulation\n\n### Response\n\nReturns HTTP **402** with the x402 payment challenge:\n\n```json\n{\n  \"requiresPayment\": true,\n  \"paymentRequirements\": {\n    \"network\": \"testnet\",\n    \"x402Version\": 1,\n    \"accepts\": [\"stellar:usdc@testnet\", \"soroban:C...\"],\n    \"maxAmountRequired\": \"3.125000\",\n    \"resource\": \"/payments/ref-123\",\n    \"description\": \"9bridge payment: NGN 5000.00 from paystack via card\",\n    \"mimeType\": \"application/json\",\n    \"payTo\": \"G...\",\n    \"extraHeaders\": {\n      \"X-9bridge-Tx-Reference\": \"ref-123\",\n      \"X-9bridge-Gateway\": \"paystack\",\n      \"X-9bridge-Channel\": \"card\",\n      \"X-9bridge-Original-Amount\": \"NGN 5000.00\"\n    }\n  },\n  \"paymentReceipt\": {\n    \"success\": true,\n    \"transactionHash\": \"a1b2c3...\",\n    \"payer\": \"buyer@example.com\",\n    \"paymentId\": \"12345\",\n    \"network\": \"testnet\",\n    \"amount\": \"3.125000\"\n  }\n}\n```\n\nThe `transactionHash` in the receipt is a **simulated payment ID** derived from the verified payment event and contract parameters. It is deterministic and does not represent an actual on-chain Stellar transaction. The real on-chain hash is produced when the Soroban contract is invoked by the recipient wallet.\n\nThe simulated payment ID is set in the `X-PAYMENT-RESPONSE` header.\n\n### `IVerifiedPaymentEvent`\n\nAll gateway payloads are normalized to this shape:\n\n```ts\ninterface IVerifiedPaymentEvent {\n  transactionId: string;\n  reference: string;\n  amount: number;\n  currency: string;\n  status: 'success' | 'failed' | 'pending' | 'reversed';\n  channel: 'card' | 'transfer' | 'ussd_wallet';\n  gateway: 'paystack' | 'monnify' | 'flutterwave';\n  paidAt: string;\n  createdAt: string;\n  customer: { id?: string; email: string; name?: string; phone?: string };\n  fees: { gateway_fee: number; processing_fee: number; total_fee: number; currency: string };\n  metadata: Record<string, unknown>;\n  rawPayload: Record<string, unknown>;\n}\n```\n\n## Exchange Rate Provider\n\nThe x402 pipeline converts NGN to USDC using a pluggable exchange rate provider. By default it uses a static rate of 1600 NGN = 1 USD.\n\n### Built-in providers\n\n```ts\nimport {\n  StaticExchangeRateProvider,\n  CoinGeckoExchangeRateProvider,\n  CompositeExchangeRateProvider,\n} from '9bridge';\n```\n\n| Provider | Source | Use case |\n|----------|--------|----------|\n| `StaticExchangeRateProvider` | Hardcoded rate | Default fallback, testing |\n| `CoinGeckoExchangeRateProvider` | CoinGecko API | Live market rates |\n| `CompositeExchangeRateProvider` | Tries providers in order | Resilience, production |\n\n### Using a live rate provider\n\n```ts\nimport { create9bridge, CompositeExchangeRateProvider, CoinGeckoExchangeRateProvider } from '9bridge';\n\nconst { gatewayFactory, webhookRouter } = create9bridge(\n  gatewayConfig,\n  {\n    ...webhookConfig,\n    exchangeRateProvider: new CompositeExchangeRateProvider([\n      new CoinGeckoExchangeRateProvider(),\n    ]),\n  }\n);\n```\n\n### Custom provider\n\nImplement the `IExchangeRateProvider` interface:\n\n```ts\nimport { IExchangeRateProvider, IExchangeRateQuote } from '9bridge';\n\nclass MyProvider implements IExchangeRateProvider {\n  async getRate(from: string, to: string): Promise<IExchangeRateQuote> {\n    const rate = await fetchMyRate(from, to);\n    return {\n      rate,\n      from,\n      to,\n      timestamp: new Date().toISOString(),\n      source: 'my-source',\n      quoteId: 'optional-id',\n      expiresAt: 'optional-expiry',\n    };\n  }\n}\n```\n\n## x402 Pipeline\n\n```ts\nimport { buildX402PaymentChallenge, simulateSorobanSwap } from '9bridge';\n\n// Swap simulation (now async — fetches live exchange rate)\nconst result = await simulateSorobanSwap(verifiedEvent, {\n  payTo: 'G...',\n  sorobanContractId: 'C...',\n  network: 'testnet',\n});\n// result.simulatedPaymentId  — deterministic ID, NOT an on-chain tx hash\n// result.toAmount            — USDC amount after conversion\n// result.exchangeRate        — rate source, timestamp, quote ID\n\n// Full x402 challenge\nconst challenge = await buildX402PaymentChallenge(verifiedEvent, {\n  payTo: 'G...',\n  sorobanContractId: 'C...',\n  network: 'testnet',\n});\n```\n\n## Standalone Usage (no Express)\n\n```ts\nimport { PaystackAdapter, parseWebhookEvent } from '9bridge';\n\nconst paystack = new PaystackAdapter('sk_live_...');\nconst event = parseWebhookEvent('paystack', rawPayload);\n\nif (event.status === 'success') {\n  // handle confirmed payment\n}\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}