Bỏ qua để đến nội dung
Tài liệu

Tích hợp WooCommerce (WordPress Plugin)

~3 phút đọc

Plugin Dòng Tiền Pro cho WooCommerce (dongtien-pay) kết nối website bán hàng WordPress của bạn với nền tảng Dòng Tiền Pro, hỗ trợ tạo mã VietQR động theo từng đơn hàng và tự động gạch nợ trong 5-10 giây ngay khi giao dịch được xác thực.

Tính năng nổi bật

Phần tiêu đề “Tính năng nổi bật”
  • Tự động gạch nợ 5-10s: Nhận diện giao dịch ngân hàng theo mã DTP... và cập nhật đơn hàng sang trạng thái processing (Đang xử lý) theo thời gian thực.
  • Tương thích 100% Checkout Blocks & HPOS: Được kiểm thử đầy đủ trên WooCommerce 9.x với WooCommerce Checkout Blocks (Gutenberg) và High-Performance Order Storage (custom_order_tables).
  • Bảo mật chuẩn Standard Webhooks: Xác thực chữ ký số HMAC-SHA256 (webhook-signature, webhook-timestamp, webhook-id) với cửa sổ dung sai thời gian 5 phút chống tấn công phát lại.
  • Không bao giờ tin tưởng tiền tạm tính: Giao dịch chỉ được gạch nợ khi đã đạt mức tin cậy verified. Giao dịch provisional sẽ chỉ ghi chú cảnh báo, bảo vệ cửa hàng trước các hành vi giả mạo thông báo.
  • Kiểm tra thiếu/thừa tiền tự động: Khách chuyển thiếu tiền sẽ giữ nguyên trạng thái on-hold và ghi rõ số tiền còn thiếu vào Order Note.

Yêu cầu hệ thống

Phần tiêu đề “Yêu cầu hệ thống”
  • PHP: 8.1 trở lên.
  • WordPress: 6.5 trở lên.
  • WooCommerce: 9.0 trở lên.
  • HTTPS: Bắt buộc trên môi trường production để bảo mật kết nối webhook và API.

Hướng dẫn cài đặt

Phần tiêu đề “Hướng dẫn cài đặt”

  1. Tải plugin: Tải gói dongtien-pay.zip từ trang Quản trị Dòng Tiền Pro (mục Tích hợp > WooCommerce) hoặc kho lưu trữ WordPress.org.

  2. Cài đặt vào WordPress: Vào WordPress Admin > Plugins (Gói mở rộng) > Add New (Cài mới) > Upload Plugin (Tải gói mở rộng lên), chọn file dongtien-pay.zip và bấm Install Now (Cài đặt ngay). Sau khi cài đặt xong, bấm Activate (Kích hoạt).

  3. Cấu hình kết nối: Vào WooCommerce > Cài đặt > Thanh toán > Dòng Tiền Pro (VietQR).

    • Cách 1 (Khuyên dùng): Bấm nút Kết nối 1 bước với Dòng Tiền Pro. Hệ thống sẽ chuyển hướng bạn đến console xác thực và tự động điền Khoá API cùng Webhook Secret.
    • Cách 2: Dán thủ công Khoá API (dt_live_...) và Webhook Secret (whsec_...) được cấp tại mục Nhà phát triển trên Dòng Tiền Pro.

  4. Chọn tài khoản nhận tiền: Điền mã hoặc bí danh tài khoản nhận tiền (ví dụ: acb_4521). Khách hàng quét QR sẽ chuyển tiền trực tiếp vào tài khoản này mà không qua bất kỳ tài khoản trung gian nào.

  5. Lưu cấu hình & Thử nghiệm: Bấm Lưu thay đổi. Đặt thử một đơn hàng trên giỏ hàng và quét mã VietQR bằng app ngân hàng để kiểm tra gạch nợ tự động.

Cấu trúc Endpoint Webhook

Phần tiêu đề “Cấu trúc Endpoint Webhook”

Webhook nhận biến động thanh toán từ Dòng Tiền Pro được đăng ký tự động tại:

POST https://cuanhang.com/wp-json/dongtien/v1/payments

Headers bảo mật:

Phần tiêu đề “Headers bảo mật:”
  • webhook-id: Mã thông điệp duy nhất (ví dụ: msg_2LqXUqT5xV60NfE8uG0)
  • webhook-timestamp: Dấu thời gian Unix Epoch (giây)
  • webhook-signature: Chữ ký HMAC-SHA256 chuẩn Standard Webhooks dạng v1,...