The payment code structure defines the templates SePay uses to extract the code field from a bank transaction's transfer content. When a template matches, code is attached to the webhook payload and becomes available to the Chỉ gửi khi có mã thanh toán (Only when code present) and Lọc theo mã thanh toán (Filter by code prefix) filters on each webhook.
- Location: Cấu hình Công ty (Company Settings) → Cấu hình chung (General configuration) → Cấu trúc mã thanh toán
- Toggle payment code recognition on/off globally for the company account
- Each company account can have multiple templates; the first one is the default and cannot be deleted
- Applies to every real bank transaction and every active webhook
Open the General Configuration page
Go to my.sepay.vn → Cấu hình Công ty → Cấu hình chung. Scroll to the Nhận diện mã thanh toán (Payment code recognition) and Cấu trúc mã thanh toán (Payment code structure) sections.
Capture: The Cấu hình chung page scrolled to the Nhận diện mã thanh toán section with Bật/Tắt (On/Off) options, followed by Cấu trúc mã thanh toán listing the existing templates as collapsible cards. The first template carries the Mẫu mặc định (Default template) badge.
File: /images/sepay-webhooks/cau-hinh-ma-thanh-toan-1-trang.png
Replace with: <DocImage src="/images/sepay-webhooks/cau-hinh-ma-thanh-toan-1-trang.png" alt="General configuration page showing the payment code structure section" caption="Payment code recognition toggle and the list of payment code structures" width={1100} height={620} />
Enable payment code recognition
The Nhận diện mã thanh toán section has two states:
| State | Effect |
|---|---|
| Bật (On, default) | SePay scans the transfer content against active templates; the code field in the webhook payload is filled when a match is found |
| Tắt (Off) | SePay skips scanning; code is always empty even if the content contains a valid code |
The webhook filters Chỉ gửi khi có mã thanh toán and Lọc theo mã thanh toán only take effect when this toggle is On.
Fields in each template
Each template is a card with 4 fields plus a status switch:
| Field | Required | Description |
|---|---|---|
| Prefix (Tiền tố) | Yes | Beginning of the code (e.g. DH, HD). Minimum 2, maximum 5 characters. The system uppercases automatically on save. |
| Min suffix length | Yes | Minimum characters after the prefix. Range 1-30. Default 6. |
| Max suffix length | Yes | Maximum characters after the prefix. Range 1-30, must be ≥ min value. Default 8. |
| Character type | Yes | Số nguyên (digits only, 0-9) or Số và chữ (alphanumeric, digits and letters A-Z). |
| Status | No | Switch Đang hoạt động (Active) / Ngưng hoạt động (Inactive). Only active templates participate in matching. |
The Ví dụ (Example) line in each card auto-updates based on the current values (e.g. prefix DH + 6-char digit suffix shows DH111111).
Capture: A fully expanded template card: Mẫu mặc định (Default template) badge in the corner, prefix DH, suffix length from 6 to 8, character type Số nguyên (digits only), Đang hoạt động (Active) switch on. Shows the Ví dụ: DH11111111 line below.
File: /images/sepay-webhooks/cau-hinh-ma-thanh-toan-2-mau-ma.png
Replace with: <DocImage src="/images/sepay-webhooks/cau-hinh-ma-thanh-toan-2-mau-ma.png" alt="Default payment code template card with prefix DH on my.sepay.vn" caption="Default template card with prefix DH" width={780} height={420} />
Add, edit, remove templates
| Action | How |
|---|---|
| Add template | Click + Thêm mẫu mã (Add template) at the end of the list. The new card opens expanded. |
| Edit template | Expand the card, change fields, click Lưu lại (Save) at the bottom of the page. |
| Delete template | Click the trash icon on the card. The first template (Mẫu mặc định badge) cannot be deleted — you can only deactivate it. |
| Pause template | Turn the Đang hoạt động switch off, then Lưu lại. The template stays but is excluded from matching. |
After editing, click Lưu lại at the bottom. A "Lưu cấu hình thành công" (Saved successfully) toast appears on success.
How SePay extracts the code from transaction content
When a bank transaction lands, the system scans the transfer content against active templates in declaration order:
- Take the first active template.
- Search the content for a string matching
<prefix><N characters of the chosen type>where N is between min and max suffix length. The prefix match is case-insensitive. - On match, attach the matched string to the webhook payload's
codefield and stop. - On no match, try the next template. If no template matches,
codestays empty.
| Template | Transfer content | Extracted code |
|---|---|---|
Prefix DH, suffix 6-8, Digits only | DH123456 thanh toan don hang | DH123456 |
Prefix DH, suffix 6-8, Digits only | dh999999 thanh toan | DH999999 |
Prefix DH, suffix 6-8, Digits only | DH123 thanh toan | (empty — suffix shorter than 6) |
Prefix DH, suffix 6-8, Digits only | Chuyen tien sinh hoat | (empty) |
Prefix HD, suffix 4-6, Alphanumeric | HD12AB chuyen khoan | HD12AB |
Used by webhook filters
When you create a webhook, two filters depend on the code field:
| Filter | Effect |
|---|---|
| Chỉ gửi khi có mã thanh toán | The webhook skips transactions with no code (content didn't match any template) |
| Lọc theo mã thanh toán | The webhook only fires when code starts with one of the selected prefixes (sourced from your template list) |
Details: Create webhook.
Test before applying to Live
Live and Test mode payment code configurations are isolated. To try a new template before applying it to real transactions:
- Switch to Test mode in the sidebar
- Go to Payment code structure (Test mode) and create a template that matches your intended Live setup
- Simulate a transaction with sample content to verify the
codevalue in the webhook payload - When satisfied, copy the configuration over to Live
Next
- Create webhook: the Chỉ gửi khi có mã thanh toán and Lọc theo mã thanh toán filters
- Integrate webhook: the
codefield in the payload and how to use it to match orders - Test mode payment code structure: try templates safely before applying to Live