📚 Tài liệu kỹ thuật Webhook

🔄 Cơ chế hoạt động

Khi một giao dịch xảy ra, Pay2S sẽ gửi dữ liệu đến endpoint của bạn qua HTTP POST.

🛠️ Request từ Pay2S

Method

POST

Header

{
  "Content-Type": "application/json",
  "Authorization": "Bearer <YOUR_TOKEN_WEBHOOK>"
}

Body (POST Parameters)

{
  "transactions": [
    {
      "id": 10001,
      "gateway": "ACB",
      "transactionDate": "2026-10-11 09:00:00",
      "transactionNumber": "DEMO10001",
      "accountNumber": "P2S99999999",
      "content": "THANHTOAN DH10001",
      "transferType": "IN",
      "transferAmount": 2000,
      "checksum": "demo-user-webhook-10001",
      "paymentCode": "DH10001",
      "extraData": {
        "remitterName": "NGUYEN VAN A",
        "remitterAccountNumber": "0123456789",
        "issuerBankName": "Ngan hang TMCP Quan Doi",
        "reciprocalBankCode": "970422"
      }
    }
  ]
}

Trường bổ sung: paymentCode, người chuyển và tài khoản ảo

Các trường bên dưới nằm trong từng phần tử transactions[], không nằm ở ngoài mảng. Payload dưới đây là webhook giao dịch, không phải IPN thanh toán hoặc webhook trạng thái Hosted Link.

Có mã thanh toán và thông tin người chuyển

{
  "transactions": [
    {
      "id": 10001,
      "gateway": "ACB",
      "transactionDate": "2026-10-11 09:00:00",
      "transactionNumber": "DEMO10001",
      "accountNumber": "P2S99999999",
      "content": "THANHTOAN DH10001",
      "transferType": "IN",
      "transferAmount": 2000,
      "checksum": "demo-user-webhook-10001",
      "paymentCode": "DH10001",
      "extraData": {
        "remitterName": "NGUYEN VAN A",
        "remitterAccountNumber": "0123456789",
        "issuerBankName": "Ngan hang TMCP Quan Doi",
        "reciprocalBankCode": "970422"
      }
    }
  ]
}

Thiếu thông tin người chuyển: khi đã bật extraData, worker thay giá trị null hoặc không có bằng chuỗi "N/A". Chuỗi rỗng từ ngân hàng vẫn được giữ nguyên. Không coi N/A là tên hoặc số tài khoản thật, không bắt buộc có thông tin người chuyển mới ghi nhận một giao dịch hợp lệ.

Bật extraData nhưng ngân hàng không cung cấp thông tin

{
  "transactions": [
    {
      "id": 10001,
      "gateway": "ACB",
      "transactionDate": "2026-10-11 09:00:00",
      "transactionNumber": "DEMO10001",
      "accountNumber": "P2S99999999",
      "content": "THANHTOAN DH10001",
      "transferType": "IN",
      "transferAmount": 2000,
      "checksum": "demo-user-webhook-10001",
      "extraData": {
        "remitterName": "N/A",
        "remitterAccountNumber": "N/A",
        "issuerBankName": "N/A",
        "reciprocalBankCode": "N/A"
      }
    }
  ]
}

Tài khoản ảo và mã tham chiếu đối tác

{
  "transactions": [
    {
      "id": 10001,
      "gateway": "BIDV",
      "transactionDate": "2026-10-11 09:00:00",
      "transactionNumber": "DEMO10001",
      "accountNumber": "963869123456",
      "content": "THANHTOAN DH10001",
      "transferType": "IN",
      "transferAmount": 2000,
      "checksum": "demo-user-webhook-10001",
      "partnerRefId": "PARTNER_REF_DEMO",
      "TID": "123456"
    }
  ]
}

Theo worker hiện tại, nếu giao dịch có vaNumber thì accountNumber = "963869" + vaNumber; nếu không, accountNumber là tài khoản gốc. TID giữ giá trị vaNumber gốc và chỉ đi kèm nhánh partnerRefId. Không tự thêm tiền tố lần nữa hoặc chuyển số tài khoản/TID sang kiểu số. Webhook gửi trực tiếp không có trường vaNumber riêng trong nhánh này; payload dựng lại từ API lịch sử webhook có thể có trường đó và accountNumber là tài khoản gốc.

Ví dụ liệt kê toàn bộ trường có điều kiện

Mẫu này ghép các nhánh của worker để minh họa tên và vị trí trường; không có nghĩa một ngân hàng hoặc mọi giao dịch luôn trả đủ các trường này. Các giá trị là dữ liệu thử, không phải bản chụp giao dịch ngân hàng thật.

{
  "transactions": [
    {
      "id": 10001,
      "gateway": "ACB",
      "transactionDate": "2026-10-11 09:00:00",
      "transactionNumber": "DEMO10001",
      "accountNumber": "963869123456",
      "content": "THANHTOAN DH10001",
      "transferType": "IN",
      "transferAmount": 2000,
      "checksum": "demo-user-webhook-10001",
      "paymentCode": "DH10001",
      "billNumber": "BILL_DEMO_001",
      "partnerRefId": "PARTNER_REF_DEMO",
      "TID": "123456",
      "teller": "TELLER_DEMO",
      "sequence": "000123",
      "extraData": {
        "remitterName": "NGUYEN VAN A",
        "remitterAccountNumber": "0123456789",
        "issuerBankName": "Ngan hang TMCP Quan Doi",
        "reciprocalBankCode": "970422"
      }
    }
  ]
}

Đọc dữ liệu mà không phụ thuộc trường tùy chọn

for (const transaction of payload.transactions) {
  const paymentCode = transaction.paymentCode ?? null;
  const extra = transaction.extraData ?? {};
  const remitterName = extra.remitterName && extra.remitterName !== 'N/A'
    ? extra.remitterName : null;
  const remitterAccount = extra.remitterAccountNumber && extra.remitterAccountNumber !== 'N/A'
    ? extra.remitterAccountNumber : null;
  // Lưu giao dịch có chống trùng theo id/checksum.
  // paymentCode, remitterName, remitterAccount có thể không có.
}

Kiểm tra Bearer token trước khi xử lý; lưu giao dịch hoặc đưa vào hàng đợi bền vững trước khi ACK. Receiver nên chấp nhận các trường bổ sung mới, không từ chối toàn bộ giao dịch chỉ vì thiếu trường tùy chọn.

Response từ Endpoint của bạn

{
  "success": true
}

🔁 Cơ chế Retry

Worker gửi trực tiếp và worker retry có lịch riêng; timeout, khoảng cách retry và số lần thử phụ thuộc cấu hình worker. Không suy ra lịch nhận chính xác chỉ từ số lần thử.

Receiver nên trả HTTP 200 và JSON { "success": true } sau khi đã lưu giao dịch hoặc đưa vào hàng đợi bền vững. Worker giao dịch hiện chấp nhận HTTP 2xx đồng thời body có success đúng; chỉ trả HTTP 200 hoặc chỉ có JSON thành công với HTTP lỗi đều không đủ. Đây không phải điều kiện ACK của IPN thanh toán.

💻 Code mẫu

<?php
// Token hợp lệ của bạn
$expectedToken = 'your_expected_token_here';

// Lấy Authorization header
$headers = getallheaders();
$authHeader = $headers['Authorization'] ?? '';

// Kiểm tra token
if (!preg_match('/Bearer\s(\S+)/', $authHeader, $matches)) {
    http_response_code(401);
    echo json_encode(['success' => false]);
    exit;
}

$receivedToken = $matches[1];
if ($receivedToken !== $expectedToken) {
    http_response_code(403);
    echo json_encode(['success' => false]);
    exit;
}

// Lấy dữ liệu JSON
$data = json_decode(file_get_contents('php://input'), true);

if (!$data || !isset($data['transactions'])) {
    http_response_code(400);
    echo json_encode(['success' => false, 'message' => 'Invalid payload']);
    exit;
}

// Xử lý từng giao dịch
foreach ($data['transactions'] as $transaction) {
    $id = $transaction['id'];
    $amount = $transaction['transferAmount'];
    $content = $transaction['content'];
    
    // Lưu vào database
    // INSERT INTO transactions (id, amount, content) VALUES ($id, $amount, $content);
}

// Trả về 200
http_response_code(200);
echo json_encode(['success' => true]);
?>

const express = require('express');
const app = express();

app.use(express.json());

const SECRET_KEY = 'your_expected_token_here';

app.post('/webhook', (req, res) => {
  // Kiểm tra Authorization
  const authHeader = req.headers['authorization'] || '';
  const token = authHeader.replace('Bearer ', '');
  
  if (token !== SECRET_KEY) {
    return res.status(403).json({ success: false });
  }

  const { transactions } = req.body;
  
  if (!transactions || !Array.isArray(transactions)) {
    return res.status(400).json({ success: false });
  }

  // Xử lý từng giao dịch
  transactions.forEach(tx => {
    const { id, transferAmount, content } = tx;
    // await Transaction.create({ id, transferAmount, content });
  });

  return res.status(200).json({ success: true });
});

app.listen(3000, () => console.log('Webhook running on :3000'));

from flask import Flask, request, jsonify

app = Flask(__name__)
SECRET_KEY = 'your_expected_token_here'

@app.route('/webhook', methods=['POST'])
def webhook():
    # Kiểm tra Authorization
    auth_header = request.headers.get('Authorization', '')
    token = auth_header.replace('Bearer ', '')
    
    if token != SECRET_KEY:
        return jsonify({'success': False}), 403

    data = request.get_json()
    
    if not data or 'transactions' not in data:
        return jsonify({'success': False}), 400
    
    # Xử lý từng giao dịch
    for tx in data['transactions']:
        tx_id = tx.get('id')
        amount = tx.get('transferAmount')
        content = tx.get('content')
        # db.transaction.insert_one({ 'id': tx_id, 'amount': amount, 'content': content })
    
    return jsonify({'success': True}), 200

if __name__ == '__main__':
    app.run(port=5000)

import org.springframework.web.bind.annotation.*;
import org.springframework.http.ResponseEntity;
import org.springframework.http.HttpStatus;
import com.google.gson.Gson;
import java.util.Map;
import java.util.List;

@RestController
@RequestMapping("/webhook")
public class WebhookController {
    
    private static final String SECRET_KEY = "your_expected_token_here";
    
    @PostMapping
    public ResponseEntity<?> handleWebhook(
            @RequestHeader(value = "Authorization", required = false) String authHeader,
            @RequestBody Map<String, Object> data) {
        
        // Kiểm tra Authorization
        if (authHeader == null) {
            return ResponseEntity.status(HttpStatus.FORBIDDEN)
                    .body(Map.of("success", false));
        }
        
        String token = authHeader.replace("Bearer ", "");
        if (!token.equals(SECRET_KEY)) {
            return ResponseEntity.status(HttpStatus.FORBIDDEN)
                    .body(Map.of("success", false));
        }

        // Lấy transactions
        List<Map<String, Object>> transactions = (List<Map<String, Object>>) data.get("transactions");
        
        if (transactions == null) {
            return ResponseEntity.badRequest().body(Map.of("success", false));
        }

        // Xử lý từng giao dịch
        for (Map<String, Object> tx : transactions) {
            String id = (String) tx.get("id");
            Long amount = ((Number) tx.get("transferAmount")).longValue();
            String content = (String) tx.get("content");
            // transactionService.save(new Transaction(id, amount, content));
        }

        return ResponseEntity.ok(Map.of("success", true));
    }
}

package main

import (
    "encoding/json"
    "log"
    "net/http"
    "strings"
)

const SECRET_KEY = "your_expected_token_here"

type Transaction struct {
    ID             string `json:"id"`
    TransferAmount int64  `json:"transferAmount"`
    Content        string `json:"content"`
}

type WebhookRequest struct {
    Transactions []Transaction `json:"transactions"`
}

func webhookHandler(w http.ResponseWriter, r *http.Request) {
    // Kiểm tra Authorization
    authHeader := r.Header.Get("Authorization")
    token := strings.TrimPrefix(authHeader, "Bearer ")
    
    if token != SECRET_KEY {
        w.WriteHeader(http.StatusForbidden)
        json.NewEncoder(w).Encode(map[string]bool{"success": false})
        return
    }

    // Parse JSON body
    var webhook WebhookRequest
    if err := json.NewDecoder(r.Body).Decode(&webhook); err != nil {
        w.WriteHeader(http.StatusBadRequest)
        json.NewEncoder(w).Encode(map[string]bool{"success": false})
        return
    }

    // Xử lý từng giao dịch
    for _, tx := range webhook.Transactions {
        log.Printf("Processing transaction: %s, Amount: %d", tx.ID, tx.TransferAmount)
        // db.SaveTransaction(tx)
    }

    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusOK)
    json.NewEncoder(w).Encode(map[string]bool{"success": true})
}

func main() {
    http.HandleFunc("/webhook", webhookHandler)
    log.Println("Webhook server running on :8080")
    http.ListenAndServe(":8080", nil)
}

require 'sinatra'
require 'json'

SECRET_KEY = 'your_expected_token_here'

post '/webhook' do
  # Kiểm tra Authorization
  auth_header = request.headers['Authorization'] || ''
  token = auth_header.sub('Bearer ', '')
  
  if token != SECRET_KEY
    status 403
    return { success: false }.to_json
  end

  # Lấy dữ liệu
  data = JSON.parse(request.body.read)
  transactions = data['transactions']
  
  unless transactions.is_a?(Array)
    status 400
    return { success: false }.to_json
  end

  # Xử lý từng giao dịch
  transactions.each do |tx|
    id = tx['id']
    amount = tx['transferAmount']
    content = tx['content']
    # Transaction.create(id: id, amount: amount, content: content)
  end

  status 200
  { success: true }.to_json
end

🔧 Troubleshooting

⚠️ Authorization header không được nhận

Nếu server của bạn không nhận được header Authorization, thêm rule này vào .htaccess:

RewriteEngine On
RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule .* - [e=HTTP_AUTHORIZATION:%1]

⚡ Best Practices

1. Xác thực ngay: Kiểm tra token trước khi xử lý
2. Validate dữ liệu: Kiểm tra transactions array trước khi loop
3. Response nhanh: Trả về 200 ngay, offload xử lý vào queue/background job
4. Idempotent: Xử lý webhook nhiều lần mà không bị lỗi (kiểm tra ID trước insert)
5. Logging: Log tất cả webhook request/response để debug
6. Error handling: Không trả về 200 nếu xử lý thất bại
7. Timeout: Đặt timeout vì Pay2S sẽ retry sau 60 giây
8. Database transaction: Dùng DB transaction để tránh data inconsistency
9. Monitoring: Alert nếu webhook failed nhiều lần
10. Versioning: Hỗ trợ multiple webhook versions để dễ update

📌 Checklist trước deploy

• [ ] Authorization header được kiểm tra
• [ ] JSON validation đầy đủ
• [ ] Response 200 được trả về luôn
• [ ] Logging được cấu hình
• [ ] Database transaction được dùng
• [ ] Error handling cho timeout/network error
• [ ] Endpoint có HTTPS (nếu production)
• [ ] Rate limiting được setup
• [ ] Webhook được test với Postman/curl
• [ ] Alert/monitoring được cấu hình

Yêu cầu lập hóa đơn từ phản hồi Webhook

Endpoint có thể yêu cầu Pay2S lập hóa đơn điện tử cho giao dịch tiền vào bằng cách trả thêm metadata hóa đơn. Cấu trúc request Pay2S gửi đến endpoint không thay đổi. Nếu không sử dụng tính năng hóa đơn, endpoint tiếp tục phản hồi như hiện tại:

{
  "success": true
}

Nếu muốn yêu cầu Pay2S lập hóa đơn cho giao dịch vừa nhận, thêm invoiceMetadata vào cùng response:

{
  "success": true,
  "invoiceMetadata": {
    "invoiceType": "regular",
    "invoiceOptions": {
      "requested": true,
      "buyerNotTakingInvoice": false,
      "paymentMethod": "TM/CK"
    },
    "customerInfo": {
      "buyerContactName": "Nguyễn Văn A",
      "buyerCompanyName": "",
      "taxCode": "",
      "citizenId": "079123456789",
      "address": "TP. Hồ Chí Minh",
      "email": "[email protected]",
      "phone": "0900000000"
    },
    "items": [
      {
        "itemCode": "SP001",
        "itemGroupCode": "NHOM_SAN_PHAM",
        "itemName": "Sản phẩm A",
        "unit": "Cái",
        "quantity": 1,
        "unitPrice": 50000,
        "taxRate": -1
      }
    ]
  }
}

Lưu ý:

• Pay2S chỉ tiếp nhận metadata khi response có HTTP 2xx và success: true.
• Tài khoản phải sử dụng gói Basic trở lên, đã kích hoạt tính năng hóa đơn điện tử và bật Nhận thông tin xuất hóa đơn khi thêm hoặc sửa webhook; webhook chưa bật hoặc tài khoản không còn gói hợp lệ sẽ bỏ qua invoiceMetadata.
• Mỗi tài khoản ngân hàng chỉ được chọn một webhook để nhận thông tin xuất hóa đơn.
• Chỉ giao dịch tiền vào (transferType: "IN") với số tiền lớn hơn 0 được đưa vào hàng chờ hóa đơn.
• invoiceOptions.requested phải là true.
• items phải có từ 1 đến 50 dòng.
• Nên gửi itemCode ở mỗi dòng hàng hóa. Pay2S dùng mã này để khớp với Quy tắc sản phẩm; nếu không khớp thì giữ nguyên tên, đơn vị và thuế suất trong response.
• itemGroupCode là mã nhóm tùy chọn. Với response webhook, quy tắc có nguồn webhook hoặc any được áp dụng; quy tắc riêng cửa hàng ưu tiên hơn quy tắc toàn tài khoản, mã sản phẩm ưu tiên hơn mã nhóm.
• taxRate nhận một trong các giá trị: -2, -1, 0, 3.5, 5, 8, 10.
• buyerNotTakingInvoice: true dùng cho người mua không lấy hóa đơn. Nếu có MST hoặc CCCD, Pay2S vẫn ưu tiên thông tin định danh.
• Pay2S chống tạo trùng theo ID giao dịch ngân hàng; endpoint có thể nhận lại cùng một webhook nhưng không sinh thêm yêu cầu hóa đơn.
• Lỗi riêng của invoiceMetadata không làm thay đổi trạng thái tiếp nhận webhook giao dịch. Doanh nghiệp cần kiểm tra màn hình hóa đơn/đối soát để xử lý metadata bị từ chối.

Điều kiện để Pay2S tiếp nhận yêu cầu hóa đơn

Pay2S chỉ tạo yêu cầu hóa đơn khi đồng thời thỏa các điều kiện sau:

1. Endpoint trả HTTP 2xx, JSON hợp lệ và success bằng true.
2. Phản hồi có invoiceMetadata.invoiceOptions.requested: true.
3. Webhook nhận giao dịch tiền vào và đã bật Nhận thông tin xuất hóa đơn từ phản hồi webhook.
4. Tài khoản Pay2S đang dùng gói Basic trở lên và đã được bật tính năng hóa đơn điện tử.
5. Giao dịch có transferType: "IN" và transferAmount lớn hơn 0.
6. items có từ 1 đến 50 dòng và từng dòng vượt qua kiểm tra dữ liệu bên dưới.

Nếu chỉ muốn xác nhận đã nhận giao dịch mà không yêu cầu lập hóa đơn, giữ nguyên phản hồi { "success": true } hoặc đặt requested: false.

Chi tiết các tham số phản hồi

Đối tượng gốc

invoiceMetadata

Tổng dung lượng JSON của riêng invoiceMetadata không được vượt quá 32 KB.

invoiceOptions

customerInfo

Mỗi phần tử trong items

Không dùng chuỗi như "5%" cho taxRate hoặc directVatRate; hãy truyền số 5. Không gửi giá trị tiền đã định dạng như "50.000 đ"; hãy truyền số 50000.

Đấu nối với Quy tắc sản phẩm

Quy tắc sản phẩm giúp dữ liệu từ website, POS, WHMCS, WooCommerce hoặc ứng dụng riêng được chuẩn hóa trước khi đưa lên hóa đơn. Quy tắc có thể thay tên hàng, mã hàng, đơn vị tính, thuế suất và cấu hình giảm thuế mà không buộc hệ thống nguồn phải biết định dạng riêng của từng nhà cung cấp hóa đơn.

Bước 1: Chọn mã đối chiếu ổn định

• itemCode phải đại diện cho loại sản phẩm, ví dụ POS_DRINK_001 hoặc API_PRODUCT_HOSTING_BASIC.
• itemGroupCode đại diện cho nhóm sản phẩm, ví dụ POS_DRINK hoặc API_GROUP_HOSTING.
• Không dùng Order ID, ID giao dịch ngân hàng hoặc ID riêng của từng dòng đơn hàng vì các mã này thay đổi sau mỗi lần bán và sẽ không tái sử dụng được quy tắc.
• Cùng một sản phẩm phải luôn trả cùng itemCode, kể cả tên hiển thị hoặc giá bán thay đổi.

Bước 2: Tạo quy tắc trong Pay2S

Mở Hóa đơn điện tử → kết nối nhà cung cấp → Hàng hóa / Quy tắc sản phẩm, sau đó:

1. Chọn Nguồn tích hợp là Webhook cho dữ liệu phản hồi webhook; chọn Mọi nguồn nếu muốn dùng chung quy tắc cho các luồng khác.
2. Chọn Mã sản phẩm để đối chiếu itemCode, Mã nhóm sản phẩm để đối chiếu itemGroupCode, hoặc Tên sản phẩm khi hệ thống nguồn không có mã ổn định.
3. Với mã, nhập chính xác mã nguồn gửi lên. Với tên, Pay2S khớp toàn bộ sau khi bỏ khoảng trắng thừa và không phân biệt chữ hoa/thường; tên có dấu và không dấu vẫn là hai giá trị khác nhau.
4. Chọn phạm vi toàn tài khoản hoặc một cửa hàng cụ thể.
5. Khai báo tên, mã, đơn vị, thuế suất và chính sách giảm thuế muốn hiển thị trên hóa đơn.
6. Lưu quy tắc rồi gửi một giao dịch thử; kiểm tra kết quả tại Hàng chờ trước khi bật tự phát hành.

Thứ tự ưu tiên khi nhiều quy tắc cùng khớp

Pay2S chọn đúng một quy tắc theo thứ tự:

1. Quy tắc của cửa hàng hiện tại ưu tiên hơn quy tắc toàn tài khoản.
2. Quy tắc nguồn webhook ưu tiên hơn nguồn any (Mọi nguồn).
3. Trong cùng phạm vi và nguồn: quy tắc theo itemCode ưu tiên hơn itemGroupCode, và itemGroupCode ưu tiên hơn tên sản phẩm.
4. Nếu vẫn bằng nhau, quy tắc được tạo sau cùng (ID lớn hơn) được chọn.

Ví dụ endpoint trả:

{
  "itemCode": "POS_DRINK_001",
  "itemGroupCode": "POS_DRINK",
  "itemName": "nuoc ngot lon",
  "unit": "item",
  "quantity": 2,
  "unitPrice": 15000,
  "taxRate": 0
}

Và Pay2S có quy tắc POS_DRINK_001 đổi thành Nước ngọt lon, đơn vị Lon, thuế suất 8%, hóa đơn sẽ dùng dữ liệu đã chuẩn hóa từ quy tắc. Số lượng và đơn giá vẫn lấy từ giao dịch hiện tại. Nếu không có quy tắc nào khớp, Pay2S giữ itemName, unit và taxRate trong response; yêu cầu không bị từ chối chỉ vì thiếu quy tắc.

Quy trình kiểm thử khuyến nghị

1. Tạo kết nối nhà cung cấp ở môi trường thử nghiệm và kiểm tra kết nối thành công.
2. Đồng bộ mẫu hóa đơn, chọn mẫu mặc định và gán đúng cửa hàng.
3. Bật Nhận thông tin xuất hóa đơn từ phản hồi webhook cho webhook nhận tiền vào.
4. Cho endpoint trả một invoiceMetadata có một mặt hàng và tổng quantity × unitPrice bằng số tiền giao dịch.
5. Kiểm tra bản ghi xuất hiện ở Hàng chờ, xem thông tin người mua và hàng hóa đã được Quy tắc sản phẩm chuẩn hóa đúng chưa.
6. Tạo bản nháp, kiểm tra PDF và tổng tiền; sau khi ổn định mới bật tự tạo nháp hoặc tự phát hành.
7. Theo dõi Đối soát và Nhật ký khi có chênh lệch hoặc lỗi nhà cung cấp.

Các lỗi thường gặp

Request và response đối chiếu ngày 11/10/2026

Các mẫu dưới đây giữ cấu trúc trường và kiểu dữ liệu. Khóa, chữ ký, URL phiên đã được thay bằng placeholder; danh sách chỉ giữ tối đa hai phần tử và dữ liệu ảnh/PDF/XML dài được rút gọn. Không sao chép placeholder để gọi API thật.

Webhook giao dịch · Payload & ACK

Đối chiếu mã nguồn backend; giá trị minh họa. Đối chiếu webhooksender.js và immediate-account-webhook.js. paymentCode có khi trích được mã khớp mẫu; extraData chỉ có khi bật dữ liệu bổ sung. Giá trị là minh họa.

POST {webhook_url}

Body:

{
  "transactions": [
    {
      "id": 10001,
      "gateway": "ACB",
      "transactionDate": "2026-10-11 09:00:00",
      "transactionNumber": "DEMO10001",
      "accountNumber": "P2S99999999",
      "content": "THANHTOAN DH10001",
      "transferType": "IN",
      "transferAmount": 2000,
      "checksum": "demo-user-webhook-10001",
      "paymentCode": "DH10001",
      "extraData": {
        "remitterName": "NGUYEN VAN A",
        "remitterAccountNumber": "0123456789",
        "issuerBankName": "Ngan hang TMCP Quan Doi",
        "reciprocalBankCode": "970422"
      }
    }
  ]
}

HTTP 200. Response:

{
  "success": true
}