Plugin WooCommerce
1. Tổng quan
Plugin GLODIPAY WooCommerce tích hợp cổng thanh toán GLODIPAY vào WooCommerce, cho phép merchant chấp nhận thanh toán bằng thẻ tín dụng/ghi nợ thông qua một nền tảng thống nhất.
Phương thức thanh toán được hỗ trợ:
- Visa / Mastercard / JCB / Amex / Diners / Maestro / Discover
Tương thích checkout:
- WooCommerce Classic Checkout
- WooCommerce Block Checkout (Gutenberg)
2. Yêu cầu hệ thống
| Yêu cầu | Phiên bản tối thiểu |
|---|---|
| WordPress | 5.8+ |
| WooCommerce | 7.0+ |
| PHP | 7.4+ |
| OpenSSL | Bắt buộc |
OpenSSL là thư viện bảo mật được plugin sử dụng để ký yêu cầu thanh toán và xác thực tính xác thực của webhook. Thư viện này được cài đặt sẵn trên hầu hết các nhà cung cấp hosting (cPanel, WP Engine, Cloudways, SiteGround, v.v.) — không cần thao tác thêm. Để kiểm tra: WordPress Admin → Tools → Site Health → Info → Server và tìm mục OpenSSL.
Yêu cầu máy chủ để nhận webhook:
- Website của merchant phải có thể truy cập công khai từ internet
- Bắt buộc sử dụng HTTPS
- Không chặn IP/địa lý trên endpoint webhook
/?wc-api=glodipay_webhook
3. Cài đặt
Điều kiện tiên quyết
Luôn sao lưu website trước khi cài đặt hoặc cập nhật bất kỳ plugin nào.
Bước 1: Tải plugin
Liên hệ GLODIPAY để nhận file ZIP của plugin.
Bước 2: Đăng nhập vào WordPress Admin
Truy cập https://yoursite.com/wp-admin
Bước 3: Vào trang thêm plugin
Plugins → Add New Plugin
Bước 4: Tải lên plugin
Nhấp "Upload Plugin" ở đầu trang Add Plugins.
Bước 5: Chọn file ZIP
Chọn file ZIP nhận được từ GLODIPAY.
Bước 6: Cài đặt
Sau khi chọn file ZIP, nhấp "Install Now" để tiến hành.
WordPress sẽ cài đặt plugin từ file ZIP vừa tải lên.
Bước 7: Kích hoạt
Nhấp "Activate Plugin" sau khi quá trình cài đặt hoàn tất.
Hoặc kích hoạt từ Plugins → Installed Plugins → GLODIPAY Payment Gateway → Activate.
Bước 8: Xác nhận
Truy cập trang checkout để xác nhận tùy chọn thanh toán GLODIPAY đã xuất hiện.
4. Cấu hình
Bước 1: Truy cập GLODIPAY Merchant
- Đăng nhập vào tài khoản Merchant tại GLODIPAY Merchant
- Đảm bảo đã xác minh email và hoàn tất KYB
- Vào API Keys từ menu bên trái
Bước 2: Lấy API Keys
Từ mục API Keys, sao chép:
| Khóa | Mô tả |
|---|---|
| Merchant ID | Mã định danh merchant duy nhất |
| Base Endpoint | URL API cơ sở (sandbox hoặc production) |
| RSA Public Key | Dùng để xác thực chữ ký webhook |
| RSA Private Key | Dùng để ký yêu cầu thanh toán |
| Expiration Date | Ngày hết hạn của khóa |
Bước 3: Cấu hình plugin trong WordPress
Truy cập theo một trong hai cách:
- Cách 1: Plugins → GLODIPAY Payment Gateway → Settings
- Cách 2: WooCommerce → Settings → Payments → GLODIPAY Payment Gateway → Manage
4.1 Cài đặt cơ bản
| Cài đặt | Mô tả | Mặc định |
|---|---|---|
| Enable/Disable | Kích hoạt cổng thanh toán | Enabled |
| Sandbox Mode | Chuyển đổi giữa Sandbox (thử nghiệm) và Production (thực tế) | Disabled |
| Thank You Page URL | URL chuyển hướng tùy chỉnh sau thanh toán. Để trống để dùng mặc định của WooCommerce | (trống) |
Quan trọng: Luôn kiểm thử trong Sandbox Mode trước khi chuyển sang Production.
4.2 API Keys
Cài đặt Sandbox
| Trường | Mô tả |
|---|---|
| Sandbox Merchant ID | Merchant ID cho môi trường thử nghiệm |
| Sandbox RSA Public Key | Public key cho sandbox |
| Sandbox RSA Private Key | Private key cho sandbox |
| Sandbox Base URL | Mặc định: https://checkout-sandbox.glodipayprocessing.com |
Cài đặt Production
| Trường | Mô tả |
|---|---|
| Production Merchant ID | Merchant ID cho môi trường thực tế |
| Production RSA Public Key | Public key cho production |
| Production RSA Private Key | Private key cho production |
| Production Base URL | Do GLODIPAY cung cấp |
4.3 Nút thao tác trên Payment Iframe
Tùy chỉnh các nút hiển thị trên overlay thanh toán.
Nút Refresh
| Trường | Mô tả | Mặc định |
|---|---|---|
| Show Refresh Button | Hiển thị nút refresh trên iframe | Yes |
| Refresh Button Text | Văn bản nhãn nút | Refresh |
| Refresh Button Color | Màu nền nút (hex) | #0073aa |
Nút Cancel
| Trường | Mô tả | Mặc định |
|---|---|---|
| Show Cancel Button | Hiển thị nút hủy trên iframe | Yes |
| Cancel Button Text | Văn bản nhãn nút | Cancel |
| Cancel Button Color | Màu nền nút (hex) | #dc3232 |
4.4 Cài đặt Debug
| Cài đặt | Mô tả | Mặc định |
|---|---|---|
| Enable Debug Mode | Ghi log thông tin thanh toán chi tiết vào WooCommerce Logger | No |
| Block Checkout Debug | Ghi log bổ sung cho các sự cố Block Checkout | No |
Lưu ý: Chỉ bật debug mode khi cần xử lý sự cố. Tắt trước khi chuyển sang môi trường production.
Khi debug mode được bật, log có thể xem tại: WooCommerce → Status → Logs
5. Luồng thanh toán
5.1 Luồng Classic Checkout
Khách hàng điền form checkout
↓
Chọn GLODIPAY làm phương thức thanh toán
↓
Nhấp "Place Order"
↓
WooCommerce tạo đơn hàng (trạng thái: pending)
↓
Plugin kết nối GLODIPAY Gateway để tạo thanh toán
↓
Form thanh toán hiển thị trong overlay ở cuối trang
↓
Khách hàng hoàn tất thanh toán trong overlay
↓
GLODIPAY thông báo kết quả thanh toán cho plugin
↓
Plugin cập nhật trạng thái đơn hàng
↓
Khách hàng được chuyển hướng đến trang Xác nhận → trang Cảm ơn
5.2 Luồng Block Checkout (Gutenberg)
Áp dụng khi trang checkout được xây dựng bằng WooCommerce Blocks (Gutenberg editor):
Khách hàng điền form checkout
↓
Chọn GLODIPAY làm phương thức thanh toán
↓
Nhấp "Place Order"
↓
Plugin kết nối GLODIPAY Gateway để tạo thanh toán
↓
Form thanh toán hiển thị trong overlay ở cuối trang
↓
(giống Classic Checkout từ đây)
5.3 Overlay Payment Iframe
Khi thanh toán được khởi tạo, một panel thanh toán trượt lên từ cuối màn hình, bao gồm:
- Tiêu đề: "Complete Your Payment"
- Nút Refresh — tải lại form thanh toán (có thể cấu hình)
- Nút Cancel — hủy thanh toán và tải lại trang (có thể cấu hình)
- Thông báo cảnh báo: "Transaction takes a few seconds to process. Don't close the page."
- Form thanh toán — form thanh toán GLODIPAY được nhúng
Nếu khách hàng vô tình đóng hoặc làm mới trang, panel thanh toán sẽ tự động xuất hiện lại.
5.4 Thông tin gửi đến GLODIPAY
Khi thanh toán được khởi tạo, plugin tự động thu thập và gửi các thông tin sau từ đơn hàng WooCommerce đến GLODIPAY:
- Thông tin đơn hàng (mã tham chiếu, số tiền, tiền tệ)
- Thông tin thanh toán của khách hàng (tên, email, số điện thoại, địa chỉ)
- Thông tin giao hàng (nếu khác địa chỉ thanh toán)
- URL trả về và thông báo thanh toán
- Logo website và địa chỉ IP của khách hàng
Không cần thao tác thủ công — plugin xử lý tự động.
6. Trang xác nhận
Sau khi hoàn tất thanh toán trong overlay, khách hàng được chuyển hướng đến trang xác nhận hiển thị kết quả giao dịch.
Nội dung trang xác nhận
- Mã giao dịch
- Phương thức thanh toán đã dùng
- Trạng thái giao dịch
Polling trạng thái
Nếu kết quả thanh toán chưa có:
- Trang tự động làm mới sau mỗi 5 giây
- Tối đa 10 lần thử
- Sau 10 lần thử không có kết quả → khách hàng được chuyển đến trang Cảm ơn
Nếu thanh toán thành công:
- Nút "Continue" xuất hiện với đếm ngược 30 giây
- Trang tự động chuyển hướng đến trang Cảm ơn sau khi hết đếm ngược
Trang Cảm ơn
Khách hàng được chuyển hướng đến:
- URL tùy chỉnh được đặt trong Thank You Page URL (cài đặt plugin), nếu đã cấu hình
- Nếu không, trang xác nhận đơn hàng mặc định của WooCommerce
Màu trạng thái
| Trạng thái | Màu |
|---|---|
successful | Xanh lá |
failed | Đỏ |
error | Đỏ |
under_review | Cam |
7. Tích hợp Webhook
Webhook là thông báo tự động mà GLODIPAY gửi đến website của bạn khi trạng thái thanh toán thay đổi. Plugin nhận thông báo này và cập nhật đơn hàng WooCommerce tương ứng.
7.1 URL Webhook
GLODIPAY gửi thông báo thanh toán đến:
https://yoursite.com/?wc-api=glodipay_webhook&order_id=123
URL này được plugin tự động cấu hình khi tạo thanh toán. Không cần thiết lập thủ công.
7.2 Xác thực chữ ký
Tất cả thông báo webhook được GLODIPAY ký số để xác nhận tính xác thực.
Plugin tự động xác thực chữ ký trên mỗi thông báo đến bằng RSA Public Key đã cấu hình trong cài đặt plugin. Không cần thao tác thủ công.
Nếu chữ ký không hợp lệ: Thông báo bị từ chối và trạng thái đơn hàng không được cập nhật. Nếu đơn hàng vẫn kẹt ở pending sau khi thanh toán thành công, hãy kiểm tra lại RSA Public Key trong cấu hình plugin.
7.3 Nội dung thông báo Webhook
Khi GLODIPAY gửi thông báo, nó bao gồm các thông tin sau. Plugin xử lý tự động — merchant không cần thao tác.
| Thông tin | Mô tả |
|---|---|
| Mã tham chiếu đơn hàng | Liên kết thông báo với đơn hàng WooCommerce đúng |
| Trạng thái giao dịch | Kết quả thanh toán (successful, failed, under review) |
| Transaction ID | Mã định danh giao dịch nội bộ của GLODIPAY |
| Mã giao dịch | Mã giao dịch dễ đọc |
| Số tiền | Số tiền thanh toán |
| Tiền tệ | Loại tiền tệ |
| Số tiền đã nhận | Số tiền thực tế nhận được |
| Số tiền quyết toán | Số tiền sau khi trừ phí |
| Chi tiết phương thức thanh toán | Thông tin thẻ hoặc phương thức thanh toán |
| Phí | Chi tiết phí |
7.4 Phản hồi Webhook
Plugin tự động gửi xác nhận lại cho GLODIPAY sau mỗi lần nhận thông báo. GLODIPAY dùng xác nhận này để đánh dấu thông báo đã gửi thành công.
7.5 Yêu cầu máy chủ Merchant
Quan trọng: Webhook sẽ không gửi được nếu GLODIPAY không thể kết nối đến website của bạn.
Nguyên nhân phổ biến gây lỗi webhook:
| Nguyên nhân | Triệu chứng | Giải pháp |
|---|---|---|
| Website không thể truy cập công khai | Đơn hàng kẹt ở pending sau thanh toán; không có log | Đảm bảo website có domain công khai và SSL hợp lệ |
| DNS chưa lan truyền | Webhook không đến ngay sau khi đổi domain | Chờ DNS lan truyền hoặc kiểm tra bằng công cụ DNS lookup |
| Chặn IP/địa lý trên website merchant | Webhook từ GLODIPAY bị chặn | Whitelist IP máy chủ GLODIPAY Gateway trong firewall hoặc plugin bảo mật |
| Firewall chặn kết nối đến | Webhook không bao giờ đến | Cho phép kết nối vào từ tất cả IP ngoài trên URL webhook |
| Website yêu cầu VPN hoặc truy cập hạn chế | GLODIPAY không thể kết nối đến website | Bỏ hạn chế truy cập trên /?wc-api=glodipay_webhook |
Cách kiểm tra website có thể truy cập: Mở URL sau trong trình duyệt hoặc công cụ bên ngoài để xác nhận có phản hồi:
https://yoursite.com/?wc-api=glodipay_webhook
Cách whitelist IP GLODIPAY Gateway: Liên hệ GLODIPAY support để lấy danh sách IP máy chủ Gateway hiện tại, sau đó thêm vào allowlist trong Cloudflare, firewall, hoặc plugin bảo mật.
8. Ánh xạ trạng thái đơn hàng
Khi GLODIPAY gửi thông báo thanh toán, plugin tự động cập nhật đơn hàng WooCommerce sang trạng thái tương ứng:
| Trạng thái GLODIPAY | Trạng thái đơn hàng WooCommerce | Mô tả |
|---|---|---|
successful | Processing | Đơn hàng xác nhận; giảm tồn kho; xóa giỏ hàng |
failed | Failed | Thanh toán thất bại; không thay đổi tồn kho |
under_review | On Hold | Thanh toán đang xem xét; đơn hàng giữ chờ kiểm tra thủ công |
refund_successful | Không đổi | GLODIPAY đã hoàn tiền — trạng thái WooCommerce không tự động cập nhật |
refund_partially_successful | Không đổi | GLODIPAY đã hoàn tiền một phần — trạng thái WooCommerce không tự động cập nhật |
Hoàn tiền: Khi hoàn tiền được thực hiện qua GLODIPAY Merchant, trạng thái đơn hàng WooCommerce không tự động thay đổi. Bạn cần cập nhật trạng thái đơn hàng thủ công và xử lý bản ghi hoàn tiền tại WooCommerce Admin → Orders.
9. Xác thực trường checkout
Plugin xác thực các trường thanh toán và giao hàng khi khách hàng đặt hàng. Việc xác thực này áp dụng cho tất cả phương thức thanh toán — không chỉ GLODIPAY.
Quan trọng: Nếu một trường bắt buộc bị xóa hoặc vô hiệu hóa khỏi trang checkout, khách hàng sẽ không thể hoàn tất bất kỳ đơn hàng nào bất kể phương thức thanh toán được chọn.
9.1 Trường thanh toán bắt buộc
Các trường sau phải có mặt và được kích hoạt trên trang checkout:
| Trường | Field ID | Độ dài tối đa | Ghi chú |
|---|---|---|---|
| Tên | billing_first_name | 255 ký tự | Bắt buộc |
| Họ | billing_last_name | 255 ký tự | Bắt buộc |
billing_email | 255 ký tự | Bắt buộc, phải đúng định dạng email | |
| Số điện thoại | billing_phone | 5–20 ký tự | Bắt buộc, tối thiểu 5 ký tự |
| Địa chỉ dòng 1 | billing_address_1 | 255 ký tự | Bắt buộc |
| Thành phố | billing_city | 255 ký tự | Bắt buộc |
| Quốc gia | billing_country | — | Bắt buộc |
Số điện thoại: Trường số điện thoại yêu cầu tối thiểu 5 ký tự. Nếu khách hàng nhập số điện thoại ngắn hơn 5 ký tự, checkout sẽ thất bại. Đảm bảo form checkout không cho phép nhập số điện thoại quá ngắn.
9.2 Trường thanh toán tùy chọn
Các trường này có thể ẩn nếu không cần. Chúng được gửi đến GLODIPAY nếu được điền, nhưng không bắt buộc để hoàn tất đơn hàng.
| Trường | Field ID | Độ dài tối đa |
|---|---|---|
| Địa chỉ dòng 2 | billing_address_2 | 255 ký tự |
| Tỉnh/Vùng | billing_state | 255 ký tự |
| Mã bưu chính | billing_postcode | 25 ký tự |
9.3 Giới hạn trường giao hàng
Trường giao hàng chỉ được xác thực khi khách hàng chọn "Ship to a different address". Bỏ qua nếu khách hàng dùng địa chỉ thanh toán để giao hàng.
| Trường | Field ID | Độ dài tối đa |
|---|---|---|
| Tên | shipping_first_name | 250 ký tự |
| Họ | shipping_last_name | 250 ký tự |
| Địa chỉ dòng 1 | shipping_address_1 | 250 ký tự |
| Địa chỉ dòng 2 | shipping_address_2 | 250 ký tự |
| Thành phố | shipping_city | 250 ký tự |
| Tỉnh/Vùng | shipping_state | 20 ký tự |
| Mã bưu chính | shipping_postcode | 10 ký tự |
9.4 Tương thích tùy chỉnh checkout
Dùng plugin Checkout Field Editor
Nếu bạn dùng plugin như Checkout Field Editor for WooCommerce để tùy chỉnh trường checkout:
| Thao tác | Field ID | Ảnh hưởng | Khuyến nghị |
|---|---|---|---|
| Ẩn/tắt Số điện thoại | billing_phone | Chặn checkout với tất cả phương thức thanh toán | Giữ hiển thị và bắt buộc |
| Ẩn/tắt Tên | billing_first_name | Checkout có thể thất bại; thiếu dữ liệu thanh toán | Giữ kích hoạt |
| Ẩn/tắt Họ | billing_last_name | Checkout có thể thất bại; thiếu dữ liệu thanh toán | Giữ kích hoạt |
| Ẩn/tắt Email | billing_email | Checkout có thể thất bại; thiếu dữ liệu thanh toán | Giữ kích hoạt |
| Ẩn/tắt Địa chỉ dòng 1 | billing_address_1 | Checkout có thể thất bại; thiếu dữ liệu thanh toán | Giữ kích hoạt |
| Ẩn/tắt Thành phố | billing_city | Checkout có thể thất bại; thiếu dữ liệu thanh toán | Gi ữ kích hoạt |
| Ẩn Địa chỉ dòng 2 | billing_address_2 | Không lỗi — có thể ẩn | Cho phép |
| Ẩn Tỉnh/Vùng | billing_state | Không lỗi — có thể ẩn | Cho phép |
| Ẩn Mã bưu chính | billing_postcode | Không lỗi — có thể ẩn | Cho phép |
| Sắp xếp lại trường | — | Không ảnh hưởng | Cho phép |
| Đổi nhãn trường | — | Không ảnh hưởng | Cho phép |
| Thêm trường tùy chỉnh | — | Không ảnh hưởng đến GLODIPAY | Cho phép |
Lưu ý: Xác thực số điện thoại áp dụng cho tất cả phương thức thanh toán. Dù không chọn GLODIPAY, số điện thoại không hợp lệ vẫn chặn đơn hàng.
Dùng page builder (Elementor, Divi, v.v.)
Nếu trang checkout được xây dựng bằng page builder, đảm bảo tất cả trường thanh toán bắt buộc trong Mục 9.1 đều có mặt trong form checkout. Plugin GLODIPAY tương thích với mọi theme hoặc page builder tải WooCommerce đúng cách.
Thêm trường tùy chỉnh vào checkout
Thêm trường tùy chỉnh vào trang checkout không ảnh hưởng đến quá trình xử lý thanh toán GLODIPAY. Nếu cần trường tùy chỉnh, hãy liên hệ nhà phát triển web hoặc chuyên gia WooCommerce.
10. Xử lý sự cố
Đơn hàng kẹt ở Pending sau thanh toán
Triệu chứng: Khách hàng đã thanh toán nhưng đơn hàng vẫn hiển thị pending.
Các bước chẩn đoán:
- Bật Debug Mode: WooCommerce → Settings → Payments → GLODIPAY Payment Gateway → Manage → Enable Debug Mode
- Tái hiện sự cố và kiểm tra log: WooCommerce → Status → Logs
- Kiểm tra website có thể truy cập công khai — mở URL này từ bên ngoài mạng của bạn hoặc dùng công cụ:
https://yoursite.com/?wc-api=glodipay_webhook - Kiểm tra xem website có plugin bảo mật, firewall, hoặc hạn chế địa lý có thể chặn kết nối từ máy chủ GLODIPAY không
- Liên hệ GLODIPAY support với Order ID — họ có thể kiểm tra thông báo đã được gửi chưa và lỗi xảy ra ở đâu
Nguyên nhân phổ biến:
| Nguyên nhân | Cách nhận biết | Giải pháp |
|---|---|---|
| Website không thể truy cập công khai | URL webhook không tải được từ công cụ bên ngoài | Đảm bảo website có domain thực với SSL hợp lệ |
| Hạn chế IP hoặc địa lý | Website chỉ tải được qua VPN hoặc từ một số quốc gia | Bỏ hạn chế truy cập trên URL webhook |
| Firewall chặn kết nối đến | Không có log sau thanh toán | Mở quyền truy cập vào; thêm IP GLODIPAY vào allowlist (liên hệ support để lấy IP) |
| RSA Public Key không đúng | Log hiển thị lỗi xác thực chữ ký | Sao chép lại RSA Public Key từ GLODIPAY Merchant → API Keys |
Sửa thủ công đơn hàng kẹt:
WooCommerce Admin → Orders → Chọn đơn hàng → Đổi trạng thái thành Processing → Save
Form thanh toán không xuất hiện
- Kiểm tra plugin đang hoạt động: Plugins → Installed Plugins → GLODIPAY Payment Gateway
- Kiểm tra API keys đã nhập: WooCommerce → Settings → Payments → GLODIPAY Payment Gateway → Manage
- Thử trình duyệt khác hoặc tắt extension trình duyệt
- Bật Debug Mode trong cài đặt plugin và kiểm tra log: WooCommerce → Status → Logs
Khách hàng quay lại trang checkout — Form thanh toán xuất hiện lại
Đây là hành vi bình thường. Nếu khách hàng điều hướng trở lại trang checkout sau khi đã khởi tạo thanh toán, plugin hiển thị lại form thanh toán hiện có thay vì tạo thanh toán mới. Điều này ngăn chặn việc thanh toán trùng lặp.