Tích hợp OnePay vào WooCommerce — cổng thanh toán VietinBank cho B2B

OnePay là cổng thanh toán B2B-friendly nhất tại Việt Nam — sản phẩm của VietinBank, support corporate card và 3D Secure 2.0 mạnh nhất hệ sinh thái VN. Quy trình duyệt nghiêm 5-15 ngày làm việc, đòi hỏi báo cáo tài chính 6-12 tháng.

Phí 1,5-2,5% tuỳ tier. Bài này hướng dẫn end-to-end + flow corporate card B2B + 5 lỗi phổ biến khi tích hợp.

OnePay khác gì các cổng thanh toán khác cho shop B2B

OnePay là cổng duy nhất tại VN được phát triển trực tiếp bởi một ngân hàng thương mại cổ phần state-owned (VietinBank). Đó là lý do compliance và security ở mức enterprise — chấp nhận corporate card của ngân hàng VN, support workflow approval đa tầng cho khách doanh nghiệp.

Trade-off là quy trình onboarding chậm và yêu cầu giấy tờ nghiêm — không phù hợp shop SME nhỏ khởi động nhanh. Đầu tư setup OnePay xứng đáng với shop có khách doanh nghiệp lớn cần thanh toán hợp đồng hàng trăm triệu.

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

3 dấu hiệu shop nên tích hợp OnePay

• Có khách doanh nghiệp dùng corporate card: khách thanh toán bằng thẻ tín dụng doanh nghiệp Visa Business/Master Corporate — cần OnePay support flow approval.
• Đơn giá trị lớn trung bình trên 10 triệu: 3DS 2.0 của OnePay mạnh hơn các cổng khác, giảm risk fraud cho đơn lớn.
• Shop B2B có hợp đồng dịch vụ: billing theo project, đơn 50-500 triệu — OnePay được khách doanh nghiệp tin tưởng hơn ví điện tử.

Bước 1 — Đăng ký OnePay Merchant qua portal

Truy cập onepay.vn mục “Đăng ký Merchant”. Quy trình online 30 phút nhưng review 5-15 ngày làm việc — chậm hơn VNPAY do OnePay kiểm tra tài chính nghiêm.

5 giấy tờ bắt buộc cho tier SME

1. Giấy phép kinh doanh + Mã số thuế còn hiệu lực trên 12 tháng.
2. CCCD người đại diện pháp luật, scan 2 mặt rõ nét.
3. Báo cáo tài chính 6-12 tháng cho tier SME — kiểm toán cho tier Corporate.
4. Hợp đồng thuê hoặc giấy chứng nhận sở hữu địa điểm kinh doanh.
5. Số tài khoản ngân hàng đứng tên doanh nghiệp — ưu tiên STK VietinBank để settle nhanh.

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

OnePay gửi email approval kèm 3 credential. Lưu password manager — đặc biệt Secure Hash là key sign HMAC, rò rỉ là attacker giả mạo request.

• Merchant ID: mã định danh shop trong hệ thống OnePay, vd ONEPAY12345.
• Access Code: public access code dùng trong query string redirect.
• Secure Hash: private key sign HMAC SHA512 — CẤM paste public hay commit Git.

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

OnePay đã publish plugin official trên WordPress.org từ năm 2023 — khác MoMo và ZaloPay phải dùng plugin community GitHub. Plugin được team OnePay duy trì trực tiếp, update theo WooCommerce mới.

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

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

Cấu hình Merchant ID + Access Code + Secure Hash

Trang config có 9 field bắt buộc. Đặc biệt field “Locale” set “vn” để hiển thị tiếng Việt cho khách hàng VN — không để default English.

# WooCommerce → Settings → Payments → OnePay → Manage

Enable: ✓ tick
Title: "Thanh toán qua OnePay (ATM/Visa/Master/Corporate)"
Description: "Cổng VietinBank, support corporate card + 3D Secure 2.0."

Merchant ID: ONEPAY12345
Access Code: ABC12DEF
Secure Hash: SECRETKEY123ABCXYZ

Endpoint Sandbox: https://mtf.onepay.vn/onecomm-pay/vpc.op
Endpoint Production: https://onepay.vn/onecomm-pay/vpc.op
Return URL: https://yourdomain.vn/wc-api/onepay_return/

Mode: Sandbox
Currency: VND
Locale: vn (hiển thị tiếng Việt cho khách)

Bước 3 — Test sandbox với 3 card test khác loại

OnePay cấp 3 card test cover 3 kịch bản khác nhau: ATM nội địa, Visa quốc tế có 3DS, Master quốc tế có 3DS. Bắt buộc test cả 3 trước go-live để verify mọi flow.

3 card test cho 3 kịch bản

• Card ATM nội địa: số cấp riêng trong dashboard, expire năm sau, OTP 123456 — flow happy path đơn giản.
• Card Visa 3DS: số cấp riêng, expire năm sau, có thêm bước OTP additional sau khi nhập card — verify flow 3D Secure.
• Card Master 3DS: tương tự Visa 3DS nhưng qua Mastercard Network — verify cross-network compatibility.

Test flow checkout end-to-end

Tạo sản phẩm test giá 1.000.000đ (OnePay phù hợp đơn lớn), add cart, checkout chọn OnePay. Redirect sang OnePay sandbox → chọn loại card → nhập card test → confirm OTP.

• Verify order status: Pending → Processing trong 5-15 giây sau confirm OTP.
• Verify log: file /wc-logs/onepay-{date}.log có entry “transaction-success” kèm transaction ID OnePay.
• Verify 3DS step: với Visa/Master, có bước OTP additional trước khi return về site — UX phải smooth không freeze.

Bước 4 — Go live và workflow corporate card B2B

Sau test sandbox pass 3-5 đơn với cả 3 card test, switch Production. Test 1 đơn thật giá nhỏ 50.000đ từ card cá nhân của owner để verify flow production.

Corporate card flow khác thẻ cá nhân

Khách doanh nghiệp dùng corporate card thường có thêm bước approval nội bộ trước khi confirm payment. Workflow điển hình mất 1-3 giờ thay vì instant như thẻ cá nhân.

• Authorization hold: OnePay hold tiền trong card doanh nghiệp tối đa 7 ngày, đợi accounting team approve.
• Approval notification: khách doanh nghiệp nhận email từ ngân hàng phát hành card request approve.
• Capture sau approve: sau khi accounting approve, OnePay capture tiền và update order status sang “Processing”.
• Timeout 7 ngày: nếu không approve trong 7 ngày, OnePay tự release hold — đơn fail.

Custom logic — show OnePay chỉ cho đơn B2B

OnePay phí cao 2,5% tier SME, không kinh tế cho đơn B2C nhỏ. Filter hook hide OnePay với đơn dưới 500.000đ và user không phải B2B customer.

add_filter('woocommerce_available_payment_gateways', 'b2b_only_onepay');

function b2b_only_onepay($gateways) {
    if (is_admin() || ! WC()->cart) return $gateways;

    $total = WC()->cart->get_total('numeric');
    $is_b2b = is_user_logged_in()
        && in_array('b2b_customer', wp_get_current_user()->roles);

    if ($total < 500000 && ! $is_b2b) {
        unset($gateways['onepay']);
    }
    return $gateways;
}

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

OnePay có cơ chế signature concat field theo alphabetical order strict — debug phức tạp hơn VNPAY do thứ tự field rất quan trọng.

Dưới đây là 5 lỗi gặp nhiều nhất qua kinh nghiệm Web22.

• Invalid signature: sau redirect báo “Invalid signature”. Re-check Secure Hash + concat field theo alphabetical strict — viết function sort field tự động trước khi build raw signature string.
• 3DS OTP timeout 3 phút: khách không nhập OTP kịp, transaction fail. Set timeout dài hơn trong plugin settings (5-10 phút), gửi notification SMS reminder trước khi expire.
• IP server chưa whitelist production: production OnePay yêu cầu whitelist IP server gọi API. Lấy IP qua hosting panel, email OnePay support — process whitelist mất 1-2 ngày làm việc.
• Settlement chậm hơn VNPAY: OnePay T+2 đến T+3 cho thẻ Visa/Master do cross-border clearing. Đối soát qua dashboard tab Reports → Settlement, không expect T+1 như VNPAY.
• Phí cao bất thường cho thẻ quốc tế: Visa/Master cross-border phí 3-3,5%. Limit OnePay chỉ cho thẻ ATM nội địa nếu shop chủ yếu bán B2C trong nước — hide thẻ quốc tế khỏi checkout.

Workflow B2B billing và hóa đơn VAT cho khách doanh nghiệp

OnePay phục vụ khách doanh nghiệp nên workflow billing khác B2C — phải có hóa đơn VAT điện tử + PO number tracking + multi-approver flow. Bỏ qua các yêu cầu này là khách doanh nghiệp không thanh toán được do quy trình kế toán nội bộ.

3 yêu cầu billing B2B bắt buộc

• Hóa đơn VAT điện tử: tích hợp Misa/Viettel eInvoice tự sinh hóa đơn sau khi OnePay confirm payment — gửi email khách trong vòng 24 giờ.
• PO number trên invoice: field “Purchase Order Number” trong checkout — khách doanh nghiệp nhập, hiển thị trên invoice để match hệ thống ERP nội bộ.
• Multi-recipient invoice: gửi invoice đến nhiều email — accounting + procurement + project manager — workflow approval B2B đa tầng.

Custom field B2B trong checkout WooCommerce

Thêm 3 field B2B vào checkout: Tên công ty đầy đủ, Mã số thuế, PO Number. Validate MST đúng format 10 hoặc 13 ký tự — invalid không cho checkout, tránh hóa đơn sai gây phiền khách.

• Tên công ty: required cho mọi role b2b_customer — hiển thị trên invoice thay tên cá nhân.
• Mã số thuế: validate format ^d{10}(d{3})?$ — đúng 10 hoặc 13 chữ số liền nhau.
• PO Number: optional nhưng recommend — khách doanh nghiệp lớn bắt buộc, khách nhỏ có thể bỏ trống.

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

Shop B2B trưởng thành thường tích hợp OnePay + VNPAY song song. OnePay làm primary cho khách doanh nghiệp dùng corporate card, VNPAY làm backup cho khách cá nhân.

Tham khảo các cổng còn lại: tích hợp VNPAY cho mass market 40+ banks, tích hợp MoMo cho khách trẻ B2C, tích hợp ZaloPay để leverage Zalo OA marketing.

Shop B2B xử lý hợp đồng giá trị lớn đặc biệt phải hardening security đúng chuẩn — xem bảo mật shop WooCommerce 7 lớp để bảo vệ data khách doanh nghiệp.

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

Tích hợp OnePay turnkey cho shop B2B doanh nghiệp

Setup OnePay end-to-end gồm chuẩn bị hồ sơ tài chính, đăng ký merchant, debug signature alphabetical order, config 3DS 2.0, custom logic B2B-only — mất 7-14 ngày tự mò nếu chưa có dev kinh nghiệm payment B2B.

Web22 ship turnkey OnePay trong 5-7 ngày sau khi merchant được approve, bao gồm cả corporate card flow + integration accounting workflow. Thi công WooCommerce theo yêu cầu cho shop Việt — báo giá theo phạm vi, có SLA cam kết thời gian hoạt động cho shop B2B.