Tích hợp VNPAY vào WooCommerce — quy trình 4 bước, plugin official, test sandbox

VNPAY là cổng thanh toán nội địa có độ phủ ngân hàng rộng nhất Việt Nam — kết nối 40+ ngân hàng + thẻ Visa/Master qua 3D Secure 2.0. Quy trình tích hợp 4 bước với plugin official trên WordPress.org mất 1-2 ngày làm việc.

Bài này hướng dẫn end-to-end + xử lý 5 lỗi phổ biến + 4 custom logic thường dùng cho shop VN.

Khi nào nên chọn VNPAY làm cổng chính

VNPAY xử lý hơn 60% giao dịch online qua ngân hàng VN năm 2024 theo báo cáo NAPAS. Shop B2C target mass market 25-55 tuổi nên ưu tiên VNPAY làm gateway primary.

Lợi thế lớn của VNPAY là plugin official được duy trì trực tiếp bởi đội dev VNPAY — update theo phiên bản WooCommerce mới trong 1-2 tuần, không phụ thuộc community.

3 tier phí phân theo volume tháng

So sánh nhanh với các cổng khác trong batch

• VNPAY vs MoMo: VNPAY mạnh ở thẻ ATM (40+ banks), MoMo mạnh ở ví điện tử trẻ — chọn VNPAY làm primary cho shop mass market.
• VNPAY vs OnePay: VNPAY phê duyệt 3-7 ngày, OnePay nghiêm hơn 5-15 ngày — VNPAY phù hợp shop SME khởi động nhanh.
• VNPAY vs Ngân Lượng: VNPAY không có escrow, Ngân Lượng có — shop marketplace 2-bên nên xem tích hợp Ngân Lượng thay thế.

Bước 1 — Đăng ký merchant VNPAY trên Cổng Doanh nghiệp

Truy cập vnpay.vn mục “Merchant” để tạo account business. Form online 15 phút, sau đó VNPAY review 3-7 ngày làm việc.

5 giấy tờ cần chuẩn bị trước khi submit

1. Giấy phép kinh doanh bản scan màu, file PDF dưới 5MB.
2. CCCD/CMND người đại diện pháp luật, scan 2 mặt rõ nét.
3. Hợp đồng thuê nhà hoặc giấy chứng nhận sở hữu địa điểm kinh doanh.
4. Số tài khoản ngân hàng đứng tên doanh nghiệp khớp giấy phép.
5. URL website đã có SSL active + sản phẩm/dịch vụ hiển thị rõ.

Sau khi approve — 3 credential phải lưu kỹ

VNPAY gửi email approval kèm 3 thông tin quan trọng. Lưu cả 3 vào password manager (1Password, Bitwarden) — KHÔNG paste qua Slack public hay email cá nhân.

• Terminal ID (TMN Code): mã định danh terminal, vd 2QXUI4B4 — paste vào plugin setting.
• Hash Secret: chuỗi ký tự sign request HMAC SHA512 — rò rỉ là attacker giả mạo callback được.
• Endpoint URL: sandbox sandbox.vnpayment.vn và production pay.vnpay.vn.

Bước 2 — Cài plugin VNPAY official từ WordPress.org

VNPAY là một trong ít cổng thanh toán VN có plugin official được publish chính thức trên WordPress.org. Cài qua wp-admin chỉ 5 phút, không cần touch code SSH.

Quy trình cài plugin qua wp-admin UI

1. Vào Plugins → Add New, search keyword “VNPAY for WooCommerce”.
2. Chọn plugin có publisher “VNPay JSC” — đây là plugin official duy nhất.
3. Click Install Now, đợi download xong, sau đó Activate.
4. Vào WooCommerce → Settings → Payments tìm row “VNPAY”.
5. Click Manage để mở trang config credential.

Cấu hình credential và endpoint URL

Trang config có 8 field bắt buộc. Paste chính xác từ email VNPAY — sai 1 ký tự là toàn bộ flow fail.

# WooCommerce → Settings → Payments → VNPAY → Manage

Enable: ✓ tick để bật gateway
Title: "Thanh toán qua VNPAY (40+ ngân hàng)"
Description: "Thanh toán an toàn qua VNPAY với ATM/Visa/Master."

Terminal ID (TMN Code): 2QXUI4B4
Hash Secret: SECRETKEY123ABCXYZ

Sandbox URL: https://sandbox.vnpayment.vn/paymentv2/vpcpay.html
Production URL: https://pay.vnpay.vn/vpcpay.html
Return URL: https://yourdomain.vn/wc-api/vnpay/

Mode: Sandbox (đổi Production sau khi test pass)
Currency: VND
Locale: vn

Save changes

Bước 3 — Test sandbox với 3 card test VNPAY cấp

Bắt buộc test sandbox trước go-live, dù tự tin config đúng. VNPAY cấp 3 card test cover happy path + failure path để verify toàn bộ flow.

3 card test cho 3 kịch bản khác nhau

• Card success ATM nội địa: số 9704198526191432198, expire 07/15, OTP 123456 — verify flow happy path.
• Card test failed: số 9704195825181517410, expire 07/15, OTP 123456 — verify shop handle failure đúng.
• Card test 3DS Visa: số cấp riêng trong dashboard merchant — verify flow 3D Secure cho thẻ quốc tế.

Quy trình test checkout end-to-end

Tạo 1 sản phẩm test giá 100.000đ, add vào cart, checkout chọn VNPAY. Hệ thống redirect sang sandbox VNPAY → nhập card test → confirm OTP 123456.

• Verify order status: WooCommerce → Orders, order phải chuyển từ “Pending” sang “Processing”.
• Verify email confirm: email order confirm phải gửi đến địa chỉ khách hàng test.
• Verify log gateway: WooCommerce → Status → Logs, file vnpay-{date}.log phải có entry success kèm transaction ID.

Bước 4 — Go live và custom logic 4 use case phổ biến

Sau khi test sandbox pass 3-5 đơn với cả 3 card test, switch Mode từ Sandbox sang Production. Paste production URL từ email VNPAY, save lại.

Test ngay 1 đơn thật với card cá nhân của owner, mua sản phẩm giá 10.000đ. Verify flow production hoạt động end-to-end trước khi mở cho khách hàng.

Custom 1 — Add fee 1,5% transparent với khách

Shop muốn pass-through phí VNPAY cho khách hàng. Dùng filter hook để hiển thị fee trong cart và checkout — minh bạch giúp khách hiểu giá thay đổi.

add_action('woocommerce_cart_calculate_fees', 'add_vnpay_fee');

function add_vnpay_fee() {
    $payment = WC()->session->get('chosen_payment_method');
    if ($payment === 'vnpay') {
        $fee = WC()->cart->get_subtotal() * 0.015;
        WC()->cart->add_fee('Phí xử lý VNPAY (1,5%)', $fee, false);
    }
}

Custom 2 — Hide VNPAY với đơn dưới 50.000đ

Đơn quá nhỏ không kinh tế khi pass-through fee VNPAY. Hide gateway với đơn dưới ngưỡng, ép khách chọn COD hoặc bank transfer.

add_filter('woocommerce_available_payment_gateways', 'hide_vnpay_low_amount');

function hide_vnpay_low_amount($gateways) {
    if (is_admin() || ! WC()->cart) return $gateways;
    $total = WC()->cart->get_total('numeric');
    if ($total < 50000) {
        unset($gateways['vnpay']);
    }
    return $gateways;
}

Custom 3 — Idempotent webhook chống double-charge

Webhook callback có thể fire 2 lần do network retry.

Dùng meta key check trước khi update order status — tránh charge khách 2 lần do bug.

5 lỗi phổ biến khi tích hợp VNPAY và cách fix nhanh

Dưới đây là 5 lỗi gặp nhiều nhất qua kinh nghiệm Web22 tích hợp VNPAY cho hơn 80 shop. Mỗi lỗi có root cause + fix cụ thể.

• Invalid hash signature: sau redirect sang VNPAY, page báo “Invalid hash” — nguyên nhân Hash Secret paste sai. Re-paste từ email gốc, đảm bảo không có space đầu/cuối.
• Không quay lại site sau thanh toán: Return URL config sai trong plugin hoặc dashboard merchant VNPAY. Set chính xác https://yourdomain.vn/wc-api/vnpay/ ở cả 2 nơi.
• VNPAY reject domain không SSL: production yêu cầu HTTPS active. Cài Let’s Encrypt qua hosting trước khi switch sang production mode.
• IP server chưa whitelist: production VNPAY yêu cầu whitelist IP server gọi API. Lấy IP qua hosting panel, gửi VNPAY support qua email.
• Đơn bị charge 2 lần: webhook fire duplicate do timeout retry. Implement idempotent check với meta _vnpay_processed, return 200 OK ngay khi nhận callback.

Monitoring và đối soát doanh thu hàng ngày

Sau khi go-live, vận hành VNPAY ổn định cần workflow monitoring + đối soát doanh thu daily. Bỏ qua step này dẫn đến phát hiện lỗi muộn — đơn fail âm thầm hoặc settlement không khớp.

Dashboard merchant VNPAY 3 metric quan trọng

• Transaction success rate: tỷ lệ giao dịch thành công trên tổng request — healthy trên 92%, dưới 85% là dấu hiệu issue gateway hoặc UX checkout.
• Settlement timing: verify settle đúng T+1 cho thẻ ATM, T+2-3 cho thẻ quốc tế — delay quá hạn liên hệ Account Manager ngay.
• Refund volume: track refund/cancel rate — bất thường vượt 5% có thể là dấu hiệu fraud hoặc UX checkout có bug.

Đối soát doanh thu cuối ngày

Export báo cáo VNPAY tab Reports → Daily Settlement, đối chiếu với WooCommerce → Reports → Sales daily. Sai lệch trên 1% cần investigate ngay — thường do đơn được paid bên VNPAY nhưng IPN không fire về WooCommerce.

• Đơn pending nhưng paid: query WooCommerce DB tìm order status pending hơn 1 giờ, cross-check với dashboard VNPAY.
• Phí gateway minus: tổng phí VNPAY phải khớp công thức (transaction_amount × fee_rate) — phát hiện overcharge sớm.
• Refund pending: refund qua VNPAY mất 5-7 ngày — track trong dashboard, theo dõi khách nếu quá hạn.

Tích hợp đa cổng và bài liên quan

Shop VN trưởng thành thường tích hợp 2-3 cổng song song để cover hết phân khúc khách hàng. VNPAY làm primary, MoMo và ZaloPay làm phụ.

Tham khảo guide chi tiết các cổng còn lại: tích hợp MoMo cho khách trẻ 18-35 tuổi, tích hợp ZaloPay để leverage Zalo OA marketing, tích hợp OnePay nếu có khách B2B doanh nghiệp lớn.

Trước khi tích hợp payment, đảm bảo shop đã hardening security đúng chuẩn — xem bảo mật shop WooCommerce 7 lớp để bảo vệ data khách.

Câu hỏi thường gặp về tích hợp VNPAY

Tích hợp VNPAY trọn gói cho shop của bạn

Setup VNPAY end-to-end cần kiến thức WordPress + PHP + signature crypto + payment compliance. Shop không có dev WooCommerce chuyên trách mất 3-5 ngày tự mò, dễ stuck ở debug signature.

Web22 ship turnkey VNPAY trong 2-3 ngày, bao gồm cả custom logic fee transparent + idempotent webhook + monitoring log. Dịch vụ thiết kế WooCommerce trọn gói tại Web22 — báo giá theo phạm vi, có SLA cam kết giao đúng hạn.