PAY2S 1.3.6 — TÍN HIỆU CHO GTM / PIXEL

1. EVENT TRÌNH DUYỆT
Plugin tự push vào window.dataLayer và phát CustomEvent cùng tên trên window:
- pay2s_order_created: tạo phiên thanh toán thành công; chưa nhận tiền.
- pay2s_payment_success: backend đã xác nhận nhận tiền qua IPN hợp lệ.
- pay2s_payment_failed: IPN báo lỗi, hoặc đơn WooCommerce ở trạng thái failed/cancelled.
- pay2s_payment_confirmed: tên cũ của sự kiện thành công, giữ cho tích hợp cũ.

CHỈ dùng pay2s_payment_success HOẶC pay2s_payment_confirmed để kích hoạt Purchase. Không gắn cả hai tag Purchase vì chúng cùng một chuyển đổi.
Không phát thất bại vì đóng trang, quá thời gian polling, lỗi mạng hoặc đang chờ tiền. Hoàn tiền không được coi là thất bại thanh toán và không phát Purchase mới.

Ví dụ dữ liệu thành công:
{
  "event": "pay2s_payment_success",
  "event_id": "pay2s_payment_confirmed_1311",
  "order_id": 1311,
  "transaction_id": "1311",
  "value": 2000,
  "currency": "VND",
  "status": "success",
  "reason_code": "",
  "reason": ""
}
Tên event_id giữ định dạng cũ để phía server/browser cùng dùng một mã chuyển đổi.
Thất bại có status=failed; reason_code ví dụ GATEWAY_9, ORDER_CANCELLED hoặc PAYMENT_FAILED; reason là mô tả ngắn không chứa thông tin đăng nhập/khách hàng.

2. CẤU HÌNH GTM
- Tạo Data Layer Variables: event_id, order_id, transaction_id, value, currency, status, reason_code, reason.
- Tạo Custom Event trigger tên chính xác pay2s_payment_success.
- Gắn trigger vào tag Meta Pixel Purchase hiện có của shop. Ánh xạ value, currency và Event ID từ các biến tương ứng.
- Dùng pay2s_payment_failed cho tag sự kiện tùy chỉnh theo nhu cầu; KHÔNG gắn Purchase.
- Dùng pay2s_order_created để ghi nhận tạo đơn; KHÔNG coi là đã thanh toán.
- Shop quản lý việc tải Pixel/GTM và consent. Plugin không tự thêm Pixel ID hay tự gửi dữ liệu sang Meta.
- Không dùng trang thank-you được mở trực tiếp hoặc URL do trình duyệt cung cấp làm bằng chứng đã thanh toán.

3. TÍN HIỆU SERVER
Các PHP action đều nhận ($order_id, $event):
  pay2s_payment_created
  pay2s_payment_success
  pay2s_payment_failed
Tên cũ pay2s_payment_confirmed vẫn có, dùng một trong hai hook success cho cùng đích nhận.
Ví dụ:
add_action('pay2s_payment_success', function ($order_id, $event) {
    // Đưa vào queue của bên tích hợp để gửi chuyển đổi tới Meta CAPI.
    // Dùng $event['event_id'] làm mã chống trùng cùng browser.
}, 10, 2);
Đây là điểm nối, KHÔNG phải triển khai CAPI. Bên tích hợp cần Pixel ID/access token, queue có retry, thông tin attribution phù hợp và cơ chế consent của shop.
Hook server thành công vẫn chạy khi khách đã đóng trình duyệt. Browser chỉ nhận event khi trang thanh toán hoặc trang quay về đang mở.
Chống trùng callback lặp tuần tự trong plugin; phía nhận vẫn phải dedup event_id, kể cả callback đồng thời. Browser dùng localStorage để chống phát lại sau reload; đây không phải biên nhận Meta và không bảo đảm tag đã gửi thành công.
Event thất bại có thể được theo sau bởi thành công nếu đơn được thanh toán lại/xác nhận muộn. Callback thất bại tới sau thành công không được ghi đè kết quả đã nhận tiền.

4. KIỂM TRA TÍCH HỢP
Dùng GTM Preview trên website staging:
- Tạo đơn: chỉ có pay2s_order_created, không có Purchase.
- Nhận IPN thành công: có pay2s_payment_success; tag Purchase kích hoạt một lần.
- Reload: không phát lại kết quả trong cùng trình duyệt còn localStorage.
- Hủy đơn/chạy tình huống lỗi: có pay2s_payment_failed kèm reason_code, không có Purchase.
- Ngắt mạng polling: không xuất hiện event thất bại.
- Cả onsite và quay về từ Pay2S đều sử dụng cùng tên event.
Không chia sẻ URL trang thanh toán có order key. Không cần gửi key/token hay thông tin cá nhân vào Pixel.

TỪ 1.3.6: Mặc định hiện bảng thành công ngay trên trang thanh toán, rồi mới phát pay2s_payment_success; không tự chuyển trang. Nếu shop chọn URL cảm ơn riêng thì chuyển sau 1,5 giây.
