> LARAVEL 13.x DOCS

Giao diện

Laravel Cashier (Stripe) ​

Nguồn gốc: Bản dịch từ Laravel Cashier (Stripe)

Giới thiệu (Introduction) ​

Laravel Cashier Stripe cung cấp interface diễn đạt, fluent cho dịch vụ thanh toán subscription của Stripe. Nó xử lý gần như toàn bộ boilerplate code cho subscription billing mà bạn e ngại phải viết. Ngoài quản lý subscription cơ bản, Cashier còn xử lý coupon, swap subscription, subscription "quantities", grace period hủy, và thậm chí tạo PDF hóa đơn.

Nâng cấp Cashier (Upgrading Cashier) ​

Khi nâng cấp, hãy đọc kỹ hướng dẫn nâng cấp.

Cashier sử dụng phiên bản Stripe API cố định. Cashier 16 dùng Stripe API version 2025-06-30.basil. Phiên bản API sẽ được cập nhật trong minor release.

Cài đặt (Installation) ​

bash
composer require laravel/cashier

Publish migration:

bash
php artisan vendor:publish --tag="cashier-migrations"

Chạy migration:

bash
php artisan migrate

Migration sẽ thêm cột vào bảng users và tạo bảng subscriptions, subscription_items.

Publish config (tùy chọn):

bash
php artisan vendor:publish --tag="cashier-config"

LƯU Ý

Stripe khuyến nghị cột lưu Stripe identifier nên case-sensitive. Đảm bảo collation cột stripe_id là utf8_bin khi dùng MySQL.

Cấu hình (Configuration) ​

Billable Model ​

Thêm trait Billable vào model (thường là App\Models\User):

php
use Laravel\Cashier\Billable;

class User extends Authenticatable
{
    use Billable;
}

Nếu dùng model khác:

php
use App\Models\Cashier\User;
use Laravel\Cashier\Cashier;

public function boot(): void
{
    Cashier::useCustomerModel(User::class);
}

API Keys ​

Cấu hình Stripe API keys trong .env:

env
STRIPE_KEY=your-stripe-key
STRIPE_SECRET=your-stripe-secret
STRIPE_WEBHOOK_SECRET=your-stripe-webhook-secret

Currency Configuration ​

Tiền tệ mặc định là USD. Thay đổi qua biến môi trường:

env
CASHIER_CURRENCY=eur
CASHIER_CURRENCY_LOCALE=nl_BE

Quickstart ​

Cashier cung cấp 2 luồng thanh toán chính:

  • Selling Products — Bán sản phẩm one-time qua Stripe Checkout
  • Selling Subscriptions — Bán subscription định kỳ

Customers ​

Cashier cung cấp các phương thức quản lý customer:

  • Retrieving Customers — Lấy thông tin customer từ Stripe
  • Creating Customers — Tạo customer trên Stripe
  • Updating Customers — Cập nhật thông tin
  • Balances — Quản lý số dư
  • Tax IDs — Quản lý mã số thuế
  • Billing Portal — Tạo link đến Stripe Billing Portal

Payment Methods ​

  • Storing — Lưu phương thức thanh toán
  • Retrieving — Lấy danh sách phương thức đã lưu
  • Updating Default — Cập nhật phương thức mặc định
  • Adding / Deleting — Thêm / Xóa phương thức

Subscriptions ​

  • Creating Subscriptions — Tạo subscription mới
  • Checking Status — Kiểm tra trạng thái (active, canceled, past due, trial...)
  • Changing Prices — Thay đổi giá
  • Subscription Quantity — Quản lý số lượng
  • Multiple Products — Subscription với nhiều sản phẩm
  • Usage Based Billing — Thanh toán theo mức sử dụng
  • Subscription Taxes — Thuế subscription
  • Cancelling / Resuming — Hủy / Khôi phục subscription

Subscription Trials ​

  • With Payment Method Up Front — Trial yêu cầu phương thức thanh toán
  • Without Payment Method Up Front — Trial không cần thanh toán trước
  • Extending Trials — Gia hạn trial

Xử lý Stripe Webhooks ​

Cashier tự động xử lý các webhook phổ biến. Bạn có thể định nghĩa thêm handler và xác thực webhook signature.

Single Charges ​

  • Simple Charge — Tính phí đơn giản
  • Charge With Invoice — Tính phí kèm hóa đơn
  • Creating Payment Intents — Tạo Payment Intent
  • Refunding Charges — Hoàn tiền

Invoices ​

  • Retrieving Invoices — Lấy danh sách hóa đơn
  • Upcoming Invoices — Xem hóa đơn sắp tới
  • Generating Invoice PDFs — Tạo PDF hóa đơn

Checkout ​

Cashier hỗ trợ Stripe Checkout cho:

  • Product Checkouts
  • Single Charge Checkouts
  • Subscription Checkouts
  • Guest Checkouts

Xử lý thanh toán thất bại (Handling Failed Payments) ​

Cashier xử lý thanh toán thất bại và cung cấp trang xác nhận thanh toán (payment confirmation page).

Strong Customer Authentication (SCA) ​

Hỗ trợ xác thực khách hàng mạnh theo yêu cầu EU, bao gồm xử lý thanh toán cần xác nhận bổ sung và thông báo thanh toán off-session.

Testing ​

Khi testing, sử dụng Stripe test mode và môi trường sandbox.