{"id":15295999,"url":"https://github.com/naustudio/vn-payments","last_synced_at":"2025-04-06T10:12:05.633Z","repository":{"id":39333659,"uuid":"117047183","full_name":"naustudio/vn-payments","owner":"naustudio","description":"Various VN Payment Gateways implemented for NodeJS","archived":false,"fork":false,"pushed_at":"2022-12-09T04:52:00.000Z","size":4525,"stargazers_count":135,"open_issues_count":29,"forks_count":40,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-03-30T08:09:37.654Z","etag":null,"topics":["checkout-cart","es6","expressjs","nau-studio","nganluong","nodejs","onepay","payment-gateway","sohapay","vn-payments","vnpay"],"latest_commit_sha":null,"homepage":"http://code.naustud.io/vn-payments","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/naustudio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-01-11T03:50:46.000Z","updated_at":"2025-01-09T09:13:22.000Z","dependencies_parsed_at":"2023-01-25T16:45:07.282Z","dependency_job_id":null,"html_url":"https://github.com/naustudio/vn-payments","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naustudio%2Fvn-payments","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naustudio%2Fvn-payments/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naustudio%2Fvn-payments/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naustudio%2Fvn-payments/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/naustudio","download_url":"https://codeload.github.com/naustudio/vn-payments/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247464223,"owners_count":20942970,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["checkout-cart","es6","expressjs","nau-studio","nganluong","nodejs","onepay","payment-gateway","sohapay","vn-payments","vnpay"],"created_at":"2024-09-30T18:08:54.414Z","updated_at":"2025-04-06T10:12:05.600Z","avatar_url":"https://github.com/naustudio.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vn-payments\n\n[![By Nau Studio](https://img.shields.io/badge/By-Nau%20Studio-977857.svg)](https://naustud.io)\n[![Travis CI build status](https://img.shields.io/travis/naustudio/node-vn-payments.svg)](https://travis-ci.org/naustudio/node-vn-payments/)\n[![Code coverage status](https://img.shields.io/codecov/c/github/naustudio/node-vn-payments.svg)](https://codecov.io/gh/naustudio/node-vn-payments)\n[![npm version](https://img.shields.io/npm/v/vn-payments.svg)](https://www.npmjs.com/package/vn-payments)\n[![GitHub license](https://img.shields.io/github/license/naustudio/node-vn-payments.svg)](https://github.com/naustudio/node-vn-payments/blob/master/LICENSE)\n\nVietnam payment gateway helpers for NodeJS. Check out live demo [here](https://vn-payments-demo.now.sh).\n\n_Thư viện hỗ trợ xây dựng URL tương tác với các cổng thanh toán trực tuyến ở Việt Nam._\n\n\u003e From our experience doing NodeJS e-commerce website in Vietnam, implementing online payment process is often troublesome and error-prone due to strict hashing algorithm and uncertain remote request rejections.\n\u003e Besides, many payment gateways in Vietnam don't have sample code or SDK for server-side JavaScript (yet). Therefore, we have gathered a set of JavaScript classes (written in ES6) that help NodeJS apps exchange data with payment gateways with more confidence and ease by validating payload object and normalize multiple gateways specs into a common API.\n\n## Supported Payment Gateways\n\n_Các cổng thanh toán đang được hỗ trợ_\n\n* [OnePay](http://onepay.com.vn/) (Domestic \u0026 International)\n* [VNPay](https://vnpay.vn/)\n* [SohaPay](https://sohapay.vn/)\n* [NganLuong](https://www.nganluong.vn/nganluong/home.html)\n\n#### Planned gateways:\n\n_Các cổng thanh toán dự định hỗ trợ:_\n\n* 123Pay (chúng tôi chưa có tài liệu tích hợp, [bạn có thể giúp](https://github.com/naustudio/node-vn-payments/blob/master/CONTRIBUTING.md#add-more-payment-gateway)?)\n* ~~AlePay~~ (AlePay chỉ hỗ trợ phương thức recurrent/subscription)\n\n## Install\n\n```sh\n# npm\nnpm install vn-payments --save\n# yarn\nyarn add vn-payments\n```\n\n## Usage\n\n### Payment Workflow:\n\nBelow is sequence diagram of typical payment gateway process:\n\n_Bên dưới là sequence diagram minh họa quy trình thanh toán trực tuyến tiêu biểu:_\n\n![Typical payment gateway process](https://raw.githubusercontent.com/naustudio/node-vn-payments/master/docs/payment-gateway-process.jpg)\n\n\u003cp align=\"center\"\u003e\u003cem\u003eDiagram taken from OnePay Intl documentation\u003c/em\u003e\u003c/p\u003e\n\n**`vn-payments`** provides helper classes that build URL for _DO request_ and verify _DR Response_ for supported payment gateway.\n\nCurrently we haven't implemented the _QueryQR()_ functions. It is in our road map for next release.\n\n_**`vn-payments`** cung cấp các class giúp xây dựng URL với tham số mã hóa để thực hiện \"DO request\" và\ngiúp kiểm tra \"DR Response\" trả về từ cổng thanh toán._\n\n_Hiện tại chúng tôi chưa hiện thực chức năng \"QueryDR\"._\n\n### JavaScript sample code:\n\nImport one of the payment gateway class from `vn-payments`:\n\n_Đầu tiên, import các class hỗ trợ thanh toán:_\n\n```js\n// ESM\nimport { OnePayDomestic } from 'vn-payments';\nimport { OnePayInternational } from 'vn-payments';\nimport { VNPay } from 'vn-payments';\nimport { SohaPay } from 'vn-payments';\nimport { NganLuong } from 'vn-payments';\n// CommonJS\nconst { OnePayDomestic } = require('vn-payments');\nconst { OnePayInternational } = require('vn-payments');\nconst { VNPay } = require('vn-payments');\nconst { SohaPay } = require('vn-payments');\nconst { NganLuong } = require('vn-payments');\n```\n\nInstantiate the helper with merchant configs provided from the payment provider:\n\n_Tiếp theo, khởi tạo instance của các class thanh toán với thông tin thiết lập dành riêng cho merchant\nđược cung cấp bởi cổng thanh toán:_\n\n```js\nconst onepayIntl = new OnePayInternational({\n  paymentGateway: 'https://mtf.onepay.vn/vpcpay/vpcpay.op',\n  merchant: 'TESTONEPAY',\n  accessCode: '6BEB2546',\n  secureSecret: '6D0870CDE5F24F34F3915FB0045120DB',\n});\n```\n\nBuild checkout URL by passing checkout data to **buildCheckoutUrl** method. The checkout data is a structured object and will be validated with **GatewayClass.checkoutSchema** which is an instance of [`simpl-schema`](https://github.com/aldeed/simple-schema-js).\n\nCheckout URL is an instance of so-called [WHATWG URL](https://nodejs.org/api/url.html#url_url), which assist parsing URL string into parts.\n\nThen, redirect client to payment gateway's checkout handler:\n\n_Xây dựng URL chuyển đến cổng thanh toán bằng hàm **buildCheckoutUrl**. Dữ liệu truyền vào là một object có cấu trúc được định nghĩa sẵn bởi thư viện và sẽ được kiểm tra hợp lệ bởi **GatewayClass.checkoutSchema**. Hàm **buildCheckoutUrl** sẽ trả về Promise bất đồng bộ, khi hoàn tất, sẽ trả về một [WHATWG URL](https://nodejs.org/api/url.html#url_url). Sau khi có được URL checkout, redirect trình duyệt của khách qua URL này:_\n\n```js\nroutes.post('/payment/checkout', (req, res) =\u003e {\n  const params = Object.assign({}, req.body);\n\n  // construct checkout payload from form data and app's defaults\n  const checkoutData = {\n    amount: parseInt(params.amount, 10),\n    customerId: params.email,\n    currency: 'VND',\n    /*...*/\n  };\n\n  // buildCheckoutUrl is async operation and will return a Promise\n  onepayIntl\n    .buildCheckoutUrl(checkoutData)\n    .then(checkoutUrl =\u003e {\n      res.writeHead(301, { Location: checkoutUrl.href });\n      res.end();\n    })\n    .catch(err =\u003e {\n      res.send(err);\n    });\n});\n```\n\nFinally, handle payment gateway callback. One of the requirements is that the callback query parameters must be validated with the checksum sent along:\n\n_Cuối cùng, bạn sẽ cần xử lý URL callback từ cổng thanh toán. Một trong các yêu cầu đó là các tham số trong URL query trả về phải được kiểm tra tính hợp lệ với chuỗi mã hóa đính kèm:_\n\n```js\nroutes.get('/payment/callback', (req, res) =\u003e {\n  const query = req.query;\n\n  onepayIntl.verifyReturnUrl(query).then(results =\u003e {\n    if (results.isSucceed) {\n      res.render('success', {\n        title: 'Nau Store - Thank You',\n        orderId: results.orderId,\n        price: results.price,\n        message: results.message,\n      });\n    } else {\n      res.render('errors', {\n        title: 'Nau Store - Payment Errors',\n        message: results.message,\n      });\n    }\n  });\n});\n```\n\nFor **IPN Request** to Website's Back End from Gateway server, implement another route handler according Gateway documentation and use the `verifyReturnUrl` to validate parameters sent from Gateway.\n\n_Về việc xử lý **IPN Request** gửi trực tiếp đến backend của trang bán hàng, bạn cần hiện thực một route handler theo tài liệu hướng dẫn của cổng thanh toán và sử dụng lại hàm `verifyReturnUrl` để kiểm tra tính hợp lệ của request gửi từ cổng thanh toán._\n\n## Example ([Live Demo](https://vn-payments-demo.now.sh))\n\nSee the Express checkout cart in the **example** folder.\n\n#### Example Getting Started:\n\n* Clone this repository.\n* Run `npm install` in `example` folder\n* Inside `example` folder, execute: `npm start`\n\n#### Test cards for testing out example:\n\nSee testing cards info in [CONTRIBUTING.md](https://github.com/naustudio/node-vn-payments/blob/master/CONTRIBUTING.md#testing-cards-for-payment-tests)\n\n## API Document\n\nSee [documentation](http://code.naustud.io/node-vn-payments).\n\n## Contributing\n\nInterested in contributing to this project? See [CONTRIBUTING.md](https://github.com/naustudio/node-vn-payments/blob/master/CONTRIBUTING.md)\n\n## Road Map\n\n* [x] Implement `buildCheckoutUrl` (A.K.A. `DO Request`) for OnePay, VNPay, SohaPay, NganLuong\n* [x] Implement `verifyReturnUrl` (A.K.A. `DR Response`) for OnePay, VNPay, SohaPay, NganLuong\n* [ ] Implement `queryDR` methods for existing gateways\n* [ ] Implement helper class for **AlePay**\n* [ ] Implement helper class for **123Pay**\n\n## FAQ\n\n[TBC]\n\n## Thanks\n\n* [Express starter kit](https://github.com/vmasto/express-babel) for the checkout cart example.\n* Vietnam payment gateway's developers who worked with Nau Studio in preliminary projects that allows us make sure this code work.\n\n## License\n\nCopyright 2019 Nau Studio \u003chttps://naustud.io\u003e\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnaustudio%2Fvn-payments","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnaustudio%2Fvn-payments","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnaustudio%2Fvn-payments/lists"}