Bỏ qua tới nội dung
Tài liệu Lấy API Token
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

  1. Cài đặt → Cấu trúc mã thanh toán: thêm tiền tố trùng TINOPAY_MATCH_PATTERN (ví dụ TP).
  2. 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ào boot() của AppServiceProvider:
\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 $listen trong app/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.