PHPackages tuanta1992/laravel-vnpay-payment - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Payment Processing](/categories/payments) 4. / 5. tuanta1992/laravel-vnpay-payment ActiveLibrary[Payment Processing](/categories/payments) tuanta1992/laravel-vnpay-payment ================================ VNPay payment gateway integration for Laravel 00PHP Since Mar 15Pushed 1mo agoCompare [ Source](https://github.com/tuanta1992/laravel-vnpay-payment)[ Packagist](https://packagist.org/packages/tuanta1992/laravel-vnpay-payment)[ RSS](/packages/tuanta1992-laravel-vnpay-payment/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (1)DependenciesVersions (1)Used By (0) Laravel VNPay Payment Gateway ============================= [](#laravel-vnpay-payment-gateway) [![Latest Version on Packagist](https://camo.githubusercontent.com/e3eb3c3e5ee8536657551f8e5def940708d284b678240c0245857c8e39f36f17/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7475616e7461313939322f6c61726176656c2d766e7061792d7061796d656e742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tuanta1992/laravel-vnpay-payment)[![Total Downloads](https://camo.githubusercontent.com/fbf55f71a98814b54a3111e9581224ca65fe3eb44ca3ac7427bbc5bc1e80f638/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7475616e7461313939322f6c61726176656c2d766e7061792d7061796d656e742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tuanta1992/laravel-vnpay-payment)[![License](https://camo.githubusercontent.com/9b0e402ebf9fa210c24a9c0d3eb806944b5e71c45b2eadf70a640b9927489126/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7475616e7461313939322f6c61726176656c2d766e7061792d7061796d656e742e7376673f7374796c653d666c61742d737175617265)](LICENSE.md) A Laravel package for integrating [VNPay](https://vnpay.vn) - one of Vietnam's leading online payment gateways. Features -------- [](#features) - Create VNPay payment URLs - Verify Return URL & IPN (Instant Payment Notification) - Query transaction status - Refund transactions (full & partial) - Multiple payment methods (ATM, QR Code, International Cards) - Dual parameter format: simplified (snake\_case) or native VNPay (`vnp_*`) - Artisan commands for testing & status checks - Configurable logging - Laravel 10+ / PHP 8.1+ Requirements ------------ [](#requirements) - PHP >= 8.1 - Laravel >= 10.0 Installation ------------ [](#installation) ``` composer require tuanta1992/laravel-vnpay-payment ``` Publish the config file: ``` php artisan vendor:publish --tag=vnpay-config ``` Configuration ------------- [](#configuration) Add the following to your `.env` file: ``` VNPAY_TMN_CODE=your_tmn_code VNPAY_HASH_SECRET=your_hash_secret VNPAY_ENVIRONMENT=sandbox VNPAY_RETURN_URL="${APP_URL}/vnpay/return" VNPAY_IPN_URL="${APP_URL}/vnpay/ipn" VNPAY_LOCALE=vn VNPAY_EXPIRE_TIME=15 VNPAY_LOG_ENABLED=true VNPAY_TIMEOUT=30 ``` > `VNPAY_TMN_CODE` and `VNPAY_HASH_SECRET` are provided by VNPay when you register as a merchant. Verify your configuration: ``` php artisan vnpay:status ``` Usage ----- [](#usage) ### Create Payment URL [](#create-payment-url) ``` use VNPayPayment\Facades\VNPay; $paymentUrl = VNPay::createPaymentUrl([ 'txn_ref' => 'ORDER_' . time(), 'amount' => 100000, // 100,000 VND 'order_info' => 'Thanh toan don hang #123', 'order_type' => 'billpayment', 'bank_code' => 'VNBANK', // optional ]); return redirect($paymentUrl); ``` **Parameters:** ParameterRequiredDescription`txn_ref`YesUnique transaction reference`amount`YesAmount in VND`order_info`YesOrder description`order_type`No`billpayment`, `topup`, `other``bank_code`NoBank code (see table below)`locale`No`vn` or `en`### Dual Parameter Format [](#dual-parameter-format) This package supports two parameter styles: **Simplified (recommended)** - auto-multiplies amount by 100 and strips Vietnamese accents: ``` VNPay::createPaymentUrl([ 'txn_ref' => 'ORDER123', 'amount' => 100000, // auto becomes 10,000,000 'order_info' => 'Thanh toan don hang', ]); ``` **Native VNPay** - pass parameters exactly as documented by VNPay: ``` VNPay::createPaymentUrl([ 'vnp_TxnRef' => 'ORDER123', 'vnp_Amount' => 10000000, // pre-formatted 'vnp_OrderInfo' => 'Thanh toan don hang', ]); ``` > VNPay requires amounts in the smallest currency unit: 100,000 VND = 10,000,000. ### Verify Return URL [](#verify-return-url) ``` // routes/web.php Route::get('/vnpay/return', [PaymentController::class, 'vnpayReturn']); ``` ``` use VNPayPayment\Facades\VNPay; public function vnpayReturn(Request $request) { $result = VNPay::verifyReturnUrl($request->all()); if ($result['is_success']) { // Payment successful // $result['txn_ref'], $result['transaction_no'], $result['amount'] return view('payment.success', compact('result')); } return view('payment.failed', compact('result')); } ``` **Return data:** `is_valid`, `is_success`, `txn_ref`, `amount`, `transaction_no`, `response_code`, `message` ### Handle IPN (Instant Payment Notification) [](#handle-ipn-instant-payment-notification) ``` // routes/web.php Route::post('/vnpay/ipn', [PaymentController::class, 'vnpayIpn']); ``` ``` use VNPayPayment\Facades\VNPay; public function vnpayIpn(Request $request) { $result = VNPay::verifyIpn($request->all()); if (!$result['is_valid']) { return response()->json(['RspCode' => '97', 'Message' => 'Invalid signature']); } $order = Order::where('txn_ref', $result['txn_ref'])->first(); if (!$order) { return response()->json(['RspCode' => '01', 'Message' => 'Order not found']); } if ($order->amount != $result['amount']) { return response()->json(['RspCode' => '04', 'Message' => 'Invalid amount']); } if ($order->status == 'paid') { return response()->json(['RspCode' => '02', 'Message' => 'Order already confirmed']); } if ($result['is_success']) { $order->update([ 'status' => 'paid', 'vnpay_transaction_no' => $result['transaction_no'], 'paid_at' => now(), ]); } return response()->json(['RspCode' => '00', 'Message' => 'Confirm Success']); } ``` ### Query Transaction [](#query-transaction) ``` $result = VNPay::queryTransaction([ 'txn_ref' => 'ORDER123', 'transaction_date' => '20231225153000', // YmdHis 'order_info' => 'Query transaction', ]); ``` ### Refund Transaction [](#refund-transaction) ``` $result = VNPay::refundTransaction([ 'txn_ref' => 'ORDER123', 'amount' => 100000, 'transaction_type' => '02', // 02: full, 03: partial 'transaction_date' => '20231225153000', 'create_by' => 'admin@example.com', 'order_info' => 'Refund for order #123', ]); ``` ### Helper Methods [](#helper-methods) ``` $bankCodes = VNPay::getBankCodes(); $bankName = VNPay::getBankName('VIETCOMBANK'); $message = VNPay::getResponseMessage('00'); $isSuccess = VNPay::isSuccess('00', '00'); ``` Artisan Commands ---------------- [](#artisan-commands) ``` # Test creating a payment URL php artisan vnpay:test --amount=100000 --txn-ref=TEST123 # Check configuration status php artisan vnpay:status ``` Bank Codes ---------- [](#bank-codes) CodeName`VNPAYQR`VNPay QR`VNBANK`Domestic ATM / Bank account`INTCARD`International card`VIETCOMBANK`Vietcombank`VIETINBANK`VietinBank`BIDV`BIDV`AGRIBANK`Agribank`SACOMBANK`Sacombank`TECHCOMBANK`Techcombank`ACB`ACB`VPBANK`VPBank`TPBANK`TPBank`MBBANK`MBBank`NCB`NCBResponse Codes -------------- [](#response-codes) CodeMeaning`00`Transaction successful`05`Insufficient balance`06`Wrong OTP`07`Suspicious transaction`09`Internet Banking not registered`10`Authentication failed 3+ times`11`Payment timeout`12`Card/Account locked`24`Transaction cancelled by customer`65`Transaction limit exceeded`75`Bank under maintenance`79`Wrong password too many times`99`Unknown errorTransaction Status Codes ------------------------ [](#transaction-status-codes) CodeMeaning`00`Successful`01`Incomplete`02`Error`04`Reversed`05`Processing refund`06`Refund request sent`07`Suspected fraud`08`Payment timeout`09`Refund rejectedTroubleshooting --------------- [](#troubleshooting) **Invalid signature** - Check `VNPAY_HASH_SECRET` in `.env`, then run `php artisan config:clear`. **Order not found** - Verify `txn_ref` is stored correctly. VNPay may call IPN multiple times. **Connection timeout** - Increase `VNPAY_TIMEOUT` in `.env` or check network connectivity to VNPay. Security -------- [](#security) - Always verify checksums from VNPay - Never expose `VNPAY_HASH_SECRET` - Use HTTPS in production - Validate amount and order info - Apply rate limiting to the IPN endpoint Changelog --------- [](#changelog) See [CHANGELOG.md](CHANGELOG.md) for recent changes. Contributing ------------ [](#contributing) Contributions are welcome! Please feel free to submit a Pull Request. License ------- [](#license) The MIT License (MIT). See [LICENSE](LICENSE.md) for more information. ### Health Score 19 — LowBetter than 10% of packages Maintenance58 Moderate activity, may be stable Popularity0 Limited adoption so far Community8 Small or concentrated contributor base Maturity11 Early-stage or recently created project Bus Factor1 Top contributor holds 66.7% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Community Maintainers ![](https://www.gravatar.com/avatar/5e379f56f9897623b3dccd30a640011ce6ed9ea89aa5f046c23c347af100550f?d=identicon)[tuanta1992](/maintainers/tuanta1992) --- Top Contributors [![tuanta1992](https://avatars.githubusercontent.com/u/166894166?v=4)](https://github.com/tuanta1992 "tuanta1992 (2 commits)")[![tuantalangtech](https://avatars.githubusercontent.com/u/236983165?v=4)](https://github.com/tuantalangtech "tuantalangtech (1 commits)") ### Embed Badge ![Health badge](/badges/tuanta1992-laravel-vnpay-payment/health.svg) ``` [![Health](https://phpackages.com/badges/tuanta1992-laravel-vnpay-payment/health.svg)](https://phpackages.com/packages/tuanta1992-laravel-vnpay-payment) ``` ### Alternatives [omnipay/paypal PayPal gateway for Omnipay payment processing library 3156.8M53](/packages/omnipay-paypal)[eduardokum/laravel-boleto Biblioteca com boletos para o laravel 626351.9k2](/packages/eduardokum-laravel-boleto)[tbbc/money-bundle This is a Symfony bundle that integrates moneyphp/money library (Fowler pattern): https://github.com/moneyphp/money. 1961.9M](/packages/tbbc-money-bundle)[2checkout/2checkout-php 2Checkout PHP Library 83740.3k2](/packages/2checkout-2checkout-php)[smhg/sepa-qr-data Generate QR code data for SEPA payments 61717.2k5](/packages/smhg-sepa-qr-data)[omnipay/dummy Dummy driver for the Omnipay payment processing library 271.2M33](/packages/omnipay-dummy) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)