{"_id":"@ecoleafcom/ppc-bank-sdk","_rev":"4-71b5e63a1d40265463af6ab261701bfd","name":"@ecoleafcom/ppc-bank-sdk","dist-tags":{"latest":"1.0.3"},"versions":{"1.0.0":{"name":"@ecoleafcom/ppc-bank-sdk","version":"1.0.0","author":"","license":"ISC","_id":"@ecoleafcom/ppc-bank-sdk@1.0.0","maintainers":[{"name":"ecoleafcom","email":"cambodia.agricue@gmail.com"}],"dist":{"shasum":"9c874db965b3d7cb48053418197717f484de32d6","tarball":"https://registry.npmjs.org/@ecoleafcom/ppc-bank-sdk/-/ppc-bank-sdk-1.0.0.tgz","fileCount":22,"integrity":"sha512-4nHbwoBIAk3hPOYKNGZlzv4LcIBlPNQsOrwHW6AXsJEx2VqjIXQSk0UdwdmZukQ0BmXTWI4zHFeVdfbI1QvRiw==","signatures":[{"sig":"MEYCIQDbJvH2xUncNJSdmg4mp4z4YItyO5XW9aCyBbMavZIftwIhAKQwI11hopQR2z5hkMPRcSj3xLmn+i0FzBZXhA6TFFgh","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":46343},"main":"dist/index.js","type":"commonjs","types":"dist/index.d.ts","scripts":{"test":"npm run build","build":"tsc","clean":"tsc --build --clean"},"_npmUser":{"name":"ecoleafcom","email":"cambodia.agricue@gmail.com"},"_npmVersion":"11.5.2","description":"A lightweight JavaScript SDK to integrate with PPCBank Open Banking Platform (OBP) and Payment Gateway APIs, enabling seamless access to banking services like payments, balance, transactions, and virtual accounts.","directories":{},"_nodeVersion":"23.10.0","_hasShrinkwrap":false,"devDependencies":{"typescript":"^6.0.3"},"_npmOperationalInternal":{"tmp":"tmp/ppc-bank-sdk_1.0.0_1777874832276_0.9546303787689341","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@ecoleafcom/ppc-bank-sdk","version":"1.0.1","author":"","license":"ISC","_id":"@ecoleafcom/ppc-bank-sdk@1.0.1","maintainers":[{"name":"ecoleafcom","email":"cambodia.agricue@gmail.com"}],"dist":{"shasum":"e1d142e4f95a57237fc2f563e36fbffb9593bfa5","tarball":"https://registry.npmjs.org/@ecoleafcom/ppc-bank-sdk/-/ppc-bank-sdk-1.0.1.tgz","fileCount":22,"integrity":"sha512-oJfbndjx6sa/RzJfbcc6kZ46h5YRJcVHvrhszQUo5GZN4f+PSwVnDpW2nIYW1DA4/xeA5n6cCgiPrB37jzrYkw==","signatures":[{"sig":"MEQCIDxyccJRu9BHH7oVxREfvPX4RX6P6SiXkI5/c/kOEk2CAiAxBXzYBRoq4KCbdkLnl3ZClAVpkgNB7fECLkrR/Oe1hw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":46352},"main":"dist/index.js","type":"commonjs","types":"dist/index.d.ts","scripts":{"test":"npm run build","build":"tsc","clean":"tsc --build --clean"},"_npmUser":{"name":"ecoleafcom","email":"cambodia.agricue@gmail.com"},"_npmVersion":"11.5.2","description":"A lightweight JavaScript SDK to integrate with PPCBank Open Banking Platform (OBP) and Payment Gateway APIs, enabling seamless access to banking services like payments, balance, transactions, and virtual accounts.","directories":{},"_nodeVersion":"23.10.0","_hasShrinkwrap":false,"devDependencies":{"typescript":"^6.0.3"},"_npmOperationalInternal":{"tmp":"tmp/ppc-bank-sdk_1.0.1_1777875106483_0.8113078884873408","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@ecoleafcom/ppc-bank-sdk","version":"1.0.2","author":"","license":"ISC","_id":"@ecoleafcom/ppc-bank-sdk@1.0.2","maintainers":[{"name":"ecoleafcom","email":"cambodia.agricue@gmail.com"}],"dist":{"shasum":"f51cdd96e15397390770c38a5f6298565d3738cc","tarball":"https://registry.npmjs.org/@ecoleafcom/ppc-bank-sdk/-/ppc-bank-sdk-1.0.2.tgz","fileCount":22,"integrity":"sha512-Q2kCY9SMR8sSQoB3KQxTZbz1iShIvejIBxLxoC/LwfC2ri1mf3sK56hvC0dlqXSxMakbvBFEViz91+ho7KP6mg==","signatures":[{"sig":"MEYCIQDOQIV2lPpti9umvIhCyU04PIamE5tYrYyuVWDVp8b5+wIhAISRhYXiZDd5hRlgNnvgaCPLUzCTrvohBaUs35hfUiP/","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":60643},"main":"dist/index.js","type":"commonjs","types":"dist/index.d.ts","scripts":{"test":"npm run build && vitest run","build":"tsc","clean":"tsc --build --clean","test:watch":"vitest"},"_npmUser":{"name":"ecoleafcom","email":"cambodia.agricue@gmail.com"},"_npmVersion":"11.5.2","description":"A lightweight JavaScript SDK to integrate with PPCBank Open Banking Platform (OBP) and Payment Gateway APIs, enabling seamless access to banking services like payments, balance, transactions, and virtual accounts.","directories":{},"_nodeVersion":"23.10.0","_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.5","typescript":"^6.0.3"},"_npmOperationalInternal":{"tmp":"tmp/ppc-bank-sdk_1.0.2_1777877881432_0.4282042655223961","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@ecoleafcom/ppc-bank-sdk","version":"1.0.3","description":"A lightweight JavaScript SDK to integrate with PPCBank Open Banking Platform (OBP) and Payment Gateway APIs, enabling seamless access to banking services like payments, balance, transactions, and virtual accounts.","license":"ISC","author":"","type":"commonjs","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"clean":"tsc --build --clean","test":"npm run build && vitest run","test:watch":"vitest","build":"tsc"},"devDependencies":{"typescript":"^6.0.3","vitest":"^4.1.5"},"_id":"@ecoleafcom/ppc-bank-sdk@1.0.3","gitHead":"d8d45f90ec78a101ebe46315f33083958f7cf64e","_nodeVersion":"23.10.0","_npmVersion":"11.5.2","dist":{"integrity":"sha512-BTHXs+AIRqOAILrvydB8yV6Nc7WHN1NiL4OVri/Pg07ZCPqCtgIs1SiCtmHhpCwfLDeDWPUn+KI2lYZ1Io/kjw==","shasum":"43a99022d17c677942f027ac578418487f773e13","tarball":"https://registry.npmjs.org/@ecoleafcom/ppc-bank-sdk/-/ppc-bank-sdk-1.0.3.tgz","fileCount":22,"unpackedSize":60643,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCiNWIx2Yi9PlyKbKn4bkyjeHG9YqydD3ogogE4fbIGIAIgY2ml0q/lFrThTs/XeIULfc1Kjp3L7koc5KiZj6lKLDQ="}]},"_npmUser":{"name":"ecoleafcom","email":"cambodia.agricue@gmail.com"},"directories":{},"maintainers":[{"name":"ecoleafcom","email":"cambodia.agricue@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ppc-bank-sdk_1.0.3_1777878214029_0.5475158799303774"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-04T06:07:12.171Z","modified":"2026-05-04T07:03:34.284Z","1.0.0":"2026-05-04T06:07:12.419Z","1.0.1":"2026-05-04T06:11:46.630Z","1.0.2":"2026-05-04T06:58:01.584Z","1.0.3":"2026-05-04T07:03:34.183Z"},"license":"ISC","description":"A lightweight JavaScript SDK to integrate with PPCBank Open Banking Platform (OBP) and Payment Gateway APIs, enabling seamless access to banking services like payments, balance, transactions, and virtual accounts.","maintainers":[{"name":"ecoleafcom","email":"cambodia.agricue@gmail.com"}],"readme":"# PPCBank Payment Gateway SDK\n\nTyped JavaScript/TypeScript SDK for PPCBank Payment Gateway bearer-token authentication and the Mayura KHQR payment flow.\n\nThis SDK is based on the PPCB Payment Gateway API Mayura document. It supports:\n\n- `POST /security_check` for bearer-token authentication\n- `POST /api/v1/PMS1011` to generate a KHQR payment URL\n- `POST /api/v1/PMS1014` to generate a raw KHQR string\n- `POST /api/v1/PMS1024` to check KHQR payment status\n- Raw authenticated `get`, `post`, and `request` calls for other PPCBank endpoints\n\n## Install\n\n```bash\nnpm install @ecoleafcom/ppc-bank-sdk\n```\n\n## Environment\n\nCreate an `.env` file in your app:\n\n```env\nNODE_ENV=development\nPPCBANK_BASE_URL=https://paytest.ppcbank.com.kh\nPPCBANK_AUTH_PATH=/security_check\n\nPPCBANK_MERCHANT_CODE=YOUR_MERCHANT_CODE\nPPCBANK_PASSWORD=YOUR_PASSWORD\n\nPPCBANK_GENERATE_KHQR_PAYMENT_URL_PATH=/api/v1/PMS1011\nPPCBANK_GENERATE_KHQR_QR_STRING_PATH=/api/v1/PMS1014\nPPCBANK_CHECK_KHQR_PAYMENT_STATUS_PATH=/api/v1/PMS1024\n```\n\n`NODE_ENV=development` is fine for local development. If `PPCBANK_DEVELOPER_BASE_URL` is not set, the SDK uses `PPCBANK_BASE_URL`. The SDK also accepts `NODE_ENV=developement` for compatibility with the common misspelling.\n\n## Basic Setup\n\n```ts\nimport { PpcBankPaymentGatewaySdk } from \"@ecoleafcom/ppc-bank-sdk\";\n\nconst ppcBank = new PpcBankPaymentGatewaySdk({\n  baseUrl: process.env.PPCBANK_BASE_URL,\n  authPath: process.env.PPCBANK_AUTH_PATH,\n  credentials: {\n    merchantCode: process.env.PPCBANK_MERCHANT_CODE!,\n    password: process.env.PPCBANK_PASSWORD!,\n  },\n});\n```\n\nCommonJS:\n\n```js\nconst { PpcBankPaymentGatewaySdk } = require(\"@ecoleafcom/ppc-bank-sdk\");\n```\n\n## Authenticate\n\n```ts\nconst auth = await ppcBank.authenticate();\n\nconsole.log(auth.token);\nconsole.log(auth.raw);\n```\n\nThe SDK reads PPCBank's documented response shape:\n\n```json\n{\n  \"header\": {\n    \"result\": true,\n    \"resultCode\": \"100000\",\n    \"resultMessage\": \"\"\n  },\n  \"body\": {\n    \"token\": \"JWT_TOKEN\",\n    \"merchantCode\": \"00000174\"\n  }\n}\n```\n\nAuthenticated SDK calls automatically send:\n\n```http\nAuthorization: Bearer <token>\n```\n\n## Generate KHQR Payment URL\n\nUses `POST /api/v1/PMS1011`.\n\n```ts\nconst response = await ppcBank.generateKhqrPaymentUrl({\n  body: {\n    billNumber: \"ORDER-1001\",\n    amount: 1.8,\n    currencyCode: \"USD\",\n    terminalLabel: \"\",\n    mobileNumber: \"\",\n    storeLabel: \"\",\n  },\n});\n\nconsole.log(response.data.body.paymentURL);\n```\n\nThe SDK automatically wraps the request in the PPCBank header/body envelope and fills `merchantCode` from credentials when omitted:\n\n```json\n{\n  \"header\": {\n    \"languageCode\": \"01\",\n    \"channelTypeCode\": \"03\"\n  },\n  \"body\": {\n    \"merchantCode\": \"YOUR_MERCHANT_CODE\",\n    \"billNumber\": \"ORDER-1001\",\n    \"amount\": 1.8,\n    \"currencyCode\": \"USD\"\n  }\n}\n```\n\n## Generate KHQR QR String\n\nUses `POST /api/v1/PMS1014`.\n\n```ts\nconst response = await ppcBank.generateKhqrQrString({\n  body: {\n    billNumber: \"ORDER-1001\",\n    amount: 1.8,\n    currencyCode: \"USD\",\n  },\n});\n\nconsole.log(response.data.body.qrCodeString ?? response.data.body.qrStringCode);\n```\n\n## Check KHQR Payment Status\n\nUses `POST /api/v1/PMS1024`.\n\n```ts\nconst response = await ppcBank.checkKhqrPaymentStatus({\n  body: {\n    billNumber: \"ORDER-1001\",\n  },\n});\n\nconsole.log(response.data.body.resultYN);\nconsole.log(response.data.body.billStatusCode);\nconsole.log(response.data.body.referenceNo);\n```\n\n`resultYN` is documented as:\n\n- `Y`: paid\n- `N`: not yet paid\n\n`billStatusCode` is documented as:\n\n- `01`: success\n- `04`: cancel\n- `05`: refund\n\n## Raw REST Calls\n\nUse `post`, `get`, or `request` for endpoints that are not wrapped by a convenience method.\n\n```ts\nconst response = await ppcBank.post(\"/api/v1/PMS1024\", {\n  header: {\n    languageCode: \"01\",\n    channelTypeCode: \"03\",\n  },\n  body: {\n    merchantCode: process.env.PPCBANK_MERCHANT_CODE!,\n    billNumber: \"ORDER-1001\",\n  },\n});\n\nconsole.log(response.data);\n```\n\n## Configure Endpoint Overrides\n\nDefaults are already set for the Mayura KHQR endpoints. Override them only if PPCBank gives you different paths.\n\n```ts\nconst ppcBank = new PpcBankPaymentGatewaySdk({\n  baseUrl: \"https://paytest.ppcbank.com.kh\",\n  credentials: {\n    merchantCode: \"YOUR_MERCHANT_CODE\",\n    password: \"YOUR_PASSWORD\",\n  },\n  endpoints: {\n    generateKhqrPaymentUrl: \"/api/v1/PMS1011\",\n    generateKhqrQrString: \"/api/v1/PMS1014\",\n    checkKhqrPaymentStatus: \"/api/v1/PMS1024\",\n  },\n});\n```\n\n## Error Handling\n\n```ts\nimport { PpcBankApiError, PpcBankAuthenticationError } from \"@ecoleafcom/ppc-bank-sdk\";\n\ntry {\n  await ppcBank.checkKhqrPaymentStatus({\n    body: {\n      billNumber: \"ORDER-1001\",\n    },\n  });\n} catch (error) {\n  if (error instanceof PpcBankApiError) {\n    console.error(error.status);\n    console.error(error.data);\n  }\n\n  if (error instanceof PpcBankAuthenticationError) {\n    console.error(error.message);\n  }\n\n  throw error;\n}\n```\n\n## Separate Sample Project\n\nThis repository includes a separate consumer project in `test/`.\n\n```bash\ncd test\nnpm install\nnpm start\nnpm run auth\nnpm run payment\nnpm run qr\nnpm run status\nnpm run rest\n```\n\nCommands:\n\n- `npm run auth`: authenticate and print a token preview\n- `npm run payment`: generate a KHQR payment URL with PMS1011\n- `npm run qr`: generate a raw KHQR string with PMS1014\n- `npm run status`: check payment status with PMS1024\n- `npm run rest`: send a raw authenticated POST using `SAMPLE_REST_PATH`\n\n## Notes\n\n- Test base URL from the Mayura PDF: `https://paytest.ppcbank.com.kh`\n- Default auth path: `/security_check`\n- Auth request body: `{ \"merchantCode\": \"...\", \"password\": \"...\" }`\n- Default KHQR request header: `{ \"languageCode\": \"01\", \"channelTypeCode\": \"03\" }`\n- Tokens are stored in the SDK instance after `authenticate()` and are created automatically before authenticated requests when credentials are configured.\n","readmeFilename":"README.md"}