> Bản đồ repo MONA Pay trong tổ chức The MONA Group: 10 SDK, MCP, CLI, plugin, connector, ví dụ; kèm cách báo lỗi, gửi PR và báo lỗ hổng.

Nguồn: https://monapay.vn/docs/github · Cập nhật: 2026-09-18

[Lấy API key miễn phí](https://my.monapay.vn/auth?mode=register)

Dùng ngay

- [Dùng ngay, không cần lập trình](https://monapay.vn/docs/dung-ngay)
- [Quán ăn, quán trà sữa](https://monapay.vn/docs/dung-ngay/quan-an-tra-sua)
- [Tiệm tóc, spa](https://monapay.vn/docs/dung-ngay/tiem-toc-spa)
- [Bán hàng online](https://monapay.vn/docs/dung-ngay/ban-hang-online)
- [Lớp học, trung tâm](https://monapay.vn/docs/dung-ngay/lop-hoc)

Bắt đầu

- [Tổng quan](https://monapay.vn/docs)
- [Bắt đầu nhanh (5 phút)](https://monapay.vn/docs/bat-dau-nhanh)
- [Khái niệm: VA, VietQR, webhook](https://monapay.vn/docs/khai-niem)

Theo stack

- [Site tĩnh Astro/Hugo + serverless](https://monapay.vn/docs/stack/astro-static-serverless)
- [Django / FastAPI](https://monapay.vn/docs/stack/django-fastapi)
- [Express / NestJS](https://monapay.vn/docs/stack/express-nestjs)
- [Flutter / React Native](https://monapay.vn/docs/stack/flutter-react-native)
- [Go / Spring Boot / .NET](https://monapay.vn/docs/stack/go-java-dotnet)
- [Google Sheets tự ghi tiền vào (Google Apps Scrip](https://monapay.vn/docs/stack/google-apps-script)
- [Laravel nhận VietQR, package PHP](https://monapay.vn/docs/stack/laravel)
- [Build bằng AI builder (Lovable/Bolt/v0/Replit)](https://monapay.vn/docs/stack/lovable-bolt-v0-replit)
- [n8n](https://monapay.vn/docs/stack/n8n)
- [Next.js (App Router, Vercel) nhận chuyển khoản t](https://monapay.vn/docs/stack/nextjs)
- [Supabase Edge Function nhận webhook, cập nhật bả](https://monapay.vn/docs/stack/supabase)
- [WordPress tự viết form, không WooCommerce](https://monapay.vn/docs/stack/wordpress-khong-woo)

Công thức cho agent

- [AI agent bán dịch vụ tự thu tiền rồi mới trả kết](https://monapay.vn/docs/cong-thuc/ai-agent-tu-thu-tien)
- [Bán khoá học, ebook, file số](https://monapay.vn/docs/cong-thuc/ban-khoa-hoc-file-so)
- [App đặt lịch thu cọc](https://monapay.vn/docs/cong-thuc/booking-thu-coc)
- [Bot Telegram/Zalo bán hàng](https://monapay.vn/docs/cong-thuc/bot-telegram-zalo-ban-hang)
- [Cá nhân, hộ kinh doanh chưa có công ty](https://monapay.vn/docs/cong-thuc/ca-nhan-chua-co-cong-ty)
- [Khách chuyển thiếu, thừa, sai nội dung](https://monapay.vn/docs/cong-thuc/khop-don-thieu-thua-sai-noi-dung)
- [App có ví](https://monapay.vn/docs/cong-thuc/nap-vi-cong-credit)
- [Nền tảng nhiều shop, mỗi shop nhận tiền vào tài](https://monapay.vn/docs/cong-thuc/platform-nhieu-shop)
- [SaaS gói tháng thu bằng chuyển khoản](https://monapay.vn/docs/cong-thuc/saas-thu-phi-thang)
- [Landing tĩnh trên Vercel/Netlify, không backend](https://monapay.vn/docs/cong-thuc/site-tinh-khong-backend)
- [Stripe không mở cho Việt Nam](https://monapay.vn/docs/cong-thuc/stripe-khong-ho-tro-viet-nam-dev)
- [Test webhook ở máy mình](https://monapay.vn/docs/cong-thuc/test-local-ngrok-sandbox)
- [Nhận tiền xong tự xuất hoá đơn điện tử và gửi em](https://monapay.vn/docs/cong-thuc/thu-tien-xong-xuat-hoa-don-gui-email)
- [Web bán hàng](https://monapay.vn/docs/cong-thuc/web-ban-hang-tu-xac-nhan-don)

Webhooks

- [Tích hợp webhook](https://monapay.vn/docs/webhooks/tich-hop-webhook)
- [Định dạng payload](https://monapay.vn/docs/webhooks/dinh-dang-payload)
- [Bảo mật: HMAC + chống replay](https://monapay.vn/docs/webhooks/bao-mat)
- [Gửi lại và xử lý lỗi](https://monapay.vn/docs/webhooks/gui-lai-va-xu-ly-loi)
- [Đối soát giao dịch](https://monapay.vn/docs/webhooks/doi-soat)

API v1

- [Xác thực](https://monapay.vn/docs/api/xac-thuc)
- [API keys](https://monapay.vn/docs/api/api-keys)
- [Sandbox: thử không tốn tiền](https://monapay.vn/docs/api/sandbox)
- [Tài khoản ảo (VA)](https://monapay.vn/docs/api/tai-khoan-ao-va)
- [QR thanh toán](https://monapay.vn/docs/api/qr-thanh-toan)
- [Trang thanh toán](https://monapay.vn/docs/api/trang-thanh-toan)
- [Giao dịch](https://monapay.vn/docs/api/giao-dich)
- [Cấu hình webhook qua API](https://monapay.vn/docs/api/webhook-configs)
- [Gói và hoá đơn (billing)](https://monapay.vn/docs/api/goi-va-hoa-don)

Cho lập trình viên

- [MCP server](https://monapay.vn/docs/mcp)
- [SDK](https://monapay.vn/docs/sdk)
- [Mã nguồn GitHub](https://monapay.vn/docs/github)

Kênh thông báo

- [Telegram](https://monapay.vn/docs/telegram)
- [Zalo](https://monapay.vn/docs/zalo)
- [Email](https://monapay.vn/docs/email)

Tham chiếu

- [API reference tương tác](https://monapay.vn/docs/api-reference)
- [Địa chỉ IP](https://monapay.vn/docs/dia-chi-ip)
- [Dành cho AI agent](https://monapay.vn/docs/ai-agent)

[MONA Pay](https://monapay.vn/)[Tài liệu](https://monapay.vn/docs)Mã nguồn MONA Pay trên GitHub

# Mã nguồn MONA Pay trên GitHub

Cập nhật 05/09/2026[Bản Markdown](https://monapay.vn/docs/github.md)[llms.txt](https://monapay.vn/llms.txt)[openapi.json](https://monapay.vn/openapi.json)

## Video hướng dẫn

Kho mã nguồn MONA Pay trên GitHub: 10 SDK, plugin, module và MCP · [Xem trên YouTube](https://www.youtube.com/watch?v=aCUAusi-hHo)

**Xem transcript video (8 phần)**

### Bản đồ mã nguồn MONA Pay

Bạn muốn tích hợp MONA Pay nhưng chưa biết nên lấy SDK, MCP hay plugin ở đâu, hoặc repo nào đúng với nền tảng đang dùng. Video này đi một vòng tổ chức themonagroup trên GitHub, chỉ rõ mười SDK, bộ công cụ cho AI agent, plugin WooCommerce và các module thương mại điện tử. Cuối video, bạn sẽ biết mở đúng README, lấy đúng lệnh cài và quay về tài liệu API khi cần kiểm endpoint.

### Bắt đầu từ tổ chức

Điểm bắt đầu là github.com/themonagroup. Nhánh mã nguồn MONA Pay tách theo ngôn ngữ và mục đích, nên đừng tải một repository bất kỳ rồi đoán cách dùng. Repo SDK có tên bắt đầu bằng monapay- và kết thúc bằng ngôn ngữ. Repo nền tảng ghi rõ tên hệ thống, còn monapay-examples gom ví dụ framework. Khi mở một repo, đọc README, yêu cầu phiên bản runtime, SECURITY và LICENSE trước khi đưa vào dự án.

### Năm SDK đầu tiên

Năm SDK đầu là monapay-node, monapay-python, monapay-php, monapay-go và monapay-java. Node dùng gói npm @monapay/node; Python dùng gói PyPI monapay; PHP dùng tên Composer monapay/php-sdk. Go dùng module github.com/themonagroup/monapay-go, còn Java có artifact monapay. Mỗi repo này có địa chỉ public ngay dưới tổ chức. Nếu dự án web mới dùng JavaScript hoặc TypeScript, bắt đầu ở Node. Flask, FastAPI hoặc Django thì mở Python.

### Năm SDK còn lại

Năm SDK còn lại là monapay-dotnet, monapay-ruby, monapay-rust, monapay-dart và monapay-elixir. Như vậy, tổ chức có đủ mười repo SDK theo mười hệ sinh thái. Các địa chỉ remote local đều trỏ về tổ chức themonagroup công khai trên GitHub. Từng repo có README riêng và ví dụ webhook phù hợp với framework của ngôn ngữ đó. Chọn SDK theo runtime đang chạy trên máy chủ, không theo ngôn ngữ của giao diện. Webhook luôn được xử lý ở backend có thể giữ secret an toàn.

### MCP CLI và ví dụ

Nhóm công cụ gồm monapay-mcp, monapay-cli và monapay-examples. MCP cho Claude Code, Cursor và Codex gọi MONA Pay trong lúc code; manifest local hiện có bốn mươi bảy tool. CLI phục vụ lệnh terminal như nghe webhook, tạo QR và tra giao dịch. Repo examples có mẫu Next.js, Express, NestJS, Laravel, Django, FastAPI, Spring Boot và Go. Bạn có thể bắt đầu từ ví dụ gần kiến trúc hiện tại rồi thay biến môi trường.

### Plugin và connector

Với cửa hàng, repo độc lập woocommerce-monapay là plugin WooCommerce. Repo monapay-connectors chứa lớp nối và adapter cho Shopify, Haravan, Sapo, KiotViet Retail, Nhanh.vn, Pancake POS và WooCommerce. Bên trong còn có module opencart-monapay, prestashop-monapay, magento2-monapay, bubble-monapay, ghost-monapay và một shopify-app. OpenCart dùng hosted checkout; PrestaShop tạo đơn chờ rồi nhận CHECKOUT_PAID; Shopify app nối đơn thanh toán thủ công với checkout MONA Pay.

### Chọn đúng repository

Cách chọn nhanh là: cần gọi API trong code thì lấy SDK; muốn AI agent tự thao tác thì dùng MCP; muốn thử kiến trúc hoàn chỉnh thì mở examples; đang bán trên WooCommerce thì lấy plugin; còn các nền tảng khác xem connectors. Lệnh cài Node và Python trên card được chép nguyên văn từ README. Dù dùng repo nào, giữ khóa trong biến môi trường, kiểm chữ ký webhook trên raw body và chống trùng bằng transaction_code.

### README sandbox và docs

GitHub cung cấp mã nguồn và ví dụ, còn nguồn xác nhận endpoint vẫn là monapay.vn/docs, llms.txt và openapi.json. Hãy mở README của đúng repo, chạy test local, dùng sandbox trước rồi mới nối luồng thật. Bạn tạo tài khoản tại my.monapay.vn và tạo khóa trong API Keys. Nếu chưa chắc nên chọn SDK, plugin hay connector nào, gọi một chín không không, sáu ba sáu, sáu bốn tám để đội MONA hướng dẫn.

Mã nguồn và ví dụ tích hợp MONA Pay nằm trong tổ chức [github.com/themonagroup](https://github.com/themonagroup). Chọn repo theo việc cần làm: SDK để gọi API trong backend, MCP để AI agent tự thao tác, CLI để thử từ terminal, plugin hoặc connector cho nền tảng bán hàng.

Tài liệu endpoint được phát hành riêng tại `monapay.vn`. Khi README và code mẫu chưa đủ một trường, hãy kiểm [OpenAPI 3.1](https://monapay.vn/openapi.json) và trang API tương ứng trước khi gửi request thật.

## Bản đồ repository

| Repo | Nội dung | Trạng thái ghi nhận trong repo |
| --- | --- | --- |
| [`monapay-node`](https://github.com/themonagroup/monapay-node) | SDK Node.js / TypeScript, package `@monapay/node` | npm 0.5.1 đã publish |
| [`monapay-python`](https://github.com/themonagroup/monapay-python) | SDK Python, package `monapay` | PyPI 0.5.1 đã publish |
| [`monapay-go`](https://github.com/themonagroup/monapay-go) | SDK Go, module `github.com/themonagroup/monapay-go` | Tag 0.4.0, cài được bằng module path |
| [`monapay-php`](https://github.com/themonagroup/monapay-php) | SDK PHP, package dự kiến `monapay/php-sdk` | Tag 0.4.0; trên GitHub, chưa lên Packagist |
| [`monapay-java`](https://github.com/themonagroup/monapay-java) | SDK Java, Maven artifact `com.themona:monapay` | Tag 0.4.0; trên GitHub, chưa lên Maven Central |
| [`monapay-dotnet`](https://github.com/themonagroup/monapay-dotnet) | SDK .NET, NuGet package `MonaPay` | Tag 0.4.0; trên GitHub, chưa lên NuGet |
| [`monapay-ruby`](https://github.com/themonagroup/monapay-ruby) | SDK Ruby, gem `monapay` | Tag 0.4.0; trên GitHub, chưa lên RubyGems |
| [`monapay-dart`](https://github.com/themonagroup/monapay-dart) | SDK Dart / Flutter, package `monapay` | Tag 0.4.0; trên GitHub, chưa lên pub.dev |
| [`monapay-rust`](https://github.com/themonagroup/monapay-rust) | SDK Rust, crate `monapay` | Tag 0.4.0; trên GitHub, chưa lên crates.io |
| [`monapay-elixir`](https://github.com/themonagroup/monapay-elixir) | SDK Elixir, Hex package `monapay` | Tag 0.4.0; trên GitHub, chưa lên Hex |
| [`monapay-mcp`](https://github.com/themonagroup/monapay-mcp) | MCP server cho Claude Code, Cursor, Codex | npm `monapay-mcp` 0.6.0, manifest có 50 tool |
| [`monapay-cli`](https://github.com/themonagroup/monapay-cli) | CLI đăng nhập, tạo QR, tra giao dịch, nghe webhook | npm `@monapay/cli` 0.2.0 đã publish |
| [`woocommerce-monapay`](https://github.com/themonagroup/woocommerce-monapay) | Plugin WooCommerce tạo checkout hoặc VietQR và tự xác nhận đơn | GitHub release 0.3.2; hồ sơ WordPress.org đang chờ |
| [`monapay-connectors`](https://github.com/themonagroup/monapay-connectors) | Shopify app, adapter và module cho các nền tảng bán hàng | Shopify, OpenCart, PrestaShop đã qua luồng sandbox tới `paid`; Magento đang ở bản scaffold |
| [`monapay-examples`](https://github.com/themonagroup/monapay-examples) | Mẫu Next.js, Express, NestJS, Laravel, Django, FastAPI, Spring Boot và Go | 8 ví dụ đã hoàn thành, có gate theo từng runtime |
| [`monapay.vn`](https://github.com/themonagroup/monapay.vn) | Site, docs, `llms.txt`, OpenAPI và Postman collection | Tài liệu public tại [monapay.vn/docs](https://monapay.vn/docs) |

Mỗi repo SDK có README, `SECURITY.md`, file license và ví dụ webhook theo ngôn ngữ. Hãy đọc yêu cầu runtime, cài đúng version rồi chạy test của repo trước khi ghép vào hệ thống đang thu tiền.

## Dùng CLI `monapay`

CLI cần Node.js 18 trở lên. Package đã publish là `@monapay/cli`:

```
npm install --global @monapay/cli
```

Nếu đang sửa source trong repo `monapay-cli`, chạy `npm link` từ thư mục repo để liên kết lệnh vào máy.

### Đăng nhập bằng API key

```
monapay login \
  --client-id "$MONAPAY_CLIENT_ID" \
  --client-secret "$MONAPAY_CLIENT_SECRET"

monapay me
```

CLI đổi client credentials thành OAuth token và cache theo hạn dùng. Credentials được lưu tại `~/.config/monapay/credentials.json`; thư mục có mode `700`, file có mode `600`. Có thể đổi vị trí bằng `MONAPAY_CONFIG_DIR`.

### Tạo VietQR động

QR động cần các giá trị merchant ACB trong biến môi trường như `MONAPAY_OWNER_NUMBER`, `MONAPAY_MERCHANT_ID`, `MONAPAY_TERMINAL_ID`, `MONAPAY_VA_PREFIX` và `MONAPAY_BENEFICIARY_NAME`. Khi đã đặt đủ:

```
monapay qr create \
  --order DH10234 \
  --amount 2500000 \
  --desc "Thanh toan DH10234"
```

CLI in `qr_data_url` và lưu ảnh `DH10234.png`. Dùng `--out ./public/qr/DH10234.png` nếu cần đường dẫn khác.

### Tra giao dịch

```
monapay tx list \
  --va MONA0000010234 \
  --limit 100

monapay tx list \
  --va MONA0000010234 \
  --since-id FT26240001234 \
  --json
```

`--since-id` dừng trước giao dịch đã biết và không in lại bản ghi đó. Đây là lọc phía CLI; lưu `transaction_code` ở database vẫn là lớp chống xử lý trùng cho đơn hàng.

### Nghe webhook tại máy

```
export MONAPAY_WEBHOOK_SECRET="secret-hmac"
monapay webhook listen --port 3939
```

Muốn chuyển tiếp sang app đang chạy:

```
monapay webhook listen \
  --port 3939 \
  --forward http://localhost:8000/webhook
```

MONA Pay cần một URL HTTPS public để bắn thử. Mở tunnel tới cổng 3939, sau đó dùng `monapay webhooks test --url https://TEN-TUNNEL.example`.

## OpenAPI và Postman

| File | Nội dung | Cách dùng |
| --- | --- | --- |
| [`openapi.json`](https://monapay.vn/openapi.json) | OpenAPI 3.1, hiện có 52 path | Import vào Postman, Insomnia hoặc công cụ sinh client; đây là nguồn kiểm method, path, field và response |
| [`monapay.postman_collection.json`](https://monapay.vn/monapay.postman_collection.json) | 20 request mẫu | Import collection rồi đặt `baseUrl`, `accessToken`, `clientSecret` trong environment riêng |
| [`llms.txt`](https://monapay.vn/llms.txt) | Mục lục docs có link Markdown | Đưa cho AI agent để tìm đúng trang |
| [`llms-full.txt`](https://monapay.vn/llms-full.txt) | Toàn văn tài liệu VI và EN | Dùng khi agent cần đọc trọn bộ trong một lần |

`baseUrl` mặc định của collection là `https://api.monapay.vn`. Không điền secret thật vào collection rồi export hoặc commit file environment.

## Báo lỗi

Mở tab **Issues** trong đúng repo và ghi đủ:

1. Runtime và version package đang dùng.
2. Các bước tái hiện ngắn, kèm request đã xoá token, secret, số tài khoản và dữ liệu khách hàng.
3. Kết quả mong đợi và kết quả thực tế.
4. HTTP status, `message` và log liên quan đã che dữ liệu nhạy cảm.

Kiểm issue đang mở trước để tránh tạo trùng. Lỗi thuộc endpoint API nhưng tái hiện qua SDK vẫn có thể mở ở repo SDK; ghi rõ path API để đội MONA chuyển đúng chỗ.

## Gửi pull request

Fork repo, tạo nhánh ngắn theo nội dung sửa, cập nhật test và README nếu hành vi public thay đổi. Chạy gate ghi trong README hoặc package scripts trước khi mở PR. Mô tả PR nên có lý do, phạm vi file, cách kiểm và ảnh chụp khi thay đổi giao diện plugin.

Không commit `.env`, API key, access token, webhook secret, file credentials CLI hoặc dữ liệu giao dịch thật. Nếu PR cần fixture, dùng mã đơn và VA giả.

## License và báo lỗ hổng bảo mật

SDK, MCP, CLI và bộ ví dụ dùng MIT. Plugin WooCommerce dùng GPLv2 hoặc mới hơn. Một số component connector có điều khoản riêng; ví dụ metadata Magento hiện ghi `proprietary`. File `LICENSE` hoặc metadata trong đúng repo là nguồn cần đọc trước khi phân phối lại.

Lỗ hổng bảo mật không đăng lên issue công khai. Gửi `info@themona.global` với tiêu đề `[security] monapay`, mô tả cách tái hiện và ảnh hưởng. Theo `SECURITY.md`, đội MONA xác nhận trong 2 ngày làm việc và chỉ công bố sau khi có bản vá.

Trong trang này

- Video hướng dẫn
- Bản đồ repository
- Dùng CLI monapay
- OpenAPI và Postman
- Báo lỗi
- Gửi pull request
- License và báo lỗ hổng bảo mật