Trong trang này
Tích hợp Laravel
Package tinovn/laravel-tinopay giúp website Laravel nhận webhook giao dịch từ TinoPay: lưu lịch sử giao dịch, chống ghi trùng và bắn event để bạn tự cộng tiền nạp hoặc xác nhận đơn hàng. Package cũng có sẵn hàm tạo link mã VietQR và gọi API lịch sử giao dịch.
Mã nguồn: github.com/tinovn/laravel-tinopay
#Luồng hoạt động
Website hiện mã VietQR (nội dung: <tiền tố><mã>, VD TP123)
│ khách quét và chuyển khoản
▼
Ngân hàng báo có ──► TinoPay trích mã thanh toán TP123
│
▼
POST /api/tinopay/webhook ──► Package lưu giao dịch, bắn TinoPayWebhookEvent("123")
│
▼
Listener của bạn: cộng tiền user 123 / xác nhận đơn 123
#Yêu cầu
- PHP 8.0 trở lên, Laravel 9 – 13.
- Tài khoản TinoPay và ít nhất một tài khoản ngân hàng đã kết nối. Với BIDV dùng tài khoản ảo (VA) nhận tiền.
#Cài đặt
#Bước 1 — Cài package
composer require tinovn/laravel-tinopay
Publish và chạy migration (tạo bảng tinopay_transactions):
php artisan vendor:publish --tag="tinopay-migrations"
php artisan migrate
Publish file cấu hình (tuỳ chọn, khi cần sửa giá trị mặc định):
php artisan vendor:publish --tag="tinopay-config"
#Bước 2 — Cấu hình .env
TINOPAY_WEBHOOK_TOKEN=chuoi_bi_mat_ngau_nhien
TINOPAY_MATCH_PATTERN=TP
# Tuỳ chọn
TINOPAY_URL=https://ipn.pay.tino.vn
TINOPAY_API_TOKEN=
TINOPAY_QR_TEMPLATE=default
| Biến | Mô tả |
|---|---|
TINOPAY_WEBHOOK_TOKEN |
Chuỗi bí mật, phải trùng Token xác thực của webhook ở bước 3. |
TINOPAY_MATCH_PATTERN |
Tiền tố mã thanh toán, trùng Cấu trúc mã thanh toán trên TinoPay. Mặc định TP. |
TINOPAY_URL |
Địa chỉ TinoPay, mặc định https://ipn.pay.tino.vn. Môi trường thử nghiệm: https://ote.allpay.vn. |
TINOPAY_API_TOKEN |
API Token, chỉ cần khi gọi TinoPay::transactions(). |
TINOPAY_QR_TEMPLATE |
default (khung TinoPay kèm logo ngân hàng) hoặc only-qr. |
#Bước 3 — Cấu hình trên TinoPay
- Cài đặt → Cấu trúc mã thanh toán: thêm tiền tố trùng
TINOPAY_MATCH_PATTERN(ví dụTP). - Tích hợp → Webhooks → Thêm webhook:
| Trường | Giá trị |
|---|---|
| URL nhận webhook | https://<domain-của-bạn>/api/tinopay/webhook |
| Tài khoản ngân hàng | Tài khoản nhận tiền (chọn VA nếu dùng BIDV) |
| Token xác thực | Trùng TINOPAY_WEBHOOK_TOKEN |
| Sự kiện | Tiền vào (chọn Tất cả nếu cần xử lý cả tiền ra) |
#Bước 4 — Viết listener
Mỗi webhook hợp lệ được lưu vào bảng tinopay_transactions. Nếu tìm thấy mã thanh toán (field code, nếu trống thì tìm trong content), package bắn TinoPayWebhookEvent với $info là phần sau tiền tố: TP123 → 123.
php artisan make:listener TinoPayWebhookListener
<?php
namespace App\Listeners;
use App\Models\User;
use TinoPay\TinoPay\Events\TinoPayWebhookEvent;
use TinoPay\TinoPay\Notifications\TinoPayTopUpSuccessNotification;
class TinoPayWebhookListener
{
public function handle(TinoPayWebhookEvent $event): void
{
$data = $event->tinoPayWebhookData;
if ($data->transferType !== 'in') {
return;
}
// $info là user id (nội dung chuyển khoản TP<user id>)
$user = User::query()->find($event->info);
if ($user) {
$user->increment('balance', $data->transferAmount);
$user->notify(new TinoPayTopUpSuccessNotification($data));
}
}
}
- Laravel 11 trở lên: listener trong
app/Listenersđược tự gắn với event, không cần đăng ký thêm (đăng ký thêm sẽ chạy 2 lần). Nếu listener chưa chạy, thêm vàoboot()củaAppServiceProvider:
\Illuminate\Support\Facades\Event::listen(
\TinoPay\TinoPay\Events\TinoPayWebhookEvent::class,
\App\Listeners\TinoPayWebhookListener::class,
);
- Laravel 10 trở xuống: thêm vào mảng
$listentrongapp/Providers/EventServiceProvider.php.
TinoPayWebhookData gồm: transactionId, gateway, transactionDate, accountNumber, virtualAccount, code, content, transferType, transferAmount, referenceCode.
#Bước 5 — Kiểm tra
Gửi thử một webhook (thay domain và token):
curl -X POST 'https://<domain-của-bạn>/api/tinopay/webhook' \
-H 'Content-Type: application/json' \
-H 'Authorization: Apikey chuoi_bi_mat_ngau_nhien' \
-d '{
"transaction_id": "TEST-0001",
"gateway": "BIDV",
"transactionDate": "2026-10-27 10:00:00",
"accountNumber": "1234567890",
"code": "TP1",
"content": "TP1 nap tien",
"transferType": "in",
"transferAmount": 100000,
"referenceCode": "FT0001",
"virtualAccount": null
}'
Phản hồi {"success":true,"message":"OK"} và bảng tinopay_transactions có thêm một dòng là đã nhận được. Sau đó chuyển khoản thật một khoản nhỏ và xem chi tiết lần gửi ở Tích hợp → Lịch sử webhook trên TinoPay.
#Mã VietQR và API
use TinoPay\TinoPay\Facades\TinoPay;
// Link ảnh VietQR (PNG). BIDV: điền số tài khoản ảo (VA). Nội dung tối đa 25 ký tự.
$src = TinoPay::qrUrl('BIDV', 'V4ABCSHOP', amount: 150000, memo: 'TP'.$user->id, accountName: 'CONG TY ABC');
// Danh sách ngân hàng: code, name, shortName, bin, ...
$banks = TinoPay::banks();
// Lịch sử giao dịch (cần TINOPAY_API_TOKEN). Mặc định trong ngày, tối đa 90 ngày.
$page = TinoPay::transactions([
'type' => 'in',
'transaction_date_from' => '2026-10-01',
'transaction_date_to' => '2026-10-27',
'per_page' => 50,
]);
<img src="{{ TinoPay::qrUrl('BIDV', 'V4ABCSHOP', $order->total, 'TP'.$order->id) }}" alt="Mã QR thanh toán">
Chi tiết tham số: Tạo mã QR (VietQR), Danh sách ngân hàng, Lịch sử giao dịch.
#Phản hồi webhook
| Kết quả | Mã HTTP |
|---|---|
| Ghi nhận thành công | 200 |
Giao dịch đã ghi nhận (trùng transaction_id), bỏ qua |
200 |
| Sai token | 401 |
JSON lỗi, thiếu cả transaction_id lẫn referenceCode |
400 |
TinoPay tự gửi lại webhook khi nhận mã lỗi (non-2xx). Gửi lại cùng giao dịch không bị ghi trùng — xem Phản hồi, Retry & Logs.
#Xử lý sự cố
| Hiện tượng | Nguyên nhân thường gặp |
|---|---|
Lịch sử webhook báo 401 |
TINOPAY_WEBHOOK_TOKEN khác Token xác thực của webhook trên TinoPay, hoặc chưa chạy php artisan config:clear sau khi sửa .env. |
Lịch sử webhook báo 404 |
Sai URL, hoặc package chưa được nạp (chạy php artisan route:list --path=tinopay để kiểm tra). |
Lịch sử webhook báo 500 |
Chưa chạy migration (thiếu bảng tinopay_transactions), hoặc listener ném lỗi — xem storage/logs/laravel.log. |
| Có giao dịch trong bảng nhưng listener không chạy | Nội dung chuyển khoản không có mã đúng tiền tố TINOPAY_MATCH_PATTERN, hoặc listener chưa được đăng ký. |
| Listener chạy 2 lần | Laravel 11+ đã tự gắn listener, xoá phần đăng ký thủ công. |