{"_id":"@alsharie/kuraimiepay","_rev":"3-4f3c7e1a3a9e04e1a4ba74d5c5202f39","name":"@alsharie/kuraimiepay","dist-tags":{"latest":"1.0.6"},"versions":{"1.0.4":{"name":"@alsharie/kuraimiepay","version":"1.0.4","keywords":["kuraimi","epay","payment","gateway","sdk","bank","fintech","typescript","alsharie"],"author":{"name":"abdulrahman alsharie"},"license":"MIT","_id":"@alsharie/kuraimiepay@1.0.4","maintainers":[{"name":"alsharie","email":"abdulrahman.alsharie@gmail.com"}],"homepage":"https://github.com/alsharie/kuraimiepay#readme","bugs":{"url":"https://github.com/alsharie/kuraimiepay/issues"},"dist":{"shasum":"fbfdee6a1758dd4db8be599bef0dce7d356efeb4","tarball":"https://registry.npmjs.org/@alsharie/kuraimiepay/-/kuraimiepay-1.0.4.tgz","fileCount":4,"integrity":"sha512-KVUpKy6JidV3x07W8wmn2UDNNmM2nJQNANE2/rXKp7jT7H/xWjGtM+f7BixexS+dQM0KG3jLkNMhiNPx2z7kzQ==","signatures":[{"sig":"MEQCICRkfwK0B9sEYylTx1S3mFLolA9dWKFKKBpCImaaNcbRAiBFL0EdOb0EF0eElnnycFQpG6EyRMgf1vXyWr3xecKy7Q==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":13539},"main":"dist/KuraimiEPayClient.js","types":"dist/KuraimiEPayClient.d.ts","gitHead":"4ba209dfe6ed2462b82920486e5f261c611582c0","scripts":{"test":"echo \"Error: no test specified\" && exit 1","build":"tsc","clean":"rm -rf dist","prepublishOnly":"npm run build","example:payment":"ts-node src/examples/sendPayment.ts","example:reversal":"ts-node src/examples/reversePayment.ts"},"_npmUser":{"name":"alsharie","email":"abdulrahman.alsharie@gmail.com"},"repository":{"url":"git+https://github.com/alsharie/kuraimiepay.git","type":"git"},"_npmVersion":"11.3.0","description":"TypeScript Node.js SDK for integrating with Kuraimi Bank E-Pay API for suppliers.","directories":{},"_nodeVersion":"22.11.0","dependencies":{"axios":"^1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"ts-node":"^10.9.0","typescript":"^5.0.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/kuraimiepay_1.0.4_1747126475721_0.5315378684902192","host":"s3://npm-registry-packages-npm-production"}},"1.0.5":{"name":"@alsharie/kuraimiepay","version":"1.0.5","keywords":["kuraimi","epay","payment","gateway","sdk","bank","fintech","typescript","alsharie"],"author":{"name":"abdulrahman alsharie"},"license":"MIT","_id":"@alsharie/kuraimiepay@1.0.5","maintainers":[{"name":"alsharie","email":"abdulrahman.alsharie@gmail.com"}],"homepage":"https://github.com/alsharie/kuraimiepay#readme","bugs":{"url":"https://github.com/alsharie/kuraimiepay/issues"},"dist":{"shasum":"1c782d8406c3eecc8bd7f7092927166636c4f3ae","tarball":"https://registry.npmjs.org/@alsharie/kuraimiepay/-/kuraimiepay-1.0.5.tgz","fileCount":4,"integrity":"sha512-4LejdpowRbuaAd1U6bLz8tK6SysEUYSbjje1XC1lQDEZuryo8QfT7+CQTuyZzWpGXiWl3R4qLNYX77KJG4zbsA==","signatures":[{"sig":"MEQCIBqnLBt2vEtSbLzuuhd3mE2kNu88RyoNh0oShUyhndZZAiBLUbWWkgI/iuw7iG0aMRaWVlcTXHmbzLTJJ/3UDQZsrQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":15833},"main":"dist/KuraimiEPayClient.js","types":"dist/KuraimiEPayClient.d.ts","gitHead":"62e154e081108291036d28d36e89836a1d214f46","scripts":{"test":"echo \"Error: no test specified\" && exit 1","build":"tsc","clean":"rm -rf dist","prepublishOnly":"npm run build","example:payment":"ts-node src/examples/sendPayment.ts","example:reversal":"ts-node src/examples/reversePayment.ts"},"_npmUser":{"name":"alsharie","email":"abdulrahman.alsharie@gmail.com"},"repository":{"url":"git+https://github.com/alsharie/kuraimiepay.git","type":"git"},"_npmVersion":"11.3.0","description":"TypeScript Node.js SDK for integrating with Kuraimi Bank E-Pay API for suppliers.","directories":{},"_nodeVersion":"22.11.0","dependencies":{"axios":"^1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"ts-node":"^10.9.0","typescript":"^5.0.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/kuraimiepay_1.0.5_1748243066134_0.23411611239202168","host":"s3://npm-registry-packages-npm-production"}},"1.0.6":{"name":"@alsharie/kuraimiepay","version":"1.0.6","description":"TypeScript Node.js SDK for integrating with Kuraimi Bank E-Pay API for suppliers.","main":"dist/KuraimiEPayClient.js","types":"dist/KuraimiEPayClient.d.ts","scripts":{"build":"tsc","prepublishOnly":"npm run build","test":"echo \"Error: no test specified\" && exit 1","example:payment":"ts-node src/examples/sendPayment.ts","example:reversal":"ts-node src/examples/reversePayment.ts","clean":"rm -rf dist"},"keywords":["kuraimi","epay","payment","gateway","sdk","bank","fintech","typescript","alsharie"],"author":{"name":"abdulrahman alsharie"},"license":"MIT","dependencies":{"axios":"^1.0.0"},"devDependencies":{"@types/node":"^20.0.0","ts-node":"^10.9.0","typescript":"^5.0.0"},"repository":{"type":"git","url":"git+https://github.com/alsharie/kuraimiepay.git"},"homepage":"https://github.com/alsharie/kuraimiepay#readme","publishConfig":{"access":"public"},"_id":"@alsharie/kuraimiepay@1.0.6","gitHead":"9ca6071926e159add04fa6d711ea3a245e52841b","bugs":{"url":"https://github.com/alsharie/kuraimiepay/issues"},"_nodeVersion":"22.11.0","_npmVersion":"11.3.0","dist":{"integrity":"sha512-NZNCFiWcxcfjnzrUNweBGlMoDwNxtoaihji74lARxG56jOP+fEQsas/4XB+HA/l5jmxi8PrcLLMOjbfRnb1Q6g==","shasum":"534423f86e04a9009a38f702a74daa2e3591dd8a","tarball":"https://registry.npmjs.org/@alsharie/kuraimiepay/-/kuraimiepay-1.0.6.tgz","fileCount":4,"unpackedSize":15833,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDPoOke47XS5W2u/ntQvP+QoSjpt/sTKXiCXlg0CgmVFQIgD+fAICOIAbzWqQMBC5UZCMvI4wIy93xopwSFzQ7p+Ds="}]},"_npmUser":{"name":"alsharie","email":"abdulrahman.alsharie@gmail.com"},"directories":{},"maintainers":[{"name":"alsharie","email":"abdulrahman.alsharie@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/kuraimiepay_1.0.6_1748250440031_0.44637650439153975"},"_hasShrinkwrap":false}},"time":{"created":"2025-05-13T08:54:35.627Z","modified":"2025-05-26T09:07:20.378Z","1.0.4":"2025-05-13T08:54:35.874Z","1.0.5":"2025-05-26T07:04:26.308Z","1.0.6":"2025-05-26T09:07:20.206Z"},"bugs":{"url":"https://github.com/alsharie/kuraimiepay/issues"},"author":{"name":"abdulrahman alsharie"},"license":"MIT","homepage":"https://github.com/alsharie/kuraimiepay#readme","keywords":["kuraimi","epay","payment","gateway","sdk","bank","fintech","typescript","alsharie"],"repository":{"type":"git","url":"git+https://github.com/alsharie/kuraimiepay.git"},"description":"TypeScript Node.js SDK for integrating with Kuraimi Bank E-Pay API for suppliers.","maintainers":[{"name":"alsharie","email":"abdulrahman.alsharie@gmail.com"}],"readme":"# Kuraimi Bank E-Pay SDK for Node.js (TypeScript)\r\n\r\nA TypeScript Node.js client library for integrating with the Kuraimi Bank E-Pay API.\r\n\r\nThis SDK helps you (the Supplier) call Kuraimi Bank's APIs for E-Payment and Reversals.\r\n\r\n\r\n\r\n## ❗ Crucial Pre-Integration Step: Supplier's Web API\r\n\r\n**Before you can successfully use the E-Payment features facilitated by this SDK (and by Kuraimi Bank's system), your system MUST expose a \"Verify Customer details API\".**\r\n\r\nAs per Section 13 of the \"Supplier Integration Guide and Technical Specification\":\r\n\r\n*   **Purpose:** Kuraimi Bank's E-Pay system will call this API (hosted by you, the supplier) to verify customer details registered on your platform.\r\n*   **Your Responsibility:**\r\n    1.  You need to develop and host an HTTP POST endpoint.\r\n    2.  This endpoint will receive customer details (e.g., `SCustID`, `MobileNo`, `Email`, `CustomerZone`) from Kuraimi Bank.\r\n    3.  Your API must validate these details against your customer database.\r\n    4.  Your API must respond in the format specified in the Kuraimi Bank documentation , including a `Code` (\"1\" for success, others for failure) and the `SCustID` if verified.\r\n    5.  You must provide Kuraimi Bank with:\r\n        *   The URL (Endpoint) for both UAT and Production environments.\r\n        *   Username and Password for Basic Authentication that Kuraimi Bank will use to call your API.\r\n*   **Impact:** If this supplier-hosted API is not implemented, not reachable, or does not function correctly, customer verification will fail, and subsequent E-Payment transactions initiated via Kuraimi Bank's applications (KJ, Mfloos) for your services may not be possible.\r\n\r\n**This SDK (`@alsharie/kuraimiepay`) helps you call Kuraimi Bank's APIs. It does NOT implement the API that Kuraimi Bank calls on your system.** Ensure this separate integration requirement is met with Kuraimi Bank.\r\n\r\n## Features (of this SDK)\r\n\r\n*   Easy-to-use client for E-Payment and Reversal transactions (calling Kuraimi Bank).\r\n*   Strongly typed interfaces for requests and responses.\r\n*   Handles Basic Authentication for calls *to* Kuraimi Bank.\r\n*   Automatic Base64 encoding for `PINPASS`.\r\n*   Configurable for UAT and Production environments.\r\n*   Uses `axios` for HTTP requests.\r\n*   Written in TypeScript, compiled to JavaScript.\r\n\r\n## Prerequisites (for using this SDK)\r\n\r\n*   **Completion of the \"Supplier's Web API\" integration (see section above).**\r\n*   Node.js (v14 or higher recommended)\r\n*   TypeScript (v4.5 or higher recommended)\r\n*   API Credentials (Username and Password) for *your supplier account* to call Kuraimi Bank's E-Pay APIs (provided by Kuraimi Bank).\r\n*   UAT and Production Base URLs for Kuraimi Bank's E-Pay APIs. The UAT URL is included based on the document; the Production URL will need to be supplied during client initialization.\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install @alsharie/kuraimiepay\r\n# or\r\nyarn add @alsharie/kuraimiepay\r\n```\r\n\r\n## Usage\r\n\r\n### 1. Initialize the Client\r\n\r\n```typescript\r\nimport KuraimiEPayClient from '@alsharie/kuraimiepay';\r\n\r\nconst apiClient = new KuraimiEPayClient({\r\n    username: 'YOUR_SUPPLIER_USERNAME', // Provided by Kuraimi Bank\r\n    password: 'YOUR_SUPPLIER_PASSWORD', // Provided by Kuraimi Bank\r\n    environment: 'UAT', // 'UAT' or 'PROD'\r\n    // baseUrl: 'https://your-custom-or-prod-base-url.com' // Optional: if PROD URL is known or to override default\r\n});\r\n```\r\n\r\n### 2. Send an E-Payment Transaction\r\n\r\n```typescript\r\nasync function makePayment() {\r\n    const paymentDetails: SendPaymentPayload = {\r\n        SCustID: 'SCUST98765',\r\n        REFNO: `TS_PAY${Date.now()}`, // Ensure this is unique\r\n        AMOUNT: 150.75,\r\n        MRCHNTNAME: 'My Online Store TS',\r\n        PINPASS: '1234', // Customer's PIN\r\n    };\r\n\r\n    try {\r\n        const response: ApiResponse = await apiClient.sendPayment(paymentDetails);\r\n        console.log('Payment Response:', response);\r\n\r\n        if (response.CODE === 1 && response.ResultSet?.PH_REF_NO) {\r\n            console.log('Payment successful! Bank Ref:', response.ResultSet.PH_REF_NO);\r\n        } else {\r\n            console.error(`Payment failed: ${response.MESSAGE} (Code: ${response.CODE})`);\r\n        }\r\n    } catch (error) {\r\n        const apiError = error as ApiError;\r\n        console.error('Error during payment:', apiError.data || apiError.message || apiError);\r\n        if (apiError.statusCode) console.error('Status Code:', apiError.statusCode);\r\n    }\r\n}\r\n\r\nmakePayment();\r\n```\r\n\r\n### 3. Reverse an E-Payment Transaction\r\n\r\n```typescript\r\nimport { ReversePaymentPayload } from '@alsharie/kuraimiepay'; // Import additional types as needed\r\n\r\nasync function reverseExistingPayment() {\r\n    const reversalDetails: ReversePaymentPayload = {\r\n        SCustID: 'SCUST98765',\r\n        REFNO: 'TS_PAY1678886660000', // The REFNO of the transaction you want to reverse\r\n    };\r\n\r\n    try {\r\n        const response: ApiResponse = await apiClient.reversePayment(reversalDetails);\r\n        console.log('Reversal Response:', response);\r\n\r\n        if (response.CODE === 1) {\r\n            console.log('Reversal request processed successfully.');\r\n        } else {\r\n            console.error(`Reversal failed: ${response.MESSAGE} (Code: ${response.CODE})`);\r\n        }\r\n    } catch (error) {\r\n        const apiError = error as ApiError;\r\n        console.error('Error during reversal:', apiError.data || apiError.message || apiError);\r\n        if (apiError.statusCode) console.error('Status Code:', apiError.statusCode);\r\n    }\r\n}\r\n\r\nreverseExistingPayment();\r\n```\r\n\r\n## API Reference (Types)\r\n\r\nKey types are exported from the main module:\r\n*   `KuraimiEPayClientOptions`\r\n*   `SendPaymentPayload`\r\n*   `ReversePaymentPayload`\r\n*   `ApiResponse<T = ResultSet | null>`\r\n*   `ApiError`\r\n*   `ResultSet`\r\n\r\nRefer to the source code in `src/index.ts` for detailed type definitions.\r\n\r\n## Error Handling\r\n\r\nThe SDK methods return Promises. If an API call fails or a network error occurs, the Promise will be rejected with an `ApiError` object. This object typically includes:\r\n*   `message` (string): A summary of the error.\r\n*   `statusCode` (number, optional): The HTTP status code, if available.\r\n*   `data` (ApiErrorResponseData, optional): The response body from the API, if available (this usually contains `CODE`, `MESSAGE`, `MESSAGEDESC` from Kuraimi Bank).\r\n*   `originalError` (AxiosError | Error, optional): The underlying error object.\r\n\r\nAlways wrap API calls in `try...catch` blocks.\r\n\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please open an issue or submit a pull request.\r\n\r\n## License\r\n\r\nMIT","readmeFilename":"readme.md"}