WEBHOOK NGÂN HÀNG — Tài liệu API

Ngân hàng hỗ trợ

Tính năng

Điểm nổi bật

Toàn bộ dữ liệu nằm trên máy chủ của bạn — không phụ thuộc dịch vụ bên ngoài.

Real-time 100%

Ngay khi app ngân hàng thông báo có tiền vào, dữ liệu lập tức được đẩy về máy chủ PHP.

Xác thực an toàn

Token bí mật gửi kèm trong JSON Payload giúp chặn dữ liệu giả mạo từ bên ngoài.

Thiết lập đơn giản

Không can thiệp API ngân hàng, không cần root máy — chỉ cần app MacroDroid trên Android.

Tự bóc tách dữ liệu

Máy đọc tự nhận diện ngân hàng, tiền vào/ra, số tiền, số tài khoản và mã giao dịch.

Cài đặt

Cài xong trong 1 phút

Cách nhanh nhất là tải sẵn file macro — khỏi tự tạo Trigger và Action. Nếu muốn tự chỉnh sửa thì làm tay theo 3 bước bên dưới.

Tải file macro có sẵn

Nhận file api-bank.macro đã cấu hình sẵn Trigger và Action. Mở MacroDroid → Import → chọn file → dán token của bạn vào ô "token" → bật công tắc là xong.

Tải file macro Khoảng 1–2 KB

Hoặc tự tạo tay trong MacroDroid

Tải App & Cấp Quyền cho MacroDroid

Tải MacroDroid từ CH Play, rồi cấp các quyền cần thiết.

Truy cập thông báo — cho phép đọc thông báo theo yêu cầu của app
Tối ưu hoá pin — đổi sang Không giới hạn (Unrestricted) để app không bị đóng ngầm
Tự khởi chạo (Auto-start) — tự hoạt động khi khởi động lại máy

Tạo Trigger (Bộ lọc thông báo)

Mở MacroDroid → Thêm Macro → chọn Trigger (Ô đỏ).

Chọn sự kiện thiết bị → rồi chọn Thông báo → Thông báo đã nhận
Ứng dung chọn app ngân hàng của bạn ví dụ: VCB Digibank hoặc MB Bank
Nội dung văn bản: chọn Bất kỳ (Any) xong nhấn OK

Cấu hình Action (Gửi HTTP POST)

Chọn Action (Ô xanh) → Chọn tương tác web → Yêu cầu HTTP Yêu cầu HTTP (HTTP Request), điền chính xác:

Phương Thức POST

URL https://dichvu.truonghoangkhiem.site/api-bank/api.php

Body Chọn tab nội dung rồi dán đoạn JSON bên dưới

Nội dung Body

application/json

{
  "token": "MBB_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "title": "{not_title}",
  "content": "{notification}"
}

Nhập tên Macro rồi bấm Lưu và chắc chắn công tắc đang bật ON.

Đoạn JSON mẫu đang dùng token ví dụ. Hãy lấy token API riêng do chủ hệ thống cấp và thay vào trường "token" trước khi lưu macro.

401

Token không hợp lệToken sai hoặc còn khoảng trắng thừa ở cuối. Xem lại trường token trong JSON.

403

Token bị khoá hoặc hết hạnLiên hệ chủ hệ thống để được mở khoá hoặc cấp token mới.

—

Macro không chạyKiểm tra công tắc đang ON và quyền Tối ưu hoá pin đã để Không giới hạn (Unrestricted).

Endpoint

Các đường dẫn API

Bấm vào tên một API để xem chi tiết và Response thật của nó.

01 POST Gửi thông báo /api.php

Webhook nhận thông báo từ MacroDroid. Lưu 1 bản ghi vào nhật ký token đó và tự động bóc tách dữ liệu giao dịch.

Gửi lên

Content-Type: application/json

Request body · JSON

{
  "token": "MBB_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "title": "VCB Digibank: Biến động số dư",
  "content": "VCB: +500,000 VND vao TK 1012345678 luc 09/10/2026 14:30. ND: NAP TIEN"
}

Trả về · 200

Response · application/json

{
  "success": true,
  "message": "Đã lưu và bóc tách thông báo thành công.",
  "error": null,
  "data": {
    "id": 102,
    "token_id": 12,
    "label": "MacroDroid · Samsung A52",
    "title": "VCB Digibank: Biến động số dư",
    "ip": "123.45.67.89",
    "created_at": "2026-10-09T14:30:00+07:00",
    "content_raw": "VCB: +500,000 VND vao TK 1012345678 luc 09/10/2026 14:30. ND: NAP TIEN",
    "parsed": {
      "bank": "VCB",
      "type": "IN",
      "amount": 500000,
      "account_number": "1012345678",
      "transaction_id": "",
      "transaction_time": "09/10/2026 14:30",
      "description": "NAP TIEN"
    }
  },
  "time": "2026-10-09T14:30:00+07:00"
}

Mã trả về

200Đã lưu + đã bóc tách
400Payload JSON không hợp lệ
401Thiếu token / token sai
403Token khoá hoặc hết hạn
422Thiếu cả title và content
429Quá giới hạn 60 req/phút
500Lỗi hệ thống

URL đầy đủ

https://dichvu.truonghoangkhiem.site/api-bank/api.php

02 GET Xem lịch sử /api.php?thao-tac=lich-su

Tối đa 20 thông báo gần nhất, mới nhất nằm trước. Có thể thêm &limit= để lấy ít hơn.

Gửi lên

Không có body — chỉ cần URL và tham số truy vấn.

Trả về · 200

Response · application/json

{
  "success": true,
  "message": "Danh sách thông báo.",
  "token_id": 12,
  "label": "MacroDroid · Samsung A52",
  "total": 1,
  "max_keep": 200,
  "items": [
    {
      "id": 102,
      "title": "VCB Digibank: Biến động số dư",
      "content": "VCB: +500,000 VND vao TK 1012345678 luc 09/10/2026 14:30. ND: NAP TIEN",
      "ip": "123.45.67.89",
      "created_at": "2026-10-09T14:30:00+07:00",
      "parsed": {
        "bank": "VCB",
        "type": "IN",
        "amount": 500000,
        "account_number": "1012345678",
        "transaction_id": "",
        "transaction_time": "09/10/2026 14:30",
        "description": "NAP TIEN"
      }
    }
  ],
  "time": "2026-10-09T14:35:00+07:00"
}

Mã trả về

200Danh sách thông báo
401Token sai hoặc không tồn tại
403Token khoá / hết hạn
429Quá giới hạn 60 req/phút

URL đầy đủ

https://dichvu.truonghoangkhiem.site/api-bank/api.php?thao-tac=lich-su&token=MBB_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

03 GET Kiểm tra token /api.php?thao-tac=kiem-tra

Xem token còn dùng được không, cùng số thông báo đã nhận. Nên gọi một lần trước khi cài macro.

Gửi lên

Không có body — chỉ cần URL và tham số truy vấn.

Trả về · 200

Response · application/json

{
  "success": true,
  "message": "Token hợp lệ.",
  "data": {
    "token_id": 12,
    "label": "MacroDroid · Samsung A52",
    "created_at": "2026-09-01T08:00:00+07:00",
    "expires_at": null,
    "last_used_at": "2026-10-09T14:30:00+07:00",
    "use_count": 143,
    "messages": 102
  },
  "time": "2026-10-09T14:35:00+07:00"
}

Mã trả về

200Token hợp lệ + thông tin token
401Token không hợp lệ

URL đầy đủ

https://dichvu.truonghoangkhiem.site/api-bank/api.php?thao-tac=kiem-tra&token=MBB_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

04 GET Thông tin API /api.php?thao-tac=thong-tin

Không cần token. Trả về giới hạn, phiên bản và danh sách endpoint đang hoạt động.

Gửi lên

Không có body — chỉ cần URL và tham số truy vấn.

Trả về · 200

Response · application/json

{
  "success": true,
  "message": "Thông tin API",
  "data": {
    "name": "WEBHOOK NGÂN HÀNG",
    "version": "3.0.0",
    "storage": "database",
    "parser": "on",
    "max_history": 20,
    "limits": {
      "rate_write": "60 req/phút",
      "rate_read": "60 req/phút",
      "max_title": 200,
      "max_content": 3000
    },
    "endpoints": [
      { "method": "POST", "path": "/api-bank/api.php", "desc": "Gửi thông báo" },
      { "method": "GET",  "path": "/api-bank/api.php?thao-tac=lich-su", "desc": "Xem lịch sử" }
    ],
    "parsed_fields": [
      { "name": "bank", "type": "string", "desc": "Mã ngân hàng (VCB, MB, TCB...) hoặc UNKNOWN" },
      { "name": "type", "type": "string|null", "desc": "IN = tiền vào, OUT = tiền ra" },
      { "name": "amount", "type": "int|null", "desc": "Số tiền biến động, không dấu phân cách" }
    ]
  },
  "time": "2026-10-09T14:35:00+07:00"
}

Mã trả về

200Thông tin cấu hình API

URL đầy đủ

https://dichvu.truonghoangkhiem.site/api-bank/api.php?thao-tac=thong-tin

Mọi phản hồi đều ở định dạng application/json và đã điền sẵn theo tên miền đang chạy. Xem khuôn Response chung để biết trường nào luôn có mặt.

Parser

Bóc tách tự động

Trước khi lưu, nội dung thông báo được máy đọc tự động và tách thành các trường có cấu trúc — không cần bạn tự viết regex trong MacroDroid.

Tin nhắn vào

content

VCB: +500,000 VND vao TK 1012345678 luc 09/10/2026 14:30.
SD: 12,500,000 VND.
ND: NAP TIEN HOANG KHIEM 12345

Kết quả ra

parsed

{
  "bank": "VCB",
  "type": "IN",
  "amount": 500000,
  "account_number": "1012345678",
  "transaction_id": "",
  "transaction_time": "09/10/2026 14:30",
  "description": "NAP TIEN HOANG KHIEM 12345"
}

Các trường được bóc tách tự động
Trường	Kiểu	Ý nghĩa	Ví dụ
bank	string	Mã ngân hàng rút gọn. Nhận diện được 17 ngân hàng phổ biến tại Việt Nam — VCB, MB, TCB, ACB, BIDV, VPB, TPB, CTG, AGR… Không nhận diện được trả về `UNKNOWN`.	VCB
type	string\|null	`IN` = tiền vào, `OUT` = tiền ra, `null` = tin nhắn không đủ dấu hiệu để kết luận (API không tự bịa).	IN
amount	int\|null	Số tiền biến động, đã bỏ hết dấu chấm/phẩy và đơn vị. Hiểu cả `500.000đ`, `1,250,000 VND`, `2.750.000`.	500000
account_number	string	Số tài khoản nhận hoặc chuyển, giữ nguyên dấu gạch nếu có (`0123-4567-8901`).	1012345678
transaction_id	string	Mã giao dịch / mã tham chiếu: nhận dạng theo nhãn (Ma GD, Ref, Mã tham chiếu) hoặc theo dạng mã của ngân hàng (VNR2024…).	VNR2024ABC123456
transaction_time	string	Thời gian giao dịch, giữ nguyên định dạng trong tin nhắn — không tự quy đổi múi giờ.	09/10/2026 14:30
description	string	Nội dung chuyển khoản, lấy từ phần sau nhãn `ND:`, `Nội dung:`, `Description:`.	NAP TIEN HOANG KHIEM

Quy ước: trường chuỗi không tìm thấy trả về "" (rỗng), trường số trả về null. Dữ liệu thô vẫn được giữ nguyên trong data.content_raw, nên bạn có thể tự xử lý lại nếu cần quy tắc riêng.

Response

Response mẫu

Luôn có success, message và time. Khi lỗi sẽ có thêm error để xử lý theo mã.

Thành công — HTTP 200

200 OK

{
  "success": true,
  "message": "Đã lưu và bóc tách thông báo thành công.",
  "error": null,
  "data": {
    "id": 102,
    "token_id": 12,
    "label": "MacroDroid · Samsung A52",
    "title": "VCB Digibank: Biến động số dư",
    "ip": "123.45.67.89",
    "created_at": "2026-10-09T14:30:00+07:00",
    "content_raw": "VCB: +500,000 VND vao TK 1012345678 luc 09/10/2026 14:30. SD: 12,500,000 VND. ND: NAP TIEN HOANG KHIEM 12345",
    "parsed": {
      "bank": "VCB",
      "type": "IN",
      "amount": 500000,
      "account_number": "1012345678",
      "transaction_id": "",
      "transaction_time": "09/10/2026 14:30",
      "description": "NAP TIEN HOANG KHIEM 12345"
    }
  },
  "time": "2026-10-09T14:30:00+07:00"
}

Lỗi — HTTP 403

403 Forbidden

{
  "success": false,
  "error": "token_da_khoa",
  "message": "Token đã bị khoá.",
  "time": "2026-10-09T14:32:07+07:00"
}

Thử ngay

Gửi thử một thông báo

Dán token của bạn vào bên dưới. Yêu cầu sẽ được gửi thật tới api.php ngay trên trang này.

Gửi thử ngay trên trang này

Yêu cầu đi thẳng tới api.php — dùng đúng token của bạn, không qua mô phỏng.

Token của bạn

Tiêu đề

Nội dung tin nhắn

Ô Tiêu đề và Nội dung tin nhắn đã điền sẵn — sửa hoặc bỏ trống cũng được.

Giới hạn

Giới hạn hiện tại

Đọc trực tiếp từ cấu hình đang chạy trên máy chủ, không phải con số ghi cứng.

Bảng giới hạn sử dụng API
Hạng mục	Giá trị	Ý nghĩa
Lịch sử mỗi token	20	Số thông báo giữ lại, mới nhất trước
Ghi — rate limit	60/phút	Số lần POST tối đa mỗi phút
Đọc — rate limit	60/phút	Số lần GET tối đa mỗi phút
Độ dài tiêu đề	200	Ký tự
Độ dài nội dung	3,000	Ký tự
Token mặc định	TOKENAPIBANK_…	Tiền tố token sinh ra
Hạn token mặc định	Không	Có thể đặt riêng cho từng token

FAQ

Câu hỏi thường gặp

Những điều người dùng hỏi nhiều nhất sau khi cài đặt.

Bao lâu thì nhận được thông báo?

Gần như tức thì — thường dưới 1–3 giây sau khi ngân hàng gửi thông báo tới điện thoại. Quá 10 giây thì kiểm tra lại macro đã bật ON chưa.

Những ngân hàng nào dùng được?

Bất kỳ app nào gửi thông báo tới điện thoại — phổ biến nhất là VCB Digibank và MB Bank. Bạn chọn app nào trong phần Trigger là dùng app đó. Bộ bóc tách tự nhận diện được 17 ngân hàng.

Cần can thiệp API ngân hàng hay root máy không?

Không. Toàn bộ hoạt động dựa trên quyền đọc thông báo của Android và app MacroDroid — cài đặt như một app bình thường.

Một token dùng cho được mấy máy?

Tối đa một token cho một thiết bị. Dùng chung sẽ khiến lịch sử bị trộn lẫn và dễ bị khoá khi nghi ngờ lạm dụng.

Có mất thông báo cũ không?

Mỗi token giữ lại 20 thông báo gần nhất. Vượt quá số này, thông báo cũ nhất tự động bị xoá.

Token có hết hạn không?

Tùy chọn. Có thể đặt hạn cố định, hạn theo ngày giờ cụ thể, hoặc không bao giờ hết hạn. Hết hạn thì API trả về mã 403.

Có chạy được trên iPhone không?

iOS không cho đọc thông báo ngân hàng tự động, nhưng bạn vẫn dùng được API bằng cách gửi POST trực tiếp từ bất kỳ ứng dụng nào hỗ trợ HTTP request.

Tự động nhận thông báo chuyển khoản Ngân hàng

Bạn gửi lên

Bạn nhận về

Điểm nổi bật

Real-time 100%

Xác thực an toàn

Thiết lập đơn giản

Tự bóc tách dữ liệu

Cài xong trong 1 phút

Tải file macro có sẵn

Tải App & Cấp Quyền cho MacroDroid

Tạo Trigger (Bộ lọc thông báo)

Cấu hình Action (Gửi HTTP POST)

Các đường dẫn API

Bóc tách tự động

Response mẫu

Gửi thử một thông báo

Gửi thử ngay trên trang này

Giới hạn hiện tại

Câu hỏi thường gặp