CartModules: VNPay Payment Gateway

Accept VNPay Payments in Your CS-Cart Store

Integrate VNPay -- Vietnam's leading payment gateway -- directly into your CS-Cart or Multi-Vendor store. Customers can pay using bank transfers, credit/debit cards, QR codes, and e-wallets through a secure hosted checkout page with HMAC-SHA512 signature verification.

Key Features

• VNPay Hosted Payment Page -- Customers pay on VNPay's secure page supporting multiple payment methods
• Redirect-Based Flow -- No sensitive data touches your server (PCI SAQ A compliant)
• HMAC-SHA512 Signature Verification -- Cryptographic verification of all payment responses using hash_equals()
• Amount Verification -- Returned payment amount is verified against the original order total
• Sandbox/Production Toggle -- Switch between test and live environments from the admin panel
• Configurable Order Statuses -- Map VNPay response codes to any CS-Cart order status
• Payment Page Language -- Choose Vietnamese or English for the VNPay payment page
• Bank Pre-selection -- Optionally pre-select a bank code (e.g., NCB, VNPAYQR) for faster checkout
• Idempotent Callbacks -- Duplicate callbacks are safely ignored
• VND Currency -- Native Vietnamese Dong support

Requirements

• CS-Cart or Multi-Vendor 4.x
• PHP 7.1 or higher
• VNPay merchant account with Terminal ID and Hash Secret
• Store currency set to VND (Vietnamese Dong)

How It Works

1. Customer selects VNPay at checkout and clicks "Place Order"
2. The addon builds payment parameters and computes an HMAC-SHA512 signature
3. Customer is redirected to VNPay's hosted payment page
4. Customer selects their bank and completes payment (bank transfer, card, QR, or e-wallet)
5. VNPay redirects back with signed response parameters
6. The addon verifies the signature, validates the amount, and updates the order status

Supported Payment Methods (via VNPay)

• Domestic ATM/debit cards (40+ Vietnamese banks)
• International credit/debit cards (Visa, MasterCard, JCB, etc.)
• VNPay QR code payments
• E-wallets
• Bank account transfers

Installation

1. Go to Add-ons > Manage add-ons, click Manual installation, and upload the addon zip
2. Activate the addon and enter the license key
3. Go to Administration > Payment methods and create a new payment method
4. Select "VNPay Payment Gateway" as the processor
5. Enter your Terminal ID (vnp_TmnCode) and Hash Secret from the VNPay merchant portal
6. Configure language, bank code, and order status mappings as desired
7. Save and test with sandbox mode before going live

Country & Currency

This addon is designed for merchants selling in Vietnam. VNPay exclusively supports VND (Vietnamese Dong). Ensure your store's primary currency is VND.