Tích Hợp Ngân Lượng API: Giải Pháp Thanh Toán Tạm Giữ Cho Sàn TMĐT
Trước khi có MoMo hay ZaloPay, thị trường thanh toán Việt Nam đã được định hình bởi những cái tên tiên phong (Pioneer). Một trong số đó là Ngân Lượng (NganLuong.vn) - ví điện tử và cổng thanh toán trung gian, sản phẩm của NextTech Group (Shark Bình).
Điều làm nên sự khác biệt của Ngân Lượng chính là cơ chế "Thanh toán tạm giữ" (Escrow), cực kỳ phù hợp cho các mô hình Chợ điện tử (Marketplace C2C), nơi người mua cần được bảo vệ quyền lợi trước khi người bán giao hàng.
1. Tại Sao Chọn Ngân Lượng?
- Bảo Vệ Người Mua (Escrow): Tiền thanh toán sẽ được Ngân Lượng "treo" lại. Chỉ khi người mua xác nhận đã nhận hàng (hoặc sau số ngày quy định), tiền mới được chuyển vào ví người bán.
- Đa Dạng Kênh Thanh Toán: Chấp nhận thẻ ATM, Visa/Master, Chuyển khoản ngân hàng, và thanh toán tại quầy Viettel Post.
- Thanh Toán Quốc Tế: Hỗ trợ tốt cho việc bán hàng xuyên biên giới (Cross-border) nhờ liên kết với PayPal và các tổ chức thẻ quốc tế.
2. Quy Trình Trở Thành Merchant Ngân Lượng
- Truy cập NganLuong.vn và đăng ký tài khoản Doanh nghiệp.
- Gửi hồ sơ chứng thực (GPKD, CMND).
- Vào trang quản trị -> Tích hợp thanh toán -> Lấy thông tin API:
<li><code>MERCHANT_ID</code>: Mã kết nối.
- <code>MERCHANT_PASS</code>: Mật khẩu kết nối (Dùng để tạo checksum).
- <code>RECEIVER_EMAIL</code>: Email tài khoản nhận tiền.
</li>
3. Hướng Dẫn Tích Hợp Kỹ Thuật (NganLuong API)
Ngân Lượng hỗ trợ nhiều phiên bản API. Chúng ta sẽ dùng phiên bản mới nhất (Checkout Version 3.1).
Bước 1: Xây dựng URL thanh toán
<code>$nl_server = "https://sandbox.nganluong.vn:8088/nl30/checkout.api.nganluong.post.php"; $merchant_id = "36680"; $merchant_pass = "matkhau123"; $receiver_email = "demo@nganluong.vn";
$order_code = "DH_" . time(); $total_amount = "200000"; $payment_method = "ATM_ONLINE"; // ATM_ONLINE, VISA, IB_ONLINE, NL (Ví NL) $bank_code = "VCB"; // Mã ngân hàng (nếu khách đã chọn trước) $order_description = "Thanh toan don hang $order_code"; $return_url = "https://yourwebsite.com/success.php"; $cancel_url = "https://yourwebsite.com/cancel.php"; $buyer_fullname = "Nguyen Van A"; $buyer_email = "khachhang@gmail.com"; $buyer_mobile = "0909123456";
// Mảng dữ liệu gửi đi $params = array( 'function' => 'SetExpressCheckout', 'version' => '3.1', 'merchant_id' => $merchant_id, 'receiver_email' => $receiver_email, 'merchant_password' => md5($merchant_pass), // Pass phải MD5 trước 'order_code' => $order_code, 'total_amount' => $total_amount, 'payment_method' => $payment_method, 'bank_code' => $bank_code, 'payment_type' => '1', // 1: Thanh toán ngay, 2: Tạm giữ 'order_description' => $order_description, 'return_url' => $return_url, 'cancel_url' => $cancel_url, 'buyer_fullname' => $buyer_fullname, 'buyer_email' => $buyer_email, 'buyer_mobile' => $buyer_mobile );
// Gửi POST Request dùng cURL $post_field = ''; foreach ($params as $key => $value) { if ($post_field != '') $post_field .= '&'; $post_field .= $key . "=" . $value; }
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $nl_server); curl_setopt($ch, CURLOPT_ENCODING, 'UTF-8'); curl_setopt($ch, CURLOPT_VERBOSE, 1); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE); curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, FALSE); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, $post_field); $result = curl_exec($ch); curl_close($ch);
// Xử lý kết quả XML trả về $xml = simplexml_load_string($result); if ($xml->error_code == '00') { // Thành công -> Redirect sang trang thanh toán của Ngân Lượng header("Location: " . (string)$xml->checkout_url); } else { echo "Lỗi: " . $xml->description; }</code></pre>
Bước 2: Xác thực kết quả (Return URL)
<p>Sau khi thanh toán, Ngân Lượng sẽ redirect về <code>return_url</code> kèm theo <code>token</code>. Bạn cần dùng token này để gọi API lấy chi tiết giao dịch (GetTransactionDetail).
<code>// File: success.php $token = $_GET['token'];
// Gọi API GetTransactionDetail để kiểm tra trạng thái thực tế $params_check = array( 'function' => 'GetTransactionDetail', 'version' => '3.1', 'merchant_id' => $merchant_id, 'merchant_password' => md5($merchant_pass), 'token' => $token );
// ... (Gửi cURL tương tự bước 1) ...
if ($xml_result->error_code == '00' && $xml_result->transaction_status == '00') { echo "Giao dịch thành công!"; // Cập nhật Database }</code></pre>
4. Ngân Lượng vs Các Ví Điện Tử Khác
<table><thead><tr><th>Tiêu Chí</th><th>Ngân Lượng</th><th>MoMo / ZaloPay</th></tr></thead><tbody><tr><td>Mô hình</td><td>Cổng trung gian (Aggregator)</td><td>Ví điện tử (Wallet)</td></tr><tr><td>Thế mạnh</td><td>Thanh toán tạm giữ (Bảo vệ người mua)</td><td>Thanh toán nhanh (QR Code)</td></tr><tr><td>Đối tượng phù hợp</td><td>Sàn TMĐT, C2C Marketplace</td><td>Bán lẻ, F&B, Offline</td></tr></tbody></table>
5. Dịch Vụ Của JAYbranding Tại Sao Cần Thiết?
<p>Hệ thống API của Ngân Lượng khá cũ (dùng XML và tham số POST truyền thống) so với các chuẩn JSON RESTful hiện đại. Việc debug lỗi XML thường rất mất thời gian.
- ✅ Chuẩn hóa dữ liệu: JAYbranding xây dựng lớp vỏ (Wrapper) để chuyển đổi dữ liệu từ Website của bạn sang định dạng XML chuẩn của Ngân Lượng.
- ✅ Xử lý hoàn tiền: Tích hợp API Refund, giúp bạn hoàn tiền cho khách chỉ với 1 click từ trang admin.
- ✅ Quản lý tranh chấp: Hệ thống log giúp bạn có bằng chứng gửi sang Ngân Lượng khi có tranh chấp (Khiếu nại chưa nhận hàng).
📞 Build sàn TMĐT chuyên nghiệp cùng JAYbranding! Hotline: 0899991131
FAQ Về Ngân Lượng
[faqs]
#### Thanh toán tạm giữ hoạt động như thế nào?
Tiền của người mua sẽ nằm ở ví trung gian của Ngân Lượng. Sau X ngày (do bạn cấu hình) nếu không có khiếu nại, tiền mới tự động chuyển về ví người bán.
#### Phí rút tiền từ Ngân Lượng về ngân hàng?
Miễn phí với hầu hết các ngân hàng liên kết, hoặc một khoản phí nhỏ nếu rút nóng.
[/faqs]