{"_id":"@aruntimalsina/fonepay-reusable-client","_rev":"2-de614b6434b0228ba4c920ceaa6c0216","name":"@aruntimalsina/fonepay-reusable-client","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@aruntimalsina/fonepay-reusable-client","version":"1.0.0","license":"MIT","_id":"@aruntimalsina/fonepay-reusable-client@1.0.0","maintainers":[{"name":"arunti","email":"adilgkn@gmail.com"}],"dist":{"shasum":"6493d4559ad8d114fed9e559b83faf42f98a1b81","tarball":"https://registry.npmjs.org/@aruntimalsina/fonepay-reusable-client/-/fonepay-reusable-client-1.0.0.tgz","fileCount":3,"integrity":"sha512-MpmsJ1rG/g8UrLxgbwjxfA4vlvZifIfIgC0vPITSMumGBolqiqpnu4TWZUU90LE1zRZeUKWV89AfyB3d0a/g0g==","signatures":[{"sig":"MEUCIG/FP3p0g15wsoV5n9DXYfpr1O/sd8zF40yh1DPVS8jKAiEAsVtejpjg5Hwen4KIzJ0amNIG5m0k3mgXd5MFkw/JXNI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":3550},"main":"./src/index.mjs","type":"module","engines":{"node":">=18"},"exports":{".":"./src/index.mjs"},"gitHead":"8bff0d08534c424bee3f623b63319f98094abe24","_npmUser":{"name":"arunti","email":"adilgkn@gmail.com"},"_npmVersion":"10.9.8","description":"JavaScript client for the reusable Fonepay REST API","directories":{},"_nodeVersion":"22.23.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/fonepay-reusable-client_1.0.0_1786917606264_0.022877033781478096","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@aruntimalsina/fonepay-reusable-client","version":"1.0.1","description":"Dependency-free Node.js client for Fonepay QR payments and settlement verification through a reusable REST API","keywords":["fonepay","fonepay-api","fonepay-qr","nepal-payments","nepal-payment-gateway","qr-payment","dynamic-qr","payment-gateway","payment-verification","settlement-verification","digital-payments","nodejs-payments","javascript-payments","express-payments","nextjs-payments"],"type":"module","main":"./src/index.mjs","exports":{".":"./src/index.mjs"},"engines":{"node":">=18"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/dannybyarun/fonepay-reusable.git","directory":"packages/javascript"},"homepage":"https://github.com/dannybyarun/fonepay-reusable/tree/main/packages/javascript#readme","bugs":{"url":"https://github.com/dannybyarun/fonepay-reusable/issues"},"publishConfig":{"access":"public"},"_id":"@aruntimalsina/fonepay-reusable-client@1.0.1","gitHead":"61095fc6073c5176d3ef9380e3b31347dd9fca64","_nodeVersion":"22.23.2","_npmVersion":"10.9.8","dist":{"integrity":"sha512-sJ0VHSgS7Ge85pxuCf9oPsK02nQEE+Lev3jELQmmScG9DDwJbBS5zDazmmGsZqOodSHQosJ3FTshmUKms9PJ/Q==","shasum":"2031fd81407bd889c6fc7116dfb1078b6696c765","tarball":"https://registry.npmjs.org/@aruntimalsina/fonepay-reusable-client/-/fonepay-reusable-client-1.0.1.tgz","fileCount":3,"unpackedSize":8877,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC6lTxCCdCmX4XISlj7X4VzsLZmNquy9BrQvEIfp4FOcwIgdImSTWaRqtLlm/1+o7G3KmTBCCEieYvOPStYqUT6D8A="}]},"_npmUser":{"name":"arunti","email":"adilgkn@gmail.com"},"directories":{},"maintainers":[{"name":"arunti","email":"adilgkn@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/fonepay-reusable-client_1.0.1_1786918066992_0.2796952473876071"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-16T22:00:06.152Z","modified":"2026-08-16T22:07:47.307Z","1.0.0":"2026-08-16T22:00:06.418Z","1.0.1":"2026-08-16T22:07:47.143Z"},"license":"MIT","description":"Dependency-free Node.js client for Fonepay QR payments and settlement verification through a reusable REST API","maintainers":[{"name":"arunti","email":"adilgkn@gmail.com"}],"readme":"# Fonepay Reusable JavaScript Client\n\nA dependency-free Node.js client for the **Fonepay QR payment and settlement-verification REST API**. Use it in Express, Next.js server routes, NestJS, Fastify, serverless functions, background workers, and other JavaScript or TypeScript backends.\n\nThis package does not call Fonepay directly from the browser. Your application calls the reusable Fonepay service, which keeps merchant credentials on the server and normalizes QR creation and payment verification.\n\n## Features\n\n- Dynamic Fonepay QR payment requests\n- Payment verification against settlement reports\n- Exact merchant-reference and amount matching\n- Optional internal API-key authentication\n- Standard `fetch` support with no runtime dependencies\n- Request timeout handling\n- Normalized `FonepayApiError` errors\n- Works with Node.js 18+, Express, Next.js, NestJS, Fastify, and server jobs\n- NPR payment support\n\n## Search keywords\n\nFonepay, Fonepay API, Fonepay QR, Nepal payments, Nepal payment gateway, QR payment, dynamic QR, payment verification, settlement verification, digital payments, Node.js payments, JavaScript payments, Express payments, and Next.js payments.\n\n## Installation\n\n```bash\nnpm install @aruntimalsina/fonepay-reusable-client\n```\n\nNode.js 18 or newer is required because the package uses the native `fetch` API.\n\n## Configuration\n\nKeep the service URL and API key in backend environment variables:\n\n```bash\nFONEPAY_SERVICE_URL=https://payments.example.com\nFONEPAY_SERVICE_API_KEY=your-service-api-key\n```\n\nThe API key is optional when the reusable service is running on a private network without service authentication.\n\n## Complete example\n\n```js\nimport { FonepayClient } from '@aruntimalsina/fonepay-reusable-client';\n\nconst fonepay = new FonepayClient({\n  baseUrl: process.env.FONEPAY_SERVICE_URL,\n  apiKey: process.env.FONEPAY_SERVICE_API_KEY,\n});\n\n// 1. Create a local payment record first.\nconst reference = `ORDER-${order.id}`;\n\n// 2. Ask the reusable service for a QR payload.\nconst qr = await fonepay.createQr({\n  merchantReference: reference,\n  amount: order.total,\n  currency: 'NPR',\n});\n\n// Return qr.qrMessage to your web or mobile frontend and render it as a QR code.\n\n// 3. Verify from a protected backend endpoint or worker after the customer pays.\nconst payment = await fonepay.verifyPayment({\n  merchantReference: reference,\n  amount: order.total,\n  daysBack: 7,\n});\n\n// 4. Make the local update idempotent.\nif (payment.verified) {\n  await markOrderPaidOnce(order.id, payment.transactionId);\n}\n```\n\n## API\n\n### `new FonepayClient(options)`\n\n| Option | Required | Description |\n|---|---:|---|\n| `baseUrl` | yes | URL of your deployed reusable Fonepay REST service |\n| `apiKey` | no | Internal service key, sent as `X-Internal-Key` |\n| `timeoutMs` | no | Request timeout, default `20000` |\n| `fetchImpl` | no | Custom fetch implementation for tests or runtimes |\n\n### `createQr({ merchantReference, amount, currency })`\n\nReturns a QR payload response:\n\n```json\n{\n  \"qrMessage\": \"...\",\n  \"terminalId\": 123,\n  \"amount\": 250,\n  \"currency\": \"NPR\",\n  \"merchantReference\": \"ORDER-1001\"\n}\n```\n\nPass `qrMessage` to a QR renderer in your own frontend. This package intentionally does not assume React, Vue, React Native, or another UI framework.\n\n### `verifyPayment({ merchantReference, amount, fromDate, toDate, daysBack })`\n\nReturns a normalized verification result:\n\n```json\n{\n  \"verified\": true,\n  \"status\": \"paid\",\n  \"transactionId\": \"FP-123\",\n  \"amount\": 250,\n  \"merchantReference\": \"ORDER-1001\"\n}\n```\n\nOnly mark an order paid when `verified === true`. Store the returned transaction ID and prevent duplicate local updates.\n\n## Error handling\n\n```js\nimport { FonepayApiError } from '@aruntimalsina/fonepay-reusable-client';\n\ntry {\n  const result = await fonepay.verifyPayment({\n    merchantReference: 'ORDER-1001',\n    amount: 250,\n    daysBack: 7,\n  });\n} catch (error) {\n  if (error instanceof FonepayApiError) {\n    console.error(error.code, error.status, error.message);\n  }\n  throw error;\n}\n```\n\nErrors expose `status`, `code`, and optional `details` fields. Common codes include `UNAUTHORIZED`, `INVALID_PAYMENT`, `GATEWAY_UNAVAILABLE`, `NETWORK_ERROR`, `TIMEOUT`, and `REQUEST_FAILED`.\n\n## Recommended payment flow\n\n```text\ncreate local order\n      ↓\nrequest QR from Fonepay service\n      ↓\nshow QR to customer\n      ↓\ncustomer pays with a Fonepay-supported bank or wallet\n      ↓\nverify payment from backend/worker\n      ↓\nmark order paid once and save transaction ID\n```\n\nThe reusable service does not store your orders. Your application owns payment records, order state, retries, and idempotency.\n\n## Security\n\n- Use this package only in trusted server-side code.\n- Never expose `FONEPAY_SERVICE_API_KEY` in browser or mobile bundles.\n- Never put Fonepay merchant credentials in this package or frontend code.\n- Use HTTPS for the reusable service in production.\n- Use a unique merchant reference for each payment.\n- Treat client-side payment success messages as untrusted.\n\n## Other stacks\n\nThe same reusable service also provides SDKs and guides for Python, PHP/Laravel, Java/Spring Boot, Go, .NET, and generic REST clients:\n\nhttps://github.com/dannybyarun/fonepay-reusable\n\n## License\n\nMIT © Arun Timalsina\n","readmeFilename":"README.md","homepage":"https://github.com/dannybyarun/fonepay-reusable/tree/main/packages/javascript#readme","keywords":["fonepay","fonepay-api","fonepay-qr","nepal-payments","nepal-payment-gateway","qr-payment","dynamic-qr","payment-gateway","payment-verification","settlement-verification","digital-payments","nodejs-payments","javascript-payments","express-payments","nextjs-payments"],"repository":{"type":"git","url":"git+https://github.com/dannybyarun/fonepay-reusable.git","directory":"packages/javascript"},"bugs":{"url":"https://github.com/dannybyarun/fonepay-reusable/issues"}}