| Name | vietnam-qr-pay JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | None |
| Summary | Python library for encoding/decoding Vietnamese bank QR codes (VietQR, VNPayQR) |
| upload_time | 2025-07-31 03:45:44 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
vietqr
vnpay
qr
vietnam
payment
banking
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Vietnam QR Pay - Python
Python library for encoding/decoding QR codes for Vietnamese banks, supporting VietQR (bank transfer QR) and VNPayQR standards, as well as multi-purpose QR codes for e-wallets like MoMo and ZaloPay.
This is the Python version of the vietnam-qr-pay library, separated from the original TypeScript/JavaScript implementation.
## Features
- ✅ Decode VietQR and VNPay QR codes
- ✅ Create static QR codes (no amount specified)
- ✅ Create dynamic QR codes (with amount)
- ✅ Support for 60+ Vietnamese banks
- ✅ E-wallet QR support (MoMo, ZaloPay via VietQR)
- ✅ CRC16 checksum validation
- ✅ Fully typed with Python type hints
## Installation
```bash
pip install vietnam-qr-pay
```
Or using uv:
```bash
uv add vietnam-qr-pay
```
## Quick Start
### Decode a QR Code
```python
from vietnam_qr_pay import QRPay
# Decode a VietQR code
qr_content = "00020101021238530010A0000007270123000697041601092576788590208QRIBFTTA5303704540410005802VN62150811Chuyen tien6304BBB8"
qr_pay = QRPay(qr_content)
print(qr_pay.is_valid) # True
print(qr_pay.provider.name) # QRProvider.VIETQR
print(qr_pay.consumer.bank_bin) # 970416
print(qr_pay.consumer.bank_number) # 257678859
print(qr_pay.amount) # 1000
print(qr_pay.additional_data.purpose) # Chuyen tien
```
### Create a Static VietQR (No Amount)
```python
from vietnam_qr_pay import QRPay, BanksObject
# Create QR for ACB bank account
qr_pay = QRPay.init_viet_qr(
bank_bin=BanksObject["acb"].bin,
bank_number="257678859"
)
content = qr_pay.build()
print(content)
# 00020101021138530010A0000007270123000697041601092576788590208QRIBFTTA53037045802VN6304AE9F
```
### Create a Dynamic VietQR (With Amount)
```python
from vietnam_qr_pay import QRPay, BanksObject
qr_pay = QRPay.init_viet_qr(
bank_bin=BanksObject["vietcombank"].bin,
bank_number="1234567890",
amount="100000",
purpose="Thanh toan don hang"
)
content = qr_pay.build()
```
### Create a VNPay QR Code
```python
from vietnam_qr_pay import QRPay
qr_pay = QRPay.init_vnpay_qr(
merchant_id="0102154778",
merchant_name="TUGIACOMPANY",
store="TU GIA COMPUTER",
terminal="TUGIACO1"
)
content = qr_pay.build()
```
## E-Wallet Support
### MoMo QR Code
```python
from vietnam_qr_pay import QRPay, BanksObject
# MoMo account number from the app
account_number = "99MM24011M34875080"
momo_qr = QRPay.init_viet_qr(
bank_bin=BanksObject["banviet"].bin,
bank_number=account_number,
amount="50000", # Optional
purpose="Chuyen tien" # Optional
)
# Add MoMo specific reference
momo_qr.additional_data.reference = "MOMOW2W" + account_number[10:]
# Add phone number's last 3 digits
momo_qr.set_unreserved_field("80", "046")
content = momo_qr.build()
```
### ZaloPay QR Code
```python
from vietnam_qr_pay import QRPay, BanksObject
# ZaloPay account number from the app
account_number = "99ZP24009M07248267"
zalopay_qr = QRPay.init_viet_qr(
bank_bin=BanksObject["banviet"].bin,
bank_number=account_number,
amount="100000", # Optional
purpose="Thanh toan" # Optional
)
content = zalopay_qr.build()
```
## Working with Banks
### List All Supported Banks
```python
from vietnam_qr_pay import BanksObject, VietQRStatus
# Get all banks
all_banks = BanksObject.values()
# Get banks supporting VietQR transfers
transfer_banks = [
bank for bank in BanksObject.values()
if bank.viet_qr_status == VietQRStatus.TRANSFER_SUPPORTED
]
# Access specific bank info
vietcombank = BanksObject["vietcombank"]
print(vietcombank.name) # Ngân hàng TMCP Ngoại Thương Việt Nam
print(vietcombank.short_name) # Vietcombank
print(vietcombank.bin) # 970436
```
### Bank Object Properties
```python
from vietnam_qr_pay import BanksObject
bank = BanksObject["acb"]
print(bank.key) # BankKey.ACB
print(bank.code) # BankCode.ACB
print(bank.name) # Ngân hàng TMCP Á Châu
print(bank.short_name) # ACB
print(bank.bin) # 970416
print(bank.swift_code) # ASCBVNVX
print(bank.viet_qr_status) # VietQRStatus.TRANSFER_SUPPORTED
```
## Advanced Usage
### Modify and Rebuild QR
```python
# Parse existing QR
qr_pay = QRPay(qr_content)
# Modify fields
qr_pay.amount = "999999"
qr_pay.additional_data.purpose = "Updated purpose"
# Rebuild QR
new_content = qr_pay.build()
```
### Custom Fields
```python
# Set unreserved fields (80-99)
qr_pay.set_unreserved_field("85", "custom_value")
# Set EMVCo fields (65-79)
qr_pay.set_evm_co_field("70", "emv_value")
```
## API Reference
### QRPay Class
```python
class QRPay:
# Properties
is_valid: bool
version: str
init_method: str # "11" = static, "12" = dynamic
provider: Provider
merchant: Merchant
consumer: Consumer
amount: Optional[str]
currency: str # "704" for VND
nation: str # "VN"
additional_data: AdditionalData
crc: str
# Methods
def __init__(content: Optional[str] = None)
def parse(content: str) -> None
def build() -> str
# Class methods
@classmethod
def init_viet_qr(...) -> QRPay
@classmethod
def init_vnpay_qr(...) -> QRPay
```
### Bank Properties
```python
@dataclass
class Bank:
key: BankKey
code: BankCode
name: str
short_name: str
bin: str
viet_qr_status: VietQRStatus
lookup_supported: Optional[int]
swift_code: Optional[str]
keywords: Optional[str]
deprecated: Optional[bool]
```
## Testing
Run tests using pytest:
```bash
uv run pytest
```
## License
MIT License - see LICENSE file for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Credits
This is a Python port of the original [vietnam-qr-pay](https://github.com/xuannghia/vietnam-qr-pay) JavaScript library.
Raw data
{
"_id": null,
"home_page": null,
"name": "vietnam-qr-pay",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "vietqr, vnpay, qr, vietnam, payment, banking",
"author": null,
"author_email": "Vietnam QR Pay Contributors <me@bangprovn.com>",
"download_url": "https://files.pythonhosted.org/packages/99/ca/77adbfc3f6f39e9d355542ee32f5fd4a4b6ab3eda2e881b6636ee31ab23c/vietnam_qr_pay-1.0.0.tar.gz",
"platform": null,
"description": "# Vietnam QR Pay - Python\n\nPython library for encoding/decoding QR codes for Vietnamese banks, supporting VietQR (bank transfer QR) and VNPayQR standards, as well as multi-purpose QR codes for e-wallets like MoMo and ZaloPay.\n\nThis is the Python version of the vietnam-qr-pay library, separated from the original TypeScript/JavaScript implementation.\n\n## Features\n\n- \u2705 Decode VietQR and VNPay QR codes\n- \u2705 Create static QR codes (no amount specified)\n- \u2705 Create dynamic QR codes (with amount)\n- \u2705 Support for 60+ Vietnamese banks\n- \u2705 E-wallet QR support (MoMo, ZaloPay via VietQR)\n- \u2705 CRC16 checksum validation\n- \u2705 Fully typed with Python type hints\n\n## Installation\n\n```bash\npip install vietnam-qr-pay\n```\n\nOr using uv:\n\n```bash\nuv add vietnam-qr-pay\n```\n\n## Quick Start\n\n### Decode a QR Code\n\n```python\nfrom vietnam_qr_pay import QRPay\n\n# Decode a VietQR code\nqr_content = \"00020101021238530010A0000007270123000697041601092576788590208QRIBFTTA5303704540410005802VN62150811Chuyen tien6304BBB8\"\nqr_pay = QRPay(qr_content)\n\nprint(qr_pay.is_valid) # True\nprint(qr_pay.provider.name) # QRProvider.VIETQR\nprint(qr_pay.consumer.bank_bin) # 970416\nprint(qr_pay.consumer.bank_number) # 257678859\nprint(qr_pay.amount) # 1000\nprint(qr_pay.additional_data.purpose) # Chuyen tien\n```\n\n### Create a Static VietQR (No Amount)\n\n```python\nfrom vietnam_qr_pay import QRPay, BanksObject\n\n# Create QR for ACB bank account\nqr_pay = QRPay.init_viet_qr(\n bank_bin=BanksObject[\"acb\"].bin,\n bank_number=\"257678859\"\n)\ncontent = qr_pay.build()\nprint(content)\n# 00020101021138530010A0000007270123000697041601092576788590208QRIBFTTA53037045802VN6304AE9F\n```\n\n### Create a Dynamic VietQR (With Amount)\n\n```python\nfrom vietnam_qr_pay import QRPay, BanksObject\n\nqr_pay = QRPay.init_viet_qr(\n bank_bin=BanksObject[\"vietcombank\"].bin,\n bank_number=\"1234567890\",\n amount=\"100000\",\n purpose=\"Thanh toan don hang\"\n)\ncontent = qr_pay.build()\n```\n\n### Create a VNPay QR Code\n\n```python\nfrom vietnam_qr_pay import QRPay\n\nqr_pay = QRPay.init_vnpay_qr(\n merchant_id=\"0102154778\",\n merchant_name=\"TUGIACOMPANY\",\n store=\"TU GIA COMPUTER\",\n terminal=\"TUGIACO1\"\n)\ncontent = qr_pay.build()\n```\n\n## E-Wallet Support\n\n### MoMo QR Code\n\n```python\nfrom vietnam_qr_pay import QRPay, BanksObject\n\n# MoMo account number from the app\naccount_number = \"99MM24011M34875080\"\n\nmomo_qr = QRPay.init_viet_qr(\n bank_bin=BanksObject[\"banviet\"].bin,\n bank_number=account_number,\n amount=\"50000\", # Optional\n purpose=\"Chuyen tien\" # Optional\n)\n\n# Add MoMo specific reference\nmomo_qr.additional_data.reference = \"MOMOW2W\" + account_number[10:]\n\n# Add phone number's last 3 digits\nmomo_qr.set_unreserved_field(\"80\", \"046\")\n\ncontent = momo_qr.build()\n```\n\n### ZaloPay QR Code\n\n```python\nfrom vietnam_qr_pay import QRPay, BanksObject\n\n# ZaloPay account number from the app\naccount_number = \"99ZP24009M07248267\"\n\nzalopay_qr = QRPay.init_viet_qr(\n bank_bin=BanksObject[\"banviet\"].bin,\n bank_number=account_number,\n amount=\"100000\", # Optional\n purpose=\"Thanh toan\" # Optional\n)\n\ncontent = zalopay_qr.build()\n```\n\n## Working with Banks\n\n### List All Supported Banks\n\n```python\nfrom vietnam_qr_pay import BanksObject, VietQRStatus\n\n# Get all banks\nall_banks = BanksObject.values()\n\n# Get banks supporting VietQR transfers\ntransfer_banks = [\n bank for bank in BanksObject.values() \n if bank.viet_qr_status == VietQRStatus.TRANSFER_SUPPORTED\n]\n\n# Access specific bank info\nvietcombank = BanksObject[\"vietcombank\"]\nprint(vietcombank.name) # Ng\u00e2n h\u00e0ng TMCP Ngo\u1ea1i Th\u01b0\u01a1ng Vi\u1ec7t Nam\nprint(vietcombank.short_name) # Vietcombank\nprint(vietcombank.bin) # 970436\n```\n\n### Bank Object Properties\n\n```python\nfrom vietnam_qr_pay import BanksObject\n\nbank = BanksObject[\"acb\"]\nprint(bank.key) # BankKey.ACB\nprint(bank.code) # BankCode.ACB\nprint(bank.name) # Ng\u00e2n h\u00e0ng TMCP \u00c1 Ch\u00e2u\nprint(bank.short_name) # ACB\nprint(bank.bin) # 970416\nprint(bank.swift_code) # ASCBVNVX\nprint(bank.viet_qr_status) # VietQRStatus.TRANSFER_SUPPORTED\n```\n\n## Advanced Usage\n\n### Modify and Rebuild QR\n\n```python\n# Parse existing QR\nqr_pay = QRPay(qr_content)\n\n# Modify fields\nqr_pay.amount = \"999999\"\nqr_pay.additional_data.purpose = \"Updated purpose\"\n\n# Rebuild QR\nnew_content = qr_pay.build()\n```\n\n### Custom Fields\n\n```python\n# Set unreserved fields (80-99)\nqr_pay.set_unreserved_field(\"85\", \"custom_value\")\n\n# Set EMVCo fields (65-79)\nqr_pay.set_evm_co_field(\"70\", \"emv_value\")\n```\n\n## API Reference\n\n### QRPay Class\n\n```python\nclass QRPay:\n # Properties\n is_valid: bool\n version: str\n init_method: str # \"11\" = static, \"12\" = dynamic\n provider: Provider\n merchant: Merchant\n consumer: Consumer\n amount: Optional[str]\n currency: str # \"704\" for VND\n nation: str # \"VN\"\n additional_data: AdditionalData\n crc: str\n \n # Methods\n def __init__(content: Optional[str] = None)\n def parse(content: str) -> None\n def build() -> str\n \n # Class methods\n @classmethod\n def init_viet_qr(...) -> QRPay\n @classmethod\n def init_vnpay_qr(...) -> QRPay\n```\n\n### Bank Properties\n\n```python\n@dataclass\nclass Bank:\n key: BankKey\n code: BankCode\n name: str\n short_name: str\n bin: str\n viet_qr_status: VietQRStatus\n lookup_supported: Optional[int]\n swift_code: Optional[str]\n keywords: Optional[str]\n deprecated: Optional[bool]\n```\n\n## Testing\n\nRun tests using pytest:\n\n```bash\nuv run pytest\n```\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Credits\n\nThis is a Python port of the original [vietnam-qr-pay](https://github.com/xuannghia/vietnam-qr-pay) JavaScript library.\n",
"bugtrack_url": null,
"license": null,
"summary": "Python library for encoding/decoding Vietnamese bank QR codes (VietQR, VNPayQR)",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/bangprovn/vietnam-qr-pay-python/issues",
"Homepage": "https://github.com/bangprovn/vietnam-qr-pay-python",
"Repository": "https://github.com/bangprovn/vietnam-qr-pay-python"
},
"split_keywords": [
"vietqr",
" vnpay",
" qr",
" vietnam",
" payment",
" banking"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "bb37fc796e30f07e9d4e3a16e8c96fa02b7e0896ab45ca3f6bb56dca2e19e7a0",
"md5": "56a37b7693f97eb1ebea987af5ba4f33",
"sha256": "100b736f9eae929a1ed47432728c58c7c8370dfeb427ecabf424f25d7b2d28cb"
},
"downloads": -1,
"filename": "vietnam_qr_pay-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "56a37b7693f97eb1ebea987af5ba4f33",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 15596,
"upload_time": "2025-07-31T03:45:42",
"upload_time_iso_8601": "2025-07-31T03:45:42.570276Z",
"url": "https://files.pythonhosted.org/packages/bb/37/fc796e30f07e9d4e3a16e8c96fa02b7e0896ab45ca3f6bb56dca2e19e7a0/vietnam_qr_pay-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "99ca77adbfc3f6f39e9d355542ee32f5fd4a4b6ab3eda2e881b6636ee31ab23c",
"md5": "796816ee039ac08ba38720f70a0ecca7",
"sha256": "88c06634772d27a1d0df49b29e38eaec0476e1eda6646108142d4291bd40d546"
},
"downloads": -1,
"filename": "vietnam_qr_pay-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "796816ee039ac08ba38720f70a0ecca7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 17581,
"upload_time": "2025-07-31T03:45:44",
"upload_time_iso_8601": "2025-07-31T03:45:44.041042Z",
"url": "https://files.pythonhosted.org/packages/99/ca/77adbfc3f6f39e9d355542ee32f5fd4a4b6ab3eda2e881b6636ee31ab23c/vietnam_qr_pay-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-31 03:45:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bangprovn",
"github_project": "vietnam-qr-pay-python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "vietnam-qr-pay"
}
