Hướng dẫn tích hợp MoMo vào WooCommerce — 4 bước end-to-end

MoMo có thị phần lớn nhất ví điện tử Việt Nam với hơn 30 triệu người dùng active. Chiếm khoảng 40% giao dịch online cho người trẻ 18-35 tuổi theo VECITA 2025. Tích hợp MoMo vào WooCommerce dùng plugin cộng đồng trên GitHub (chưa có plugin chính thức WordPress.org), mất 1-2 ngày làm việc.

Bài này hướng dẫn end-to-end + debug 5 lỗi chữ ký không khớp phổ biến.

Khi nào MoMo nên làm cổng chính thay vì phụ

Cửa hàng bán fashion, F&B, đồ điện tử consumer, voucher digital — target user 18-35 tuổi nên đặt MoMo làm chính. Conversion rate qua MoMo cao hơn ATM 8-12% cho phân khúc này theo data internal Web22 từ 60 cửa hàng.

• Phù hợp đặt MoMo chính: shop fashion, F&B, đồ điện tử consumer, voucher digital — khách 18-35 tuổi đơn nhỏ.
• Phù hợp đặt MoMo phụ: shop B2B, đơn trên 10 triệu, khách trên 40 tuổi.

Ngược lại, cửa hàng B2B hoặc bán hàng đắt trên 10 triệu nên đặt MoMo làm phương án phụ.

Khách trên 40 tuổi cũng ít dùng MoMo — user MoMo trung bình thanh toán dưới 2 triệu.

Đơn lớn họ vẫn ưu tiên chuyển khoản ATM.

3 tier đơn vị bán MoMo và phí tương ứng

Tránh tier Cá nhân với cửa hàng production

• Phí cao 2,5%: đắt hơn Doanh nghiệp Standard 0,7% — đơn 1 triệu mất thêm 7.000đ/giao dịch không đáng.
• Settle T+0 thủ công: phải manual rút tiền từ ví, không tự động chuyển STK — workflow vận hành phiền.
• Không có IPN webhook: phải poll status API mỗi 1-2 phút, độ trễ cao, dễ miss update — UX khách hàng kém.

Quy trình tích hợp 4 bước end-to-end

Tích hợp MoMo vào WooCommerce gồm 4 bước tuần tự: đăng ký Business, cài plugin, test sandbox, go-live với tuỳ chỉnh theo phân khúc khách.

Bước 1 — Đăng ký MoMo Doanh nghiệp qua portal

Truy cập doanh nghiệp.momo.vn click “Đăng ký Đơn vị bán”. Process nhanh hơn VNPAY — 3-5 ngày so với 3-7.

MoMo có team review trong giờ hành chính active hơn.

4 thông tin trả về sau khi approve

MoMo gửi email với 4 credential phải lưu password manager. Khác VNPAY ở chỗ MoMo cấp RSA Công khai Key để verify webhook callback — cơ chế bảo mật mạnh hơn.

1. Partner Code: mã định danh đơn vị bán, vd MOMOBKUN20180529 — paste vào plugin setting.
2. Access Key: công khai key dùng cho mọi request API — không nhạy cảm bằng Bí mật Key.
3. Bí mật Key: private key sign HMAC SHA256 — CẤM paste công khai hay commit vào kho mã Git.
4. Công khai Key RSA: dùng verify chữ ký webhook callback từ MoMo — đảm bảo callback từ MoMo thật.

Upgrade từ Cá nhân lên Doanh nghiệp Pro

Cửa hàng bắt đầu ở tier Cá nhân có thể upgrade Standard sau khi có giấy phép kinh doanh. Upgrade lên Pro cần chứng minh khối lượng hơn 100 triệu/tháng qua 3 tháng liên tiếp.

Bước 2 — Cài plugin cộng đồng từ GitHub MoMo

MoMo chưa publish plugin chính thức trên WordPress.org (khác VNPAY). Phải dùng plugin cộng đồng — phổ biến nhất là kho mã chính thức của MoMo trên GitHub.

Tải plugin từ kho mã chính thức MoMo

1. Truy cập github.com/momo-wallet/woocommerce — đây là kho mã chính thức của đội MoMo.
2. Click “Code” → “Download ZIP” để tải tệp woo-momo-thanh toán.zip.
3. Vào WordPress admin Plugins → Add New → Upload Plugin, chọn tệp zip vừa tải.
4. Click Install Now, đợi upload xong, sau đó Activate.
5. Vào WooCommerce → Settings → Thanh toán tìm row “MoMo” rồi click Manage.

Cấu hình 3 credential + 2 endpoint URL

Trang config có 10 field bắt buộc. Đặc biệt lưu ý field “Request Type” — chọn sai loại request là khách không thanh toán được.

# WooCommerce → Settings → Thanh toán → MoMo → Manage

Enable: ✓ tick
Title: "Thanh toán qua ví MoMo"
Description: "Quét QR hoặc mở app MoMo thanh toán nhanh."

Partner Code: MOMOBKUN20180529
Access Key: F8BBA842ECF85
Bí mật Key: K951B6PE1waDMi640xX08PD3vg6EkVlz

Endpoint Sandbox: https://test-thanh toán.momo.vn/v2/cổng/api/create
Endpoint Production: https://thanh toán.momo.vn/v2/cổng/api/create

IPN URL: https://yourdomain.vn/wc-api/momo_ipn/
Redirect URL: https://yourdomain.vn/wc-api/momo_redirect/

Mode: Sandbox
Request Type: captureWallet (ví thường) hoặc payWithATM (qua thẻ ATM nội địa)

Bước 3 — Test sandbox với app MoMo Test riêng biệt

Đây là khác biệt lớn so với VNPAY — MoMo có app sandbox tách biệt hoàn toàn khỏi app production. Bắt buộc cài app MoMo Test từ APK link trong dashboard đơn vị bán.

Cài app MoMo Test trên Android/iOS

• Android: tải APK từ dashboard đơn vị bán tab “Tài nguyên” — cài qua “Install unknown sources” trong setting Android.
• iOS: register UDID device trong dashboard, MoMo gửi link TestFlight để cài qua App Store private.
• Account test: MoMo cấp riêng cho mỗi đơn vị bán — không thể test bằng account MoMo cá nhân của owner.

Test flow QR code + deeplink

Tạo sản phẩm test giá 100.000đ, add cart, checkout chọn MoMo. WooCommerce gọi MoMo API trả về QR code + URL deeplink.

Mở app MoMo Test quét QR → confirm thanh toán bằng PIN sandbox.

• Verify đơn hàng status: chuyển từ “Pending” sang “Processing” trong vòng 5-10 giây.
• Verify IPN fire: WooCommerce → Status → Logs, tệp momo-{date}.log có entry “ipn-success” kèm transaction ID.
• Verify email notification: email confirm đơn hàng gửi đến địa chỉ customer test.

Bước 4 — Go live và tuỳ chỉnh logic theo phân khúc khách

Sau khi test sandbox pass 3-5 đơn cả happy path lẫn failure case, switch Mode sang Production. Test 1 đơn thật từ tài khoản MoMo cá nhân của owner — phí 1-2k thực sự bị charge, chấp nhận để verify production flow.

Tuỳ chỉnh 1 — Hide MoMo với đơn lớn hơn 5 triệu

MoMo phù hợp đơn nhỏ dưới 5 triệu — đơn lớn user thường ưu tiên ATM hoặc bank transfer. Filter hook hide MoMo cho đơn lớn để giảm friction checkout.

add_filter('woocommerce_available_payment_gateways', 'limit_momo_amount');

function limit_momo_amount($cổng) {
    if (is_admin() || ! WC()->cart) return $cổng;
    $total = WC()->cart->get_total('numeric');
    if ($total > 5000000 && isset($cổng['momo'])) {
        unset($cổng['momo']);
    }
    return $cổng;
}

Tuỳ chỉnh 2 — Track conversion theo cổng lên GA4

Đo conversion riêng theo từng cổng để biết MoMo có thực sự outperform ATM cho phân khúc trẻ không.

Push event vào GA4 enhanced ecommerce qua thank-you page.

add_action('woocommerce_thankyou', function($order_id) {
    $đơn hàng = wc_get_order($order_id);
    if ($đơn hàng->get_payment_method() === 'momo') {
        echo '<script>gtag("event", "purchase_momo", {value: '
            . $đơn hàng->get_total() . '});</script>';
    }
});

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

MoMo có cơ chế chữ ký HMAC SHA256 phức tạp hơn VNPAY — 80% issue tích hợp đến từ chữ ký không khớp. Dưới đây là 5 lỗi gặp nhiều nhất.

• Invalid chữ ký không khớp: MoMo API trả về error “Invalid chữ ký”. Kiểm tra Bí mật Key paste, đối chiếu thứ tự field trong raw chữ ký với tài liệu MoMo (alphabetical strict).
• IPN không fire dù đã paid: đơn paid bên MoMo nhưng đơn hàng WooCommerce vẫn pending. Check firewall hosting có block IP MoMo (118.69.0.0/16) không — whitelist range đó trong cPanel hoặc Plesk.
• Sandbox app không scan QR production: hoàn toàn bình thường, không phải bug. Sandbox và production isolated 100% — phải dùng app MoMo Test riêng, không phải app MoMo trên store.
• Phí MoMo cao bất thường 2,5%: đang ở tier Personal chưa upgrade Doanh nghiệp. Submit doc giấy phép kinh doanh qua dashboard MoMo → Settings → Upgrade Account để giảm còn 1,8%.
• Đối soát không match doanh thu: phí MoMo + thuế GTGT đã trừ trước khi chuyển STK. Đối soát qua dashboard tab Reports → Đối soát export Excel, không tự tính tay từ tổng đơn.

Monitoring IPN webhook và đối soát đối soát

MoMo có cơ chế IPN webhook quan trọng hơn VNPAY — nếu IPN thất bại là đơn hàng không update dù khách đã paid. Quy trình theo dõi IPN health hàng ngày là bắt buộc.

3 metric IPN cần track liên tục

• IPN success rate: tỷ lệ IPN fire thành công trên tổng đơn hàng paid — healthy trên 98%, dưới 95% là firewall hoặc network issue.
• IPN latency: thời gian từ khi MoMo gửi callback đến khi WooCommerce process xong — healthy dưới 5 giây.
• Retry count: MoMo retry IPN tối đa 5 lần nếu cửa hàng trả về non-200 status. Retry count cao bất thường = endpoint cửa hàng có bug.

Setup cảnh báo qua Slack/Telegram khi IPN thất bại

Hook vào lifecycle IPN — log mọi event vào tệp riêng + gửi cảnh báo real-time qua Slack/Telegram khi gặp pattern bất thường. Phát hiện issue trong 5-10 phút thay vì 1-2 ngày khi khách complain.

• Cảnh báo critical: 5 IPN thất bại liên tiếp trong 10 phút — gửi Slack channel ops kèm error message + order_id.
• Cảnh báo warning: latency trung bình 1 giờ vượt 8 giây — performance regression cần investigate.
• Daily digest: tổng kết IPN success rate + settle match rate gửi email admin mỗi sáng 8h.

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

Cửa hàng B2C trưởng thành thường tích hợp 2-3 cổng song song. MoMo làm chính cho khách trẻ, VNPAY làm chính cho khách trung tuổi — cover hết phân khúc.

Tham khảo các cổng còn lại theo từng phân khúc khách. VNPAY cho mass market 40+ ngân hàng, ZaloPay tận dụng Zalo OA, OnePay cho cửa hàng B2B doanh nghiệp lớn.

Trước khi tích hợp thanh toán, đảm bảo cửa hàng đã hardening security đúng chuẩn. Xem bảo mật cửa hàng WooCommerce 7 lớp để bảo vệ data khách và flow thanh toán.

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

Tích hợp MoMo Doanh nghiệp turnkey cho cửa hàng B2C

Setup MoMo end-to-end gồm đăng ký Doanh nghiệp, debug chữ ký, config IPN webhook, tuỳ chỉnh logic theo phân khúc. Tự mò mất 4-6 ngày nếu dev chưa có kinh nghiệm WooCommerce thanh toán.

Web22 ship turnkey MoMo trong 2-3 ngày, bao gồm cả chữ ký debug + IPN monitoring + tuỳ chỉnh hide cổng. Báo giá website bán hàng WooCommerce — báo giá theo phạm vi rõ ràng, có SLA cam kết giao đúng hạn.