Tích hợp Bảo Kim vào WooCommerce — niche giáo dục online + escrow

Bảo Kim là cổng thanh toán Việt Nam ra đời 2009, hiện có khoảng 2-3 triệu user và sở hữu lợi thế hiếm: tính năng escrow giữ tiền theo product type. Bài này hướng dẫn 6 bước tích hợp Bảo Kim vào WooCommerce cho shop bán khoá học online, dịch vụ freelance hoặc marketplace P2P quy mô vừa.

Phí 1,2-1,8% tuỳ tier, settlement T+1 đến T+2, setup full 2-5 ngày.

Vì sao chọn Bảo Kim cho shop dịch vụ digital

Phần lớn shop bán hàng vật lý B2C tại Việt Nam mặc định chọn VNPAY hoặc MoMo cho tốc độ chuyển khoản và độ phủ ngân hàng. Bảo Kim chiếm vị trí khác hẳn: ngách giáo dục online, freelance và marketplace cần escrow để bảo vệ buyer khi product giao chậm hoặc sản phẩm bàn giao phức tạp.

Shop bán khoá học có refund policy 7-14 ngày sẽ hưởng lợi từ escrow Bảo Kim. Tiền vào account trung gian chứ chưa về shop, buyer xác nhận hoàn thành thì tiền mới release.

Dispute thì xử qua dashboard, không phải qua chargeback ngân hàng phức tạp như Stripe.

3 lợi thế cụ thể của Bảo Kim so với cổng truyền thống

• Escrow tích hợp sẵn: giữ tiền 3-30 ngày tuỳ product category, không cần plugin escrow bên thứ ba, không phải custom code phức tạp như khi dùng Stripe Connect.
• Niche giáo dục mạnh: nhiều trung tâm khoá học online VN đã dùng Bảo Kim từ 2015-2018, user audience đã quen flow xác nhận giao hàng và xử lý dispute trên ví.
• Setup nhẹ: 2-5 ngày approve merchant, không yêu cầu doanh thu tối thiểu như OnePay, chấp nhận hộ kinh doanh cá thể chứ không phải bắt buộc công ty TNHH.

Khi nào KHÔNG nên chọn Bảo Kim

Bảo Kim không phải cổng tốt nhất cho mọi trường hợp. Có 3 tình huống shop nên skip và chọn cổng khác để tránh lãng phí công sức tích hợp.

• Shop bán hàng vật lý B2C mass: khách quen MoMo, VNPAY, ZaloPay — Bảo Kim ít user nhận diện. Tỉ lệ chuyển đổi thấp 30-40% so với VNPAY trên cùng checkout.
• Shop cần subscription billing: Bảo Kim Định kỳ API ra 2024 nhưng plugin community chưa support đầy đủ, phải custom code. Stripe vẫn là lựa chọn tốt hơn cho SaaS.
• Shop B2B doanh nghiệp lớn: doanh nghiệp quen chuyển khoản trực tiếp hoặc OnePay (chuỗi VietinBank). Bảo Kim brand chưa đủ trust cho enterprise.

Bước 1 — Đăng ký Bảo Kim Merchant và 3 tier phí

Đăng ký merchant qua website chính thức của Bảo Kim. Process online 2-5 ngày, hồ sơ cần giấy phép kinh doanh hoặc CCCD chủ hộ kinh doanh, STK ngân hàng cùng tên với đăng ký kinh doanh.

Hồ sơ chuẩn bị trước khi click đăng ký gồm scan màu giấy phép kinh doanh, bản chụp 2 mặt CCCD chủ tài khoản, sao kê ngân hàng 3 tháng gần nhất. Thiếu 1 trong 3 bộ này thì đơn pending chờ bổ sung 2-3 ngày.

3 tier phí và escrow window tương ứng

• Cá nhân (1,8%): không có escrow, settlement T+1. Phù hợp freelancer nhận thanh toán đơn lẻ, không bán product có refund policy.
• Doanh nghiệp (1,2-1,5%): escrow 3-7 ngày, settlement T+1. Phù hợp shop khoá học online, dịch vụ digital có cam kết hoàn tiền nếu khoá học không đạt cam kết.
• Premium (1,0-1,2%): escrow 3-14 ngày custom, settlement T+1. Yêu cầu doanh thu trên 100 triệu/tháng 3 tháng liên tiếp.
• Phù hợp marketplace, đơn vị có multi-đơn vị cung cấp.

3 credential cần lưu sau khi merchant được duyệt

1. Merchant ID: mã định danh shop trong hệ thống Bảo Kim, dạng số 5-7 chữ số. Hiển thị ngay trang đầu dashboard sau login.
2. API Key public: dùng identify shop khi gọi endpoint tạo order. Có thể nhúng vào client-side JavaScript an toàn.
3. Secret Key: dùng sign request server-side, KHÔNG để lộ ra client. Lưu vào password manager kèm môi trường sandbox và production tách biệt.

Bước 2 — Cài plugin Bảo Kim cho WooCommerce

Bảo Kim không có plugin official trên repo WordPress.org, nhưng có plugin community “WooCommerce BaoKim Payment” được Bảo Kim verify chính thức từ 2021. Plugin free, download trực tiếp tại dashboard merchant của Bảo Kim hoặc từ link verified trên forum WordPress Việt Nam.

Quy trình cài qua wp-admin trong 5 phút

1. Vào Plugins → Add New → Upload Plugin trên wp-admin của shop.
2. Chọn file zip plugin tải về từ dashboard Bảo Kim, click Install Now.
3. Sau cài đặt thành công click Activate để bật plugin.
4. Vào WooCommerce → Settings → Payments, tìm dòng “BaoKim” trong list.
5. Click Manage để mở trang config chi tiết, fill credential và Return URL.

Mẫu config plugin với credential thật

# Plugin Settings → BaoKim Payment config

Enable: ✓ tick bật cổng
Title: "Thanh toán qua Bảo Kim"
Description: "Thanh toán an toàn với escrow Bảo Kim — giữ tiền đến khi nhận hàng."

Merchant ID: 234567                       # Từ dashboard
API Key: BK_PUBLIC_KEY_12345              # Public key
Secret Key: BK_SECRET_67890ABCXYZ         # Sign request

Endpoint Sandbox: https://sandbox.baokim.vn/payment/order
Endpoint Production: https://api.baokim.vn/payment/order

Return URL: https://yourdomain.vn/wc-api/baokim_return/
Notify URL: https://yourdomain.vn/wc-api/baokim_notify/

Escrow: ✓ Auto-bật cho dịch vụ digital
Escrow days default: 5  # Default 5 ngày, custom theo product type

Lưu ý khi config Return URL và Notify URL

Return URL là nơi buyer được redirect về sau khi thanh toán xong. Notify URL là endpoint Bảo Kim gọi background để báo kết quả giao dịch — quan trọng hơn Return URL vì buyer có thể tắt browser nửa chừng.

Cả 2 URL phải có SSL (HTTPS) và response status 200 OK trong vòng 5 giây. Whitelist IP Bảo Kim ở firewall: dải 118.69.252.0/24 cho production và 118.69.253.0/24 cho sandbox.

Block nhầm IP này khiến Notify URL không nhận, đơn pending vĩnh viễn.

Bước 3 — Test trên sandbox với account demo

Bảo Kim cấp sandbox account riêng kèm app Bảo Kim Test để giả lập buyer experience. KHÔNG bao giờ go-live mà chưa test sandbox tối thiểu 5 happy path và 2 edge case dispute.

Checklist test trước khi switch production

• Happy path checkout success: tạo đơn 500.000đ, chọn Bảo Kim, redirect sang sandbox, confirm — tiền vào escrow, order status WooCommerce chuyển “Processing”.
• Buyer xác nhận hoàn thành: mở app Bảo Kim Test, click “Đã nhận hàng” — tiền release từ escrow về tài khoản seller sandbox, status order chuyển “Completed”.
• Dispute case: mở app, click “Khiếu nại” trong escrow window — tiền pending, không release, notification về dashboard merchant để xử lý.
• Verify log chi tiết: mở file /wc-logs/baokim-{date}.log kiểm tra request và response của từng API call — phải có cả endpoint create, return, notify.

Bước 4 — Go live và custom escrow theo product category

Sau khi sandbox pass đủ 7 case checklist, switch endpoint sang production và paste cặp API Key + Secret Key production vào plugin. KHÔNG dùng chung credential sandbox cho production, Bảo Kim sẽ block account vì pattern không hợp lệ.

Tính năng giá trị nhất của Bảo Kim cho shop multi-product là custom escrow_days theo product category. Khoá học có refund policy 14 ngày thì escrow 14 ngày, ebook delivery instant thì escrow 1 ngày, coaching multi-session thì escrow 30 ngày.

Snippet PHP set escrow days theo product category

// Set escrow days theo product category
add_filter('baokim_escrow_days', 'category_based_escrow', 10, 2);

function category_based_escrow($days, $order) {
    $items = $order->get_items();

    foreach ($items as $item) {
        $product_id = $item->get_product_id();
        $cats = wp_get_post_terms($product_id, 'product_cat', ['fields' => 'slugs']);

        if (in_array('khoa-hoc', $cats)) {
            return 14;  // Khoá học có refund policy 14 ngày
        } elseif (in_array('ebook', $cats)) {
            return 1;   // Ebook digital delivery instant
        } elseif (in_array('coaching-1-1', $cats)) {
            return 30;  // Coaching multi-session
        }
    }
    return 5;  // Default 5 ngày cho product không xếp category
}

Email notification cho buyer khi escrow window sắp hết

Nhiều buyer quên click “Đã nhận hàng” sau khi thực sự nhận, gây kẹt tiền trong escrow. Gửi email reminder 2 ngày trước khi escrow auto-release giúp buyer chủ động xác nhận, đồng thời thông báo seller theo dõi.

Hook vào event baokim_escrow_expiring_soon plugin fire khi còn 48 giờ. Compose email với link đến app Bảo Kim Test hoặc app sản xuất, kèm order detail và policy refund của shop để buyer ra quyết định nhanh.

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

Tổng hợp từ 12 dự án Web22 deploy Bảo Kim 2023-2025, đây là 5 lỗi gặp nhiều nhất khi go-live. Pattern fix kèm theo đã được verify trên production thực tế.

• API Key paste sai: request reject với message “Unauthorized” hoặc “Invalid signature”. Re-check cả 3 credential (Merchant ID, API Key, Secret Key) từ dashboard, đặc biệt phân biệt sandbox vs production — pattern ký tự khác nhau ở prefix.
• Notify URL không nhận callback: Bảo Kim retry 3 lần rồi bỏ. Whitelist IP 118.69.252.0/24, đảm bảo URL response 200 OK trong 5 giây, KHÔNG redirect chain qua nhiều domain.
• Check Cloudflare hoặc reverse proxy có block IP Bảo Kim không.
• Escrow stuck pending: buyer không confirm, không dispute, nhưng tiền không auto-release sau escrow_days. Nguyên nhân: WP-Cron không chạy trên host shared.
• Setup real cron Linux gọi wp cron event run --due-now mỗi 15 phút.
• Plugin conflict với page cache: WP Rocket, LiteSpeed Cache giữ form payment cũ, signature mismatch khi submit. Exclude trang /checkout/ và /wc-api/ khỏi cache rules.
• Test bằng cách hard refresh checkout sau khi đổi cart.
• Phí cao bất thường ở tier Cá nhân: shop đăng ký nhầm tier Cá nhân 1,8% trong khi đủ điều kiện Doanh nghiệp 1,2-1,5%. Submit giấy phép kinh doanh qua dashboard support, request upgrade — duyệt 3-5 ngày.

Checklist 8 điểm bắt buộc trước khi go-live Bảo Kim

Sau khi hoàn thành 5 bước trên, đừng switch production ngay. Chạy checklist 8 điểm để bắt lỗi sót — pattern fail phổ biến nhất là phát hiện sau khi đã có khách thật, lúc đó refund và xử lý support phức tạp hơn nhiều.

4 điểm kỹ thuật cần verify

• SSL certificate valid trên domain shop: Bảo Kim reject Notify URL không HTTPS. Check SSL bằng SSL Labs grade A trở lên.
• Wildcard certificate cho subdomain checkout cũng OK.
• Webhook IP whitelist firewall: dải 118.69.252.0/24 cho production. Test bằng tool curl từ IP Bảo Kim — nếu nhận 200 OK thì pass, 403/timeout là firewall block.
• Cron job Linux thay WP-Cron: WP-Cron không reliable trên shared hosting. Setup real cron Linux gọi wp cron event run --due-now mỗi 15 phút qua command line cPanel hoặc Plesk.
• Error log rotation: file /wc-logs/baokim-{date}.log có thể tăng kích thước nhanh khi traffic cao. Setup logrotate hằng tuần, giữ 30 ngày log gần nhất.

4 điểm business cần verify

• Refund policy ghi rõ trên website: trang Refund Policy với thời gian, điều kiện, quy trình. Bảo Kim đối chiếu với dispute để xử lý — policy minh bạch giảm dispute đáng kể.
• Customer service email + hotline responsive: email reply trong 24 giờ, hotline trong giờ hành chính. Buyer không liên hệ được sẽ mở dispute Bảo Kim, dễ thua.
• Hoá đơn VAT tự động sau payment: tích hợp với eInvoice (Viettel, VNPT) để xuất hoá đơn ngay sau Bảo Kim confirm. Hợp lệ về kế toán và thuế.
• Backup database trước go-live: dump database WooCommerce qua UpdraftPlus hoặc lệnh mysqldump. Rollback nhanh nếu issue nghiêm trọng phát sinh trong 48 giờ đầu.

Câu hỏi thường gặp về tích hợp Bảo Kim

Bài liên quan trong cụm WooCommerce

Bảo Kim là 1 trong 8 cổng thanh toán phổ biến cho shop WooCommerce VN. Tham khảo các bài cùng cụm để chọn kết hợp cổng phù hợp mô hình kinh doanh:

• So sánh 8 cổng thanh toán WooCommerce VN — decision matrix — bảng tổng hợp phí, độ phủ, niche để chọn 2-3 cổng tối ưu.
• Tích hợp VNPAY vào WooCommerce — cổng rộng nhất với 40+ ngân hàng, phù hợp B2C mass.
• Tích hợp MoMo vào WooCommerce — ví điện tử cho user trẻ dưới 35 tuổi, conversion cao.
• Cấu hình COD WooCommerce — chống bom hàng — pair với Bảo Kim cho shop bán dịch vụ kèm hàng vật lý.
• Dịch vụ thiết kế website WooCommerce trọn gói tại Web22 — tham khảo gói thi công shop bán hàng VN turnkey.

Cần đội Web22 dev WooCommerce full feature kèm tích hợp Bảo Kim escrow theo product category? Đội Web22 dev WooCommerce full feature — báo giá rõ ràng theo phạm vi, không phát sinh sau khi ký hợp đồng.