Appearance
🧠 Khái niệm & Tích hợp Hook Pay2S
🔌 Tích hợp nhanh chóng
Việc tích hợp cực kỳ đơn giản với PHP, Node.js hoặc bất kỳ ngôn ngữ nào.
Bạn chỉ cần khai báo đầu nhận dữ liệu (endpoint) và xử lý kết quả được Pay2S gửi về.
🏦 Liên kết tài khoản
Bạn cần có tài khoản Pay2S và liên kết ít nhất một tài khoản ngân hàng.
Truy cập trang quản trị để xem danh sách tài khoản liên kết.
Giao diện liên kết
Hệ thống có thể hỗ trợ liên kết cùng lúc nhiều tài khoản. Việc tích hợp gần như không phụ thuộc vào việc bạn liên kết tài khoản nào vào hệ thống nhờ tính linh động của hệ thống Hook.
⚙️ Tạo Hook
Sau khi liên kết tài khoản, bạn tiến hành khai báo Hook – là endpoint của bạn để nhận dữ liệu giao dịch.
Chi tiết vui lòng tham khảo ở mục Tạo Hook !
📩 Cơ chế gửi giao dịch
- Mỗi giao dịch được gửi riêng lẻ: nếu có 5 giao dịch thì gửi 5 lần
- Bạn có thể theo dõi tại Lịch sử giao dịch để debug
Mẹo: Tạo 1 giao dịch test → Xem dữ liệu tại Lịch sử giao dịch để kiểm tra endpoint
🔐 Bảo mật với API Key
Dữ liệu được gửi ở định dạng JSON (raw body) với Header:
Authorization: Bearer [Token của Hook]⚠️ Lưu ý: Token được gửi trong Header
Authorization. Bạn PHẢI kiểm tra và so sánh Token này trước khi xử lý dữ liệu giao dịch để đảm bảo request từ Pay2S thực sự.
📦 Dữ liệu giao dịch gửi về từ Pay2S
Dưới đây là các trường được gửi từ hệ thống:
| Trường | Kiểu | Mô tả |
|---|---|---|
| id | String | Mã định danh duy nhất tại Pay2S |
| gateway | String | Tên cổng thanh toán (momo, vcb, techcombank...) |
| transactionDate | Date | Ngày tháng giao dịch (yyyy-mm-dd) |
| transactionNumber | String | Mã giao dịch riêng biệt, không trùng lặp trên cùng tài khoản |
| accountNumber | String | Số tài khoản liên kết nhận giao dịch |
| content | String | Nội dung giao dịch từ cổng thanh toán |
| transferType | String | Loại giao dịch: IN (nhận) hoặc OUT (chuyển) |
| transferAmount | Long | Số tiền giao dịch (dạng số nguyên, vd: 1000000) |
| checksum | String | Mã xác định duy nhất giao dịch được sinh ra từ Pay2S |
⚡ Best Practices
- Xác thực Token: Luôn check header
Authorizationtrước khi xử lý - Verify checksum: Kiểm tra tính toàn vẹn dữ liệu bằng checksum
- Idempotent: Xử lý webhook nhiều lần mà không gây lỗi (check
idhoặctransactionNumber) - Response nhanh: Trả về HTTP 200 trong vòng 30 giây
- Async processing: Offload xử lý nặng vào queue/background job
- Logging: Log tất cả request webhook để debug
- Retry logic: Pay2S sẽ retry nếu không nhận được 200 OK
- HTTPS Only: Endpoint phải dùng HTTPS
- Database transaction: Dùng transaction khi cập nhật database
- Monitoring: Alert khi có lỗi hoặc timeout