> 7 trường trong gói JSON MONA Pay gửi khi có tiền vào, 3 kiểu Content-Type, header kèm theo, gói gửi thử và định dạng tương thích đang triển khai.

Nguồn: https://monapay.vn/docs/webhooks/dinh-dang-payload · 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)Định dạng payload webhook MONA Pay

# Định dạng payload webhook MONA Pay

Cập nhật 03/09/2026[Bản Markdown](https://monapay.vn/docs/webhooks/dinh-dang-payload.md)[llms.txt](https://monapay.vn/llms.txt)[openapi.json](https://monapay.vn/openapi.json)

## Video hướng dẫn

Webhook MONA Pay gửi gì: từng trường trong payload và cách đọc · [Xem trên YouTube](https://www.youtube.com/watch?v=_F0ySFb6uW4)

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

### Hiểu payload để khỏi sai

Nhận được một gói webhook nhưng không biết trường nào dùng để khớp đơn, trường nào dùng để chống trùng là lỗi rất dễ làm sai dữ liệu. Trong video này, mình sẽ đọc đủ bảy trường payload, ba kiểu đóng gói, các header đi kèm và cách phân biệt gói thử. Làm xong, bạn có thể viết bộ nhận dữ liệu mà không phụ thuộc vào thứ tự trường.

### Payload mẫu bảy trường

Định dạng mặc định tên là monapay. Body JSON có đúng bảy trường: amount, description, transfer_date, transaction_code, account_number, bank_name và type. Dữ liệu mẫu có số tiền hai triệu năm trăm nghìn đồng, mã giao dịch FT26240001234, số tài khoản 1234567890, ngân hàng ACB và loại income. Hãy đọc theo tên khóa, đừng dựa vào vị trí vì hệ thống có thể thêm trường mới về sau.

### Tiền, nội dung, thời gian

Ba trường đầu mô tả khoản tiền. amount là số nguyên theo đơn vị VND, không có phần thập phân; hai triệu năm trăm nghìn đồng được gửi thành 2500000. description là nội dung khách gõ hoặc nội dung đã điền trong mã QR, có thể dùng để khớp đơn khi không dùng tài khoản ảo. transfer_date là chuỗi theo mẫu giờ, phút, giây rồi ngày, tháng, năm, sử dụng giờ Việt Nam.

### Mã và tài khoản nhận

Bốn trường còn lại giúp định danh. transaction_code là mã giao dịch phía ngân hàng, giữ nguyên qua mọi lần gửi lại và phải làm khóa UNIQUE. account_number cho biết tiền vào tài khoản thật hay tài khoản ảo nào; nếu mỗi đơn có một tài khoản ảo, so trường này là đủ. bank_name hiện có giá trị ACB. type hiện là income, nghĩa là tiền vào. Code nên bỏ qua giá trị hoặc trường lạ thay vì báo lỗi.

### Ba kiểu Content-Type

Bạn chọn một trong ba payload_format. application/json là mặc định và body là JSON không có khoảng trắng thừa. application/x-www-form-urlencoded gửi chuỗi giống form HTML, phù hợp hệ thống cũ chỉ đọc $_POST. multipart/form-data gửi mỗi trường thành một phần của form. Nếu dùng HMAC, luôn ký raw body đúng như nhận được, vì chuỗi JSON và chuỗi form tạo ra chữ ký khác nhau.

### Các header đi kèm

Header Content-Type luôn có và khớp với payload_format. Khi chọn HMAC_SHA256, gói nhận thêm X-Mona-Timestamp, là Unix giây lúc gửi, cùng X-Mona-Signature, có dạng sha256= rồi đến chuỗi hex. Nếu chọn API_KEY, Secret được đặt trong header tùy chọn, mặc định là X-Webhook-Secret. Chọn kiểu nào thì endpoint phải đọc đúng header của kiểu đó.

### Nhận biết gói gửi thử

Nút Gửi thử trong dashboard hoặc lệnh POST /api/v1/client-webhooks/test tạo một gói có đúng bảy trường. Với đơn quan trọng, bạn có thể tra transaction_code qua API đối soát trước khi đổi trạng thái, hoặc chỉ gửi thử vào môi trường staging. Đừng coi dữ liệu mẫu là tiền thật. Lớp nhận cũng nên giữ transaction_code làm khóa chống trùng, kể cả khi bấm thử nhiều lần.

### Parse ngày giờ đúng

Lỗi hay gặp nằm ở ngày giờ và kiểu dữ liệu. transfer_date dùng mẫu HH:MM:SS dd/mm/YYYY, giờ Việt Nam UTC cộng bảy, không phải ISO tám nghìn sáu trăm lẻ một; đừng đưa thẳng vào new Date(). Hãy tự phân tích đúng mẫu hoặc lưu nguyên chuỗi để đối soát. amount luôn là số nguyên. Gửi lại mười lần vẫn là cùng một transaction_code, nên không được cộng tiền mười lần.

### Mở docs và thử payload

Payload mẫu, bảng giải nghĩa và phần câu hỏi nhanh nằm tại monapay.vn/docs/webhooks/dinh-dang-payload. Bạn đăng ký tại my.monapay.vn, tạo webhook rồi dùng Gửi thử để nhìn đúng body hệ thống của mình nhận được. Nếu còn vướng cách đọc trường hoặc chọn định dạng, gọi tổng đài một chín không không, sáu ba sáu, sáu bốn tám để đội MONA hỗ trợ.

Mỗi webhook MONA Pay gửi là một gói JSON 7 trường: số tiền, nội dung, thời gian, mã giao dịch, số tài khoản nhận, tên ngân hàng và loại giao dịch. Bạn chọn được 1 trong 3 kiểu đóng gói (JSON, form-urlencoded, multipart). MONA Pay đang triển khai thêm tuỳ chọn định dạng tương thích các cổng phổ biến tại Việt Nam, xem mục cuối trang.

## Payload định dạng `monapay` (mặc định)

```
{
  "amount": 2500000,
  "description": "noi dung chuyen khoan",
  "transfer_date": "10:30:00 28/08/2026",
  "transaction_code": "FT26240001234",
  "account_number": "1234567890",
  "bank_name": "ACB",
  "type": "income"
}
```

| Trường | Kiểu | Ý nghĩa | Ghi chú |
| --- | --- | --- | --- |
| `amount` | số nguyên | Số tiền giao dịch, đơn vị VND | Không có phần thập phân. 2.500.000đ gửi là `2500000` |
| `description` | chuỗi | Nội dung chuyển khoản khách gõ hoặc nội dung trong mã QR | Dùng để khớp đơn khi không dùng VA |
| `transfer_date` | chuỗi | Thời điểm giao dịch, định dạng `HH:MM:SS dd/mm/YYYY`, giờ Việt Nam | Ví dụ dữ liệu thật: `14:52:05 03/09/2026` |
| `transaction_code` | chuỗi | Mã giao dịch phía ngân hàng | Giữ nguyên qua mọi lần gửi lại. Dùng làm khoá chống trùng |
| `account_number` | chuỗi | Số VA hoặc số tài khoản nhận tiền | Khớp đơn theo VA thì so trường này |
| `bank_name` | chuỗi | Tên ngân hàng | Hiện luôn là `ACB` |
| `type` | chuỗi | Loại giao dịch | Hiện chỉ có `income` (tiền vào) |

Ba điều nên biết khi dùng:

- **`transaction_code` là khoá duy nhất.** Gửi lại 10 lần thì cả 10 gói cùng một `transaction_code`. Bảng giao dịch của bạn nên có ràng buộc UNIQUE trên cột này.
- **`account_number` cho biết tiền vào VA nào.** Nếu bạn gắn mỗi đơn một VA, chỉ cần so trường này là biết đơn nào đã trả, không cần đọc `description`.
- **Trường sẽ được thêm, không bị đổi tên.** Khi MONA Pay mở thêm ngân hàng hoặc loại giao dịch, đội MONA thêm giá trị mới (ví dụ `bank_name` khác `ACB`, `type` khác `income`) chứ không đổi tên 7 trường này. Code của bạn nên bỏ qua trường lạ thay vì báo lỗi.

## Ba kiểu Content-Type

Chọn trong dashboard hoặc qua trường `payload_format` khi tạo cấu hình:

| `payload_format` | MONA Pay gửi thế nào | Dùng khi |
| --- | --- | --- |
| `application/json` | Body là chuỗi JSON như trên, không khoảng trắng thừa | Mặc định. Mọi framework hiện đại đều nhận được |
| `application/x-www-form-urlencoded` | Body dạng `amount=2500000&description=...` như form HTML | Hệ thống cũ chỉ đọc `$_POST` |
| `multipart/form-data` | Từng trường là một phần của form nhiều phần | Hệ thống chỉ nhận multipart |

Với HMAC, chuỗi được ký là raw body đúng như MONA Pay gửi: JSON không khoảng trắng với kiểu JSON, chuỗi urlencoded với kiểu form. Chi tiết ở [Bảo mật webhook](https://monapay.vn/docs/webhooks/bao-mat).

## Header đi kèm

| Header | Khi nào có | Giá trị |
| --- | --- | --- |
| `Content-Type` | Luôn | Theo `payload_format` đã chọn |
| `X-Mona-Timestamp` | Kiểu xác thực `HMAC_SHA256` | Unix giây lúc gửi |
| `X-Mona-Signature` | Kiểu xác thực `HMAC_SHA256` | `sha256=<hex>` |
| Header tên tuỳ chọn (mặc định `X-Webhook-Secret`) | Kiểu xác thực `API_KEY` | Secret bạn đặt |

## Định dạng tương thích (đang triển khai)

MONA Pay đang triển khai thêm tuỳ chọn định dạng payload tương thích với các cổng phổ biến tại Việt Nam để đổi nhà cung cấp không phải sửa code; công bố tại trang này khi lên. Trong lúc chờ, 7 trường ở trên đủ để bạn viết một lớp chuyển đổi khoảng 10 dòng ở đầu nhận: đổi tên trường theo cấu trúc code cũ, giữ `transaction_code` làm khoá chống trùng, rồi gọi lại hàm xử lý sẵn có.

## Gói gửi thử

Khi bấm Gửi thử trong dashboard hoặc gọi `POST /api/v1/client-webhooks/test`, MONA Pay gửi một gói có đúng 7 trường này với dữ liệu mẫu. Endpoint của bạn nên phân biệt gói thử với giao dịch thật bằng cách kiểm tra `transaction_code` có tồn tại trong danh sách giao dịch (qua [API đối soát](https://monapay.vn/docs/webhooks/doi-soat)) trước khi đổi trạng thái đơn quan trọng, hoặc đơn giản là chỉ gửi thử vào môi trường staging.

## Câu hỏi nhanh

**Số tiền có bao giờ là số thập phân không?** Không. VND không có phần lẻ, `amount` luôn là số nguyên.

**Múi giờ của `transfer_date`?** Giờ Việt Nam (UTC+7), đúng như ACB báo.

**Có gửi giao dịch tiền ra không?** Hiện chưa. `type` luôn là `income`. Khi có thêm loại khác đội MONA giữ nguyên tên trường.

**Tôi nhận webhook bằng Google Apps Script hoặc n8n được không?** Được, miễn URL nhận POST và trả 200 trong 10 giây. Với chữ ký HMAC, cần lấy raw body để tính lại, xem [Bảo mật webhook](https://monapay.vn/docs/webhooks/bao-mat).

## Lưu ý định dạng `transfer_date`

`transfer_date` là chuỗi `HH:MM:SS dd/mm/YYYY` theo giờ Việt Nam (UTC+7), ví dụ `14:52:05 03/09/2026`. Đây không phải ISO 8601: không đưa thẳng giá trị vào `new Date()`; hãy parse theo đúng định dạng này hoặc lưu nguyên chuỗi để đối soát.

Trong trang này

- Video hướng dẫn
- Payload định dạng monapay (mặc định)
- Ba kiểu Content-Type
- Header đi kèm
- Định dạng tương thích (đang triển khai)
- Gói gửi thử
- Câu hỏi nhanh
- Lưu ý định dạng transfer_date
