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. tuanta1992/laravel-vnpay-payment

ActiveLibrary

tuanta1992/laravel-vnpay-payment
================================

VNPay payment gateway integration for Laravel

00PHP

Since Mar 15Pushed 1w 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 today

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 &amp; IPN (Instant Payment Notification)
- Query transaction status
- Refund transactions (full &amp; partial)
- Multiple payment methods (ATM, QR Code, International Cards)
- Dual parameter format: simplified (snake\_case) or native VNPay (`vnp_*`)
- Artisan commands for testing &amp; status checks
- Configurable logging
- Laravel 10+ / PHP 8.1+

Requirements
------------

[](#requirements)

- PHP &gt;= 8.1
- Laravel &gt;= 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

21

—

LowBetter than 21% of packages

Maintenance64

Regular maintenance activity

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)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)
