rpay-sdk 1.0.0__tar.gz

rpay_sdk-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RPAY (https://rpay.vn)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rpay_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: rpay-sdk
+Version: 1.0.0
+Summary: Official RPAY Payment & Banking SDK for Python — VietQR, 15 Vietnamese Bank Gateways (POS/V1/V2/V3), Bank Invoices, 18-Network USDT/USDC Crypto Gateway, Multi-Domain & HMAC-SHA256 Webhooks.
+Author-email: RPAY Team <support@rpay.vn>
+License: MIT
+Project-URL: Homepage, https://rpay.vn
+Project-URL: Documentation, https://rpay.vn/docs
+Project-URL: Repository, https://github.com/rpayvn/rpay-sdk-python
+Keywords: rpay,rpay-sdk,vietqr,sepay,payment-gateway,vietnam-bank-api,vietcombank,mbbank,acb,usdt,usdc,trc20,bep20,webhook,hmac-sha256
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# rpay-sdk (Python) — Thư viện Tích hợp Thanh toán Tự động RPAY (Bank VietQR VNĐ & Crypto USDT/USDC)
+
+Thư viện Python chính thức cho cổng thanh toán **RPAY (`https://api.rpay.vn` & hệ thống Web con / Multi-Domain)** dành cho **FastAPI, Flask, Django, Tornado & Cronjob Workers**.
+
+- **Zero-Config (Tự động đọc `.env` / `os.environ`)**: Không cần viết code khởi tạo rườm rà.
+- **Không phụ thuộc ngoài (Zero External Dependencies)**: Chỉ dùng thư viện chuẩn của Python (`urllib.request`, `hmac`, `hashlib`, `json`).
+- **Hợp nhất Cả Bank (15 cổng VietQR VNĐ) & Crypto (USDT/USDC trên 18 mạng lưới)**: Dùng chung 4 hàm `rpay.pay(...)`, `rpay.check(...)`, `rpay.lsgd(...)`, `rpay.qr(...)`.
+- **Hỗ trợ Đa Tên Miền (`Multi-Domain`)**: `rpay.for_domain("pay.shopa.vn")` hoặc truyền `domain="pay.shopb.com"` ngay trong từng hàm.
+
+---
+
+## 1. Cài đặt & Cấu hình `.env`
+
+```bash
+pip install rpay-sdk
+```
+
+Khai báo biến môi trường trong `.env` (hoặc `os.environ`):
+
+```env
+RPAY_DOMAIN=https://api.rpay.vn
+RPAY_BANK_TOKEN=rpay_vcb_live_123456_abcdef123456
+RPAY_MERCHANT_ID=MRCH-0001
+RPAY_USDT_API_KEY=ukey_live_xxxxxxxxxxxxxxxx
+RPAY_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxx
+```
+
+---
+
+## 2. 4 Hàm Cốt lõi Dễ Dùng Nhất (`pay`, `check`, `lsgd`, `qr`)
+
+```python
+import rpay_sdk as rpay
+
+# 1. Tạo hóa đơn Ngân hàng (VietQR VNĐ)
+bank_order = rpay.pay(
+    channel="bank",
+    amount=250000,
+    orderId="DH1001",
+    description="Nạp tiền tài khoản",
+    callbackUrl="https://webcuaban.com/api/webhooks/rpay",
+)
+
+# 2. Tạo hóa đơn Crypto (USDT / USDC trên 18 mạng lưới)
+crypto_order = rpay.pay(
+    channel="usdt",
+    network="TRC20",  # TRC20, BEP20, ERC20, SOLANA, TON, POLYGON, ARBITRUM, BASE...
+    token="USDT",
+    amount=50,
+    orderId="DH1002",
+    callbackUrl="https://webcuaban.com/api/webhooks/rpay",
+)
+
+print(bank_order["invoiceCode"], bank_order["paymentUrl"], bank_order["qrImageUrl"])
+
+# 3. Kiểm tra & Gạch nợ tức thì (Tự phân biệt RPINV... của Bank và USINV.../USTX... của USDT)
+checked = rpay.check(bank_order["invoiceCode"])
+if checked["isPaid"]:
+    print("Khách đã thanh toán:", checked["paidAmount"], checked["currency"])
+
+# 4. Tạo nhanh mã VietQR động
+qr = rpay.qr(bank="MB", account="0123456789", amount=150000, memo="DH1001")
+print(qr["qrDataUrl"], qr["qrImageUrl"])
+```
+
+---
+
+## 3. Lấy Lịch sử Giao dịch (LSGD) & Đối soát Chống Trùng (`rpay.lsgd` & `rpay.match_payment`)
+
+```python
+import rpay_sdk as rpay
+
+processed_ids = set()
+
+# Lấy đồng thời cả LSGD Ngân hàng (V2) + LSGD USDT trong 1 lệnh:
+history = rpay.lsgd(channel="all", bank="VCB", limit=50)
+
+matches = rpay.match_payment(
+    history["transactions"],
+    order_code="DH1001",
+    expected_amount=250000,
+    processed_ids=processed_ids,
+    mutate_processed_ids=True,  # Tự động thêm transactionID vào processed_ids
+)
+
+if matches:
+    tx = matches[0]
+    print(f"Đã khớp đơn qua {tx['channel']}: +{tx['amount']} {tx['currency']} (Mã GD: {tx['transactionID']})")
+```
+
+---
+
+## 4. Tích hợp Nhận Webhook `HMAC-SHA256` (FastAPI / Flask / Django)
+
+### Ví dụ với FastAPI:
+
+```python
+from fastapi import FastAPI, HTTPException, Request
+import rpay_sdk as rpay
+
+app = FastAPI()
+
+@app.post("/api/webhooks/rpay")
+async def rpay_webhook(request: Request):
+    raw_body = await request.body()
+    event = rpay.verify_webhook(
+        raw_body=raw_body,
+        headers=dict(request.headers),
+    )
+    if not event["verified"]:
+        raise HTTPException(status_code=401, detail=event["reason"])
+
+    # Tự động chuẩn hóa chung cho cả Bank Invoice (VND) và Crypto Invoice (USDT/USDC):
+    print("Kênh:", event["channel"], "Đơn:", event["orderId"], "Thực nhận:", event["paidAmount"], event["currency"])
+    return {"success": True, "received": True}
+```
+
+---
+
+## 5. Dùng trên Nhiều Tên Miền (`Multi-Domain`)
+
+```python
+import rpay_sdk as rpay
+
+shop_a = rpay.for_domain("pay.shopa.vn", bank_token="rpay_vcb_live_shopA...")
+shop_b = rpay.for_domain("pay.shopb.com", bank_token="rpay_mb_live_shopB...")
+
+inv_a = shop_a.pay(channel="bank", amount=200000, orderId="A-01")
+inv_b = shop_b.pay(channel="usdt", network="BEP20", amount=30, orderId="B-01")
+```
+
+---
+
+## 6. Xuất bản lên PyPI
+
+```bash
+cd C:\Users\kotin\Desktop\rpayv2\plugin\python
+python -m unittest discover -s tests
+pip install build twine
+python -m build
+twine upload dist/*
+```

rpay_sdk-1.0.0/README.md

@@ -0,0 +1,142 @@
+# rpay-sdk (Python) — Thư viện Tích hợp Thanh toán Tự động RPAY (Bank VietQR VNĐ & Crypto USDT/USDC)
+
+Thư viện Python chính thức cho cổng thanh toán **RPAY (`https://api.rpay.vn` & hệ thống Web con / Multi-Domain)** dành cho **FastAPI, Flask, Django, Tornado & Cronjob Workers**.
+
+- **Zero-Config (Tự động đọc `.env` / `os.environ`)**: Không cần viết code khởi tạo rườm rà.
+- **Không phụ thuộc ngoài (Zero External Dependencies)**: Chỉ dùng thư viện chuẩn của Python (`urllib.request`, `hmac`, `hashlib`, `json`).
+- **Hợp nhất Cả Bank (15 cổng VietQR VNĐ) & Crypto (USDT/USDC trên 18 mạng lưới)**: Dùng chung 4 hàm `rpay.pay(...)`, `rpay.check(...)`, `rpay.lsgd(...)`, `rpay.qr(...)`.
+- **Hỗ trợ Đa Tên Miền (`Multi-Domain`)**: `rpay.for_domain("pay.shopa.vn")` hoặc truyền `domain="pay.shopb.com"` ngay trong từng hàm.
+
+---
+
+## 1. Cài đặt & Cấu hình `.env`
+
+```bash
+pip install rpay-sdk
+```
+
+Khai báo biến môi trường trong `.env` (hoặc `os.environ`):
+
+```env
+RPAY_DOMAIN=https://api.rpay.vn
+RPAY_BANK_TOKEN=rpay_vcb_live_123456_abcdef123456
+RPAY_MERCHANT_ID=MRCH-0001
+RPAY_USDT_API_KEY=ukey_live_xxxxxxxxxxxxxxxx
+RPAY_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxx
+```
+
+---
+
+## 2. 4 Hàm Cốt lõi Dễ Dùng Nhất (`pay`, `check`, `lsgd`, `qr`)
+
+```python
+import rpay_sdk as rpay
+
+# 1. Tạo hóa đơn Ngân hàng (VietQR VNĐ)
+bank_order = rpay.pay(
+    channel="bank",
+    amount=250000,
+    orderId="DH1001",
+    description="Nạp tiền tài khoản",
+    callbackUrl="https://webcuaban.com/api/webhooks/rpay",
+)
+
+# 2. Tạo hóa đơn Crypto (USDT / USDC trên 18 mạng lưới)
+crypto_order = rpay.pay(
+    channel="usdt",
+    network="TRC20",  # TRC20, BEP20, ERC20, SOLANA, TON, POLYGON, ARBITRUM, BASE...
+    token="USDT",
+    amount=50,
+    orderId="DH1002",
+    callbackUrl="https://webcuaban.com/api/webhooks/rpay",
+)
+
+print(bank_order["invoiceCode"], bank_order["paymentUrl"], bank_order["qrImageUrl"])
+
+# 3. Kiểm tra & Gạch nợ tức thì (Tự phân biệt RPINV... của Bank và USINV.../USTX... của USDT)
+checked = rpay.check(bank_order["invoiceCode"])
+if checked["isPaid"]:
+    print("Khách đã thanh toán:", checked["paidAmount"], checked["currency"])
+
+# 4. Tạo nhanh mã VietQR động
+qr = rpay.qr(bank="MB", account="0123456789", amount=150000, memo="DH1001")
+print(qr["qrDataUrl"], qr["qrImageUrl"])
+```
+
+---
+
+## 3. Lấy Lịch sử Giao dịch (LSGD) & Đối soát Chống Trùng (`rpay.lsgd` & `rpay.match_payment`)
+
+```python
+import rpay_sdk as rpay
+
+processed_ids = set()
+
+# Lấy đồng thời cả LSGD Ngân hàng (V2) + LSGD USDT trong 1 lệnh:
+history = rpay.lsgd(channel="all", bank="VCB", limit=50)
+
+matches = rpay.match_payment(
+    history["transactions"],
+    order_code="DH1001",
+    expected_amount=250000,
+    processed_ids=processed_ids,
+    mutate_processed_ids=True,  # Tự động thêm transactionID vào processed_ids
+)
+
+if matches:
+    tx = matches[0]
+    print(f"Đã khớp đơn qua {tx['channel']}: +{tx['amount']} {tx['currency']} (Mã GD: {tx['transactionID']})")
+```
+
+---
+
+## 4. Tích hợp Nhận Webhook `HMAC-SHA256` (FastAPI / Flask / Django)
+
+### Ví dụ với FastAPI:
+
+```python
+from fastapi import FastAPI, HTTPException, Request
+import rpay_sdk as rpay
+
+app = FastAPI()
+
+@app.post("/api/webhooks/rpay")
+async def rpay_webhook(request: Request):
+    raw_body = await request.body()
+    event = rpay.verify_webhook(
+        raw_body=raw_body,
+        headers=dict(request.headers),
+    )
+    if not event["verified"]:
+        raise HTTPException(status_code=401, detail=event["reason"])
+
+    # Tự động chuẩn hóa chung cho cả Bank Invoice (VND) và Crypto Invoice (USDT/USDC):
+    print("Kênh:", event["channel"], "Đơn:", event["orderId"], "Thực nhận:", event["paidAmount"], event["currency"])
+    return {"success": True, "received": True}
+```
+
+---
+
+## 5. Dùng trên Nhiều Tên Miền (`Multi-Domain`)
+
+```python
+import rpay_sdk as rpay
+
+shop_a = rpay.for_domain("pay.shopa.vn", bank_token="rpay_vcb_live_shopA...")
+shop_b = rpay.for_domain("pay.shopb.com", bank_token="rpay_mb_live_shopB...")
+
+inv_a = shop_a.pay(channel="bank", amount=200000, orderId="A-01")
+inv_b = shop_b.pay(channel="usdt", network="BEP20", amount=30, orderId="B-01")
+```
+
+---
+
+## 6. Xuất bản lên PyPI
+
+```bash
+cd C:\Users\kotin\Desktop\rpayv2\plugin\python
+python -m unittest discover -s tests
+pip install build twine
+python -m build
+twine upload dist/*
+```

rpay_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rpay-sdk"
+version = "1.0.0"
+description = "Official RPAY Payment & Banking SDK for Python — VietQR, 15 Vietnamese Bank Gateways (POS/V1/V2/V3), Bank Invoices, 18-Network USDT/USDC Crypto Gateway, Multi-Domain & HMAC-SHA256 Webhooks."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.8"
+authors = [
+  { name = "RPAY Team", email = "support@rpay.vn" }
+]
+keywords = [
+  "rpay",
+  "rpay-sdk",
+  "vietqr",
+  "sepay",
+  "payment-gateway",
+  "vietnam-bank-api",
+  "vietcombank",
+  "mbbank",
+  "acb",
+  "usdt",
+  "usdc",
+  "trc20",
+  "bep20",
+  "webhook",
+  "hmac-sha256"
+]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Office/Business :: Financial",
+  "Topic :: Software Development :: Libraries :: Python Modules"
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://rpay.vn"
+Documentation = "https://rpay.vn/docs"
+Repository = "https://github.com/rpayvn/rpay-sdk-python"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["rpay_sdk*"]

rpay_sdk-1.0.0/rpay_sdk/__init__.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+from .client import RPayClient, RPayError, create_client, rpay
+from .constants import (
+    RPAY_BANKS,
+    RPAY_DEFAULT_BASE_URL,
+    RPAY_DEFAULT_TIMEOUT_SEC,
+    RPAY_USDT_NETWORKS,
+    resolve_bank_spec,
+    resolve_usdt_network_spec,
+)
+from .unified import (
+    detect_payment_channel,
+    match_unified_transactions,
+    normalize_unified_invoice,
+    normalize_unified_transaction,
+)
+from .webhooks import (
+    build_canonical_payload_string,
+    hmac_sha256_hex,
+    safe_compare_signature,
+    sign_canonical_payload,
+    sign_raw_body,
+    verify_webhook,
+)
+
+# Module-level shorthands so `import rpay_sdk as rpay; rpay.pay(...)` works seamlessly
+init = rpay.init
+configure = rpay.configure
+for_domain = rpay.for_domain
+pay = rpay.pay
+create_invoice = rpay.create_invoice
+check = rpay.check
+check_invoice = rpay.check_invoice
+status = rpay.status
+get_invoice = rpay.get_invoice
+lsgd = rpay.lsgd
+get_history = rpay.get_history
+qr = rpay.qr
+match_payment = rpay.match_payment
+route = rpay.route
+
+__all__ = [
+    "rpay",
+    "RPayClient",
+    "RPayError",
+    "create_client",
+    "init",
+    "configure",
+    "for_domain",
+    "pay",
+    "create_invoice",
+    "check",
+    "check_invoice",
+    "status",
+    "get_invoice",
+    "lsgd",
+    "get_history",
+    "qr",
+    "match_payment",
+    "route",
+    "verify_webhook",
+    "sign_canonical_payload",
+    "sign_raw_body",
+    "hmac_sha256_hex",
+    "safe_compare_signature",
+    "build_canonical_payload_string",
+    "RPAY_BANKS",
+    "RPAY_USDT_NETWORKS",
+    "RPAY_DEFAULT_BASE_URL",
+    "RPAY_DEFAULT_TIMEOUT_SEC",
+    "resolve_bank_spec",
+    "resolve_usdt_network_spec",
+    "detect_payment_channel",
+    "normalize_unified_invoice",
+    "normalize_unified_transaction",
+    "match_unified_transactions",
+]