Hướng dẫn chức năng thanh toán trong laravel

Laravel Cashier cung cấp một interface dễ hiểu, rõ ràng cho các dịch vụ thanh toán subscription trực tuyến như Stripe's. Nó gần như đã xử lý tất cả các đoạn code mà bạn đang sợ viết mà có liên quan đến các phần thanh toán subscription. Ngoài quản lý subscription cơ bản, Cashier cũng có thể xử lý cả các phiếu giảm giá, chuyển đổi subscription, đăng ký "nhiều" subscription, thời hạn hủy bỏ và thậm chí là tạo các file hóa đơn PDF.

Cập nhật Cashier

Khi nâng cấp lên phiên bản mới của Cashier, điều quan trọng là bạn phải xem kỹ hướng dẫn nâng cấp.

{note} Để tránh các thay đổi nghiêm trọng, Cashier sẽ sử dụng một phiên bản API Stripe cố định. Cashier 12 sẽ sử dụng phiên bản API Stripe

php artisan migrate

13. Phiên bản API Stripe này sẽ được cập nhật thành các bản phát hành nhỏ để sử dụng các tính năng và cải tiến mới của Stripe.

Cài đặt

Đầu tiên, thêm package Cashier cho Stripe với Composer:

composer require laravel/cashier

{note} Để đảm bảo Cashier xử lý đúng tất cả các event của Stripe, hãy nhớ .

Database Migrations

Service provider của Cashier sẽ đăng ký thư mục migration database của chính nó, vì vậy hãy nhớ migration cơ sở dữ liệu của bạn sau khi cài đặt package. Việc migration Cashier sẽ thêm một số cột vào bảng

php artisan migrate

14 của bạn cũng như tạo một bảng

php artisan migrate

15 mới để chứa tất cả các đăng ký của khách hàng của bạn:

php artisan migrate

Nếu bạn cần ghi đè các migration đi kèm với package Cashier, bạn có thể export chúng bằng lệnh Artisan

php artisan migrate

16:

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

Nếu bạn muốn ngăn việc migration của Cashier chạy, bạn có thể sử dụng phương thức

php artisan migrate

17 được Cashier cung cấp. Thông thường, phương thức này nên được gọi trong phương thức

php artisan migrate

18 trong

php artisan migrate

19 của bạn:

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

{note} Stripe khuyến cáo rằng bất kỳ cột nào được sử dụng để lưu trữ Stripe identifier phải phân biệt giữa chữ hoa và chữ thường. Do đó, bạn nên đảm bảo collation cho cột

php artisan migrate

20 được set thành, ví dụ:

php artisan migrate

21 trong MySQL. Có thể hiểu thêm thông tin .

Cấu hình

Billable Model

Trước khi sử dụng Cashier, hãy thêm trait

php artisan migrate

22 vào định nghĩa model của bạn. Trait này sẽ cung cấp các phương thức khác nhau cho phép bạn thực hiện các tác vụ thanh toán phổ biến, chẳng hạn như tạo subscription, áp dụng phiếu giảm giá hoặc cập nhật thông tin phương thức thanh toán:

use Laravel\Cashier\Billable;
class User extends Authenticatable
{
    use Billable;
}

Cashier sẽ giả định rằng billable model của bạn sẽ là class

php artisan migrate

23 đi kèm với Laravel. Nếu bạn muốn thay đổi điều này, bạn có thể chỉ định một model khác trong file

php artisan migrate

24 của bạn:

CASHIER_MODEL=App\User

{note} Nếu bạn đang sử dụng model khác, khác với model

php artisan migrate

23 do Laravel cung cấp, bạn sẽ cần export và thay đổi được cung cấp để khớp với tên bảng của model thay thế mà bạn muốn.

API Keys

Tiếp theo, bạn nên cấu hình key của Stripe trong file

php artisan migrate

24 của bạn. Bạn có thể lấy khóa API Stripe của bạn từ bảng điều khiển của Stripe.

STRIPE_KEY=your-stripe-key
STRIPE_SECRET=your-stripe-secret

Cấu hình loại tiền

Đơn vị tiền mặc định của Cashier là Đô la Mỹ (USD). Bạn có thể thay đổi loại tiền mặc định này bằng cách set biến môi trường

php artisan migrate

27:

CASHIER_CURRENCY=eur

Ngoài việc cấu hình đơn vị tiền tệ của Cashier, bạn cũng có thể chỉ định ngôn ngữ được sử dụng khi định dạng tiền tệ để hiển thị trong hóa đơn. Cashier sử dụng class

php artisan migrate

28 của PHP để set ngôn ngữ tiền tệ:

CASHIER_CURRENCY_LOCALE=nl_BE

{note} Để sử dụng các ngôn ngữ khác, khác với ngôn ngữ

php artisan migrate

29, hãy đảm bảo là extension của PHP

php artisan migrate

30 đã được cài đặt và cấu hình trên server của bạn.

Logging

Cashier cho phép bạn chỉ định channel log sẽ được sử dụng khi ghi log tất cả các exception liên quan đến Stripe. Bạn có thể chỉ định channel log này bằng cách sử dụng biến môi trường

php artisan migrate

31:

CASHIER_LOGGER=stack

Customers

Lấy Customers

Bạn có thể lấy ra một khách hàng bằng ID Stripe của họ thông qua phương thức

php artisan migrate

32. Điều này sẽ trả về một instance của Billable model:

php artisan migrate

0

Tạo Customers

Đôi khi, bạn có thể muốn tạo một Stripe customer mà không cần phải đăng ký. Bạn có thể thực hiện việc này bằng phương thức

php artisan migrate

33:

php artisan migrate

1

Khi customer đã được tạo trong Stripe, bạn có thể bắt đầu subscription. Bạn cũng có thể sử dụng mảng tùy chọn

php artisan migrate

34 để truyền vào bất kỳ tham số bổ sung nào mà được hỗ trợ bởi API Stripe:

php artisan migrate

2

Bạn có thể sử dụng phương thức

php artisan migrate

35 nếu bạn muốn trả về một đối tượng customer nếu billable đã là một customer trong Stripe:

php artisan migrate

3

Phương thức

php artisan migrate

36 có thể được sử dụng nếu bạn muốn trả về một đối tượng customer nhưng không chắc liệu billable đã là customer trong Stripe hay chưa. Phương thức này sẽ tạo ra một customer mới trong Stripe nếu customer đó chưa tồn tại:

php artisan migrate

4

Cập nhật Customers

Đôi khi, bạn có thể muốn cập nhật trực tiếp thông tin cho customer của Stripe. Bạn có thể thực hiện việc này bằng phương pháp

php artisan migrate

37:

php artisan migrate

5

Cổng thanh toán

Stripe cung cấp một cách dễ dàng để thiết lập một cổng thanh toán để customer của bạn có thể quản lý subscription, phương thức thanh toán và xem lại lịch sử thanh toán của họ. Bạn có thể chuyển hướng người dùng của bạn đến cổng thanh toán bằng phương pháp

php artisan migrate

38 từ một controller hoặc một route:

php artisan migrate

6

Mặc định, khi người dùng kết thúc việc quản lý subscription của họ, họ có thể muốn quay lại route

php artisan migrate

39 của ứng dụng của bạn. Bạn có thể cung cấp URL tùy biến mà người dùng sẽ được quay lại bằng cách truyền URL làm tham số cho phương thức

php artisan migrate

38:

php artisan migrate

7

Nếu bạn chỉ muốn tạo URL cho cổng thanh toán, bạn có thể sử dụng phương thức

php artisan migrate

41:

php artisan migrate

8

Phương thức thanh toán

Lưu phương thức thanh toán

Để tạo một subscription hoặc thực hiện tính phí "một lần" với Stripe, bạn sẽ cần lưu phương thức thanh toán và lấy identifier của phương thức đó từ Stripe. Cách tiếp cận được sử dụng theo mục đích khác nhau dựa trên việc bạn sẽ sử dụng phương thức thanh toán này cho việc thanh toán các subscription hay các khoản phí một lần, vì vậy chúng ta sẽ xem xét cả hai ví dụ bên dưới.

Phương thức thanh toán cho Subscription

Khi lưu trữ thẻ tín dụng cho khách hàng để sử dụng trong tương lai, API Setup Intent của Stripe sẽ phải được sử dụng để thu thập thông tin chi tiết về phương thức thanh toán của khách hàng. "Setup Intent" cho biết ý định tính phí phương thức thanh toán của khách hàng. Trait

php artisan migrate

22 của Cashier có chứa một

php artisan migrate

43 để dễ dàng tạo một Setup Intent mới. Bạn nên gọi phương thức này từ route hoặc controller sẽ hiển thị form thu thập chi tiết phương thức thanh toán cho khách hàng của bạn:

php artisan migrate

9

Sau khi bạn đã tạo xong Setup Intent và truyền nó đến view, bạn nên gắn secret của intent đó vào trong element sẽ thu thập phương thức thanh toán. Ví dụ: hãy xem xét form "cập nhật phương thức thanh toán" này:

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

0

Tiếp theo, thư viện Stripe.js có thể sử dụng element đó để gắn các element Stripe cần thiết vào form và thu thập chi tiết thanh toán của khách hàng một cách an toàn:

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

1

Tiếp theo, thẻ có thể được xác minh và một "identifier cho phương thức thanh toán" an toàn có thể được lấy ra từ Stripe bằng cách sử dụng phương thức

php artisan migrate

44 của Stripe:

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

2

Sau khi thẻ đã được Stripe xác minh, bạn có thể truyền kết quả identifier

php artisan migrate

45 vào ứng dụng Laravel của bạn, nơi nó có thể được lưu với thông tin khách hàng. Phương thức thanh toán này có thể được hoặc . Bạn cũng có thể sử dụng ngay identifier phương thức thanh toán này để .

{tip} Nếu bạn muốn biết thêm thông tin về Setup Intent và cách thu thập chi tiết thanh toán của khách hàng, vui lòng .

Phương thức thanh toán cho phí

Tất nhiên, khi thực hiện một khoản tính phí một lần đối với một phương thức thanh toán của khách hàng, chúng ta sẽ chỉ cần sử dụng một identifier phương thức thanh toán trong một lần duy nhất. Do các giới hạn của Stripe, bạn không thể sử dụng phương thức thanh toán mặc định của khách hàng cho các khoản tính phí một lần. Bạn phải cho phép khách hàng nhập chi tiết phương thức thanh toán của họ bằng thư viện Stripe.js. Ví dụ, hãy xem xét form sau:

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

3

Tiếp theo, thư viện Stripe.js có thể sử dụng element đó để gắn các element Stripe cần thiết vào form và thu thập chi tiết thanh toán của khách hàng một cách an toàn:

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

1

Tiếp theo, thẻ có thể được xác minh và một "identifier cho phương thức thanh toán" an toàn có thể được lấy ra từ Stripe bằng cách sử dụng :

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

5

Nếu thẻ được xác minh thành công, bạn có thể truyền

php artisan migrate

47 vào ứng dụng Laravel của bạn và xử lý tiếp .

Lấy phương thức thanh toán

Phương thức

php artisan migrate

48 trên instance Billable model sẽ trả về một collection các instance

php artisan migrate

49:

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

6

Để lấy phương thức thanh toán mặc định, phương thức

php artisan migrate

50 có thể được sử dụng:

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

7

Bạn cũng có thể lấy ra một phương thức thanh toán cụ thể thuộc sở hữu của một Billable model bằng cách sử dụng phương thức

php artisan migrate

51:

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

8

Xác định người dùng có phương thức thanh toán hay không

Để xác định xem một Billable model có phương thức thanh toán mặc định được gắn với tài khoản của họ hay không, hãy sử dụng phương thức

php artisan migrate

52:

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

9

Để xác định xem Billable model có ít nhất một phương thức thanh toán được gắn với tài khoản của họ hay không, hãy sử dụng phương thức

php artisan migrate

53:

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

0

Cập nhật phương thức thanh toán mặc định

Phương thức

php artisan migrate

54 có thể được sử dụng để cập nhật thông tin về phương thức thanh toán mặc định của khách hàng. Phương thức này chấp nhận một identifier phương thức thanh toán của Stripe và sẽ gắn phương thức thanh toán mới làm phương thức thanh toán hóa đơn mặc định:

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

1

Để đồng bộ thông tin phương thức thanh toán mặc định của bạn với thông tin phương thức thanh toán mặc định của khách hàng trong Stripe, bạn có thể sử dụng phương thức

php artisan migrate

55:

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

2

{note} Phương thức thanh toán mặc định của khách hàng chỉ có thể được sử dụng để lập hóa đơn và tạo một subscription mới. Do những hạn chế từ Stripe, nó không thể được sử dụng cho các khoản tính phí một lần.

Thêm phương thức thanh toán

Để thêm một phương thức thanh toán mới, bạn có thể gọi phương thức

php artisan migrate

56 trên một model billable user, và truyền identifier phương thức thanh toán:

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

3

{tip} Để tìm hiểu cách lấy identifier phương thức thanh toán, vui lòng xem lại .

Xoá phương thức thanh toán

Để xóa một phương thức thanh toán, bạn có thể gọi phương thức

php artisan migrate

57 trên instance

php artisan migrate

49 mà bạn muốn xóa:

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

4

Phương thức

php artisan migrate

59 sẽ xóa tất cả thông tin về phương thức thanh toán cho một Billable model:

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

5

{note} Nếu người dùng có một subscription đang hoạt động, bạn nên ngăn họ xóa phương thức thanh toán mặc định của họ.

Subscriptions

Tạo Subscription

Để tạo một subscription, trước tiên hãy lấy ra một instance Billable model của bạn, thường là một instance của

php artisan migrate

23. Khi bạn đã lấy được instance của model, bạn có thể sử dụng phương thức

php artisan migrate

61 để tạo ra một subscription cho model:

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

6

Tham số đầu tiên được truyền cho phương thức

php artisan migrate

61 phải là tên của subscription. Nếu ứng dụng của bạn chỉ cung cấp một loại subscription duy nhất, bạn có thể gọi nó là

php artisan migrate

63 hoặc

php artisan migrate

64. Tham số thứ hai là gói cụ thể mà người dùng đang subscription. Giá trị này phải tương ứng với price identifier của gói trong Stripe.

Phương thức

php artisan migrate

65, chấp nhận hoặc đối tượng Stripe

php artisan migrate

66, sẽ bắt đầu đăng ký subscription cũng như cập nhật cơ sở dữ liệu của bạn với ID của khách hàng và thông tin thanh toán có liên quan khác.

{note} Việc truyền trực tiếp identifier phương thức thanh toán vào phương thức subscription

php artisan migrate

67 cũng sẽ tự động thêm identifier đó vào danh sách các phương thức thanh toán được lưu của người dùng đó.

Quantities

Nếu bạn muốn set một số lượng cụ thể các gói khi tạo subscription, bạn có thể sử dụng phương thức

php artisan migrate

68:

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

7

Additional Details

Nếu bạn muốn thêm chi tiết khách hàng hoặc subscription, bạn có thể làm bằng cách truyền chúng làm tham số thứ hai và tham số thứ ba cho phương thức

php artisan migrate

65:

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

8

Để tìm hiểu thêm về các field được hỗ trợ bởi Stripe, hãy xem và tạo subscription của Stripe.

Coupons

Nếu bạn muốn áp dụng phiếu giảm giá khi tạo subscription, bạn có thể sử dụng phương thức

php artisan migrate

70:

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

9

Adding Subscriptions

Nếu bạn muốn thêm một subscription cho một khách hàng đã có sẵn phương thức thanh toán mặc định, bạn có thể sử dụng phương thức

php artisan migrate

71 khi sử dụng phương thức

php artisan migrate

61:

use Laravel\Cashier\Billable;
class User extends Authenticatable
{
    use Billable;
}

0

Kiểm tra trạng thái Subscription

Khi người dùng đã subscription vào application của bạn, bạn có thể dễ dàng kiểm tra trạng thái subscription của họ bằng nhiều phương thức thuận tiện khác nhau. Đầu tiên, phương thức

php artisan migrate

73 sẽ trả về

php artisan migrate

74 nếu người dùng đó có active subscription, ngay cả khi subscription hiện tại đang trong thời gian dùng thử:

use Laravel\Cashier\Billable;
class User extends Authenticatable
{
    use Billable;
}

1

Phương thức

php artisan migrate

73 cũng là một cách tuyệt vời cho một route middleware, cho phép bạn lọc quyền truy cập vào các route hoặc các controller dựa trên trạng thái subscription của người dùng:

use Laravel\Cashier\Billable;
class User extends Authenticatable
{
    use Billable;
}

2

Nếu bạn muốn xác định xem người dùng đó có còn trong thời gian dùng thử hay không, bạn có thể sử dụng phương thức

php artisan migrate

76. Phương thức này có thể hữu ích để hiển thị cảnh báo cho người dùng biết rằng họ vẫn đang trong thời gian dùng thử:

use Laravel\Cashier\Billable;
class User extends Authenticatable
{
    use Billable;
}

3

Phương thức

php artisan migrate

77 có thể được sử dụng để xác định xem người dùng có đăng ký gói dịch vụ đã cho hay không dựa vào Price ID của gói đó trong Stripe. Trong ví dụ này, chúng ta sẽ xác định xem subscription

php artisan migrate

63 của người dùng có đăng ký gói

php artisan migrate

79 hay không:

use Laravel\Cashier\Billable;
class User extends Authenticatable
{
    use Billable;
}

4

Bằng cách truyền một mảng cho phương thức

php artisan migrate

77, bạn có thể xác định xem subscription

php artisan migrate

63 của người dùng có được đăng ký với gói

php artisan migrate

79 hay

php artisan migrate

83 hay không:

use Laravel\Cashier\Billable;
class User extends Authenticatable
{
    use Billable;
}

5

Phương thức

php artisan migrate

84 có thể được sử dụng để xác định xem người dùng hiện tại có đang đăng ký và không còn trong thời gian dùng thử hay không:

use Laravel\Cashier\Billable;
class User extends Authenticatable
{
    use Billable;
}

6

Cancelled Subscription Status

Để xác định xem người dùng đã từng subscription, nhưng sau đó đã hủy, bạn có thể sử dụng phương thức

php artisan migrate

85:

use Laravel\Cashier\Billable;
class User extends Authenticatable
{
    use Billable;
}

7

Bạn cũng có thể xác định xem người dùng đã hủy subscription của họ hay chưa, hay vẫn còn trong "thời gian có hiệu lực" cho đến khi subscription hết hạn. Ví dụ: nếu người dùng hủy subscription vào ngày 5 tháng 3 mà dự kiến ban đầu là sẽ hết hạn vào ngày 10 tháng 3, thì người dùng sẽ ở trong "thời gian có hiệu lực" của họ cho đến ngày 10 tháng 3. Lưu ý rằng phương thức

php artisan migrate

73 vẫn trả về

php artisan migrate

74 trong thời gian này:

use Laravel\Cashier\Billable;
class User extends Authenticatable
{
    use Billable;
}

8

Để xác định xem người dùng đã hủy subscription và không còn trong "thời gian subscription" của họ, bạn có thể sử dụng phương thức

php artisan migrate

88:

use Laravel\Cashier\Billable;
class User extends Authenticatable
{
    use Billable;
}

9

Subscription Scopes

Hầu hết các trạng thái subscription cũng có sẵn dưới dạng query scope giúp cho bạn có thể dễ dàng truy vấn dữ liệu subscription của bạn ở một trạng thái nhất định:

CASHIER_MODEL=App\User

0

Dưới đây là một danh sách đầy đủ các scope có sẵn:

CASHIER_MODEL=App\User

1

Incomplete and Past Due Status

Nếu subscription yêu cầu một hành động thanh toán phụ sau khi được tạo, thì subscription sẽ được đánh dấu là

php artisan migrate

89. Trạng thái của subscription được lưu trong cột

php artisan migrate

90 trong bảng

php artisan migrate

91 của Cashier.

Tương tự, nếu hành động thanh toán phụ được yêu cầu khi hoán đổi gói, subscription sẽ được đánh dấu là

php artisan migrate

92. Khi subscription của bạn ở một trong hai trạng thái này, subscription sẽ không được active cho đến khi khách hàng xác nhận thanh toán. Để kiểm tra xem subscription có được thanh toán hay chưa, bạn có thể thực hiện bằng cách sử dụng phương thức

php artisan migrate

93 trên Billable model hoặc một instance subscription:

CASHIER_MODEL=App\User

2

Khi một subscription có một khoản thanh toán chưa hoàn thành, bạn nên hướng người dùng đến trang xác nhận thanh toán của Cashier, và truyền identifier của

php artisan migrate

94. Bạn có thể sử dụng phương thức

php artisan migrate

94 có sẵn trên instance subscription để lấy identifier này:

CASHIER_MODEL=App\User

3

Nếu bạn muốn một subscription vẫn được coi là hoạt động khi nó ở trạng thái

php artisan migrate

92, bạn có thể sử dụng phương thức

php artisan migrate

97 do Cashier cung cấp. Thông thường, phương thức này nên được gọi trong phương thức

php artisan migrate

18 trong

php artisan migrate

19 của bạn:

CASHIER_MODEL=App\User

4

{note} Khi một subscription ở trạng thái

php artisan migrate

89, bạn sẽ không thể thay đổi subscription cho đến khi xác nhận thanh toán. Do đó, các phương thức

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

01 và

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

02 sẽ đưa ra một ngoại lệ khi subscription ở trạng thái

php artisan migrate

89.

Thay đổi gói

Sau khi một người dùng đã subscription vào application của bạn, đôi khi họ có thể muốn thay đổi sang gói subscription mới. Để chuyển người dùng sang subscription mới, hãy truyền vào một price identifier của gói mới vào phương thức

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

01:

CASHIER_MODEL=App\User

5

Nếu người dùng đang trong thời gian dùng thử, thì thời gian dùng thử sẽ được duy trì. Ngoài ra, nếu có "nhiều" subscription tồn tại, thì những subscription đó cũng sẽ vẫn được duy trì.

Nếu bạn muốn thay đổi gói và hủy tất cả các gói dùng thử mà người dùng hiện đang sử dụng, bạn có thể sử dụng phương thức

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

05:

CASHIER_MODEL=App\User

6

Nếu bạn muốn thay đổi gói và lập hóa đơn ngay cho người dùng thay vì đợi đến chu kỳ thanh toán tiếp theo của họ, bạn có thể sử dụng phương pháp

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

06:

CASHIER_MODEL=App\User

7

Prorations

Mặc định, Stripe sẽ tính phí khi hoán đổi giữa các gói. Phương thức

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

07 có thể được sử dụng để cập nhật subscription mà không bị tính phí:

CASHIER_MODEL=App\User

8

Để biết thêm thông tin về tính phí subscription, hãy tham khảo tài liệu Stripe.

{note} Việc thực thi phương thức

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

07 trước phương thức

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

06 sẽ không ảnh hưởng gì đến tỷ lệ. Một hóa đơn sẽ luôn được phát hành.

Subscription số lượng lớn

Thỉnh thoảng subscription có thể bị ảnh hưởng bởi "số lượng". Ví dụ: application của bạn có thể tính phí $10 mỗi tháng cho mỗi người dùng trên mỗi tài khoản. Để dễ dàng tăng hoặc giảm số lượng subscription của bạn, hãy sử dụng các phương thức

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

10 hoặc

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

11:

CASHIER_MODEL=App\User

9

Ngoài ra, bạn cũng có thể set một số lượng cụ thể bằng phương thức

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

02:

STRIPE_KEY=your-stripe-key
STRIPE_SECRET=your-stripe-secret

0

Phương thức

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

07 có thể được sử dụng để cập nhật số lượng của subscription mà không cần chia tỷ lệ phí:

STRIPE_KEY=your-stripe-key
STRIPE_SECRET=your-stripe-secret

1

Để biết thêm thông tin về số lượng đăng ký, hãy tham khảo tài liệu của Stripe.

{note} Xin lưu ý rằng khi làm việc với một subscription nhiều plan, cần có thêm tham số "plan" cho các phương thức quantity ở trên.

Một subscription nhiều plan

Một subscription nhiều plan cho phép bạn chỉ định nhiều gói thanh toán cho một subscription. Ví dụ: hãy tưởng tượng bạn đang xây dựng một ứng dụng "helpdesk" của một customer service có subscription cơ bản là 10 đô la mỗi tháng, nhưng cung cấp thêm gói chat trực tiếp với mức phí bổ sung là 15 đô la mỗi tháng:

STRIPE_KEY=your-stripe-key
STRIPE_SECRET=your-stripe-secret

2

Bây giờ khách hàng sẽ có hai gói subscription

php artisan migrate

63. Cả hai gói này sẽ được tính phí vào các khoảng thời gian thanh toán tương ứng với chúng. Bạn cũng có thể sử dụng phương thức

php artisan migrate

68 để chỉ ra số lượng cụ thể cho từng gói:

STRIPE_KEY=your-stripe-key
STRIPE_SECRET=your-stripe-secret

3

Hoặc, bạn có thể điều chỉnh thêm gói bổ sung và số lượng của nó bằng phương thức

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

16:

STRIPE_KEY=your-stripe-key
STRIPE_SECRET=your-stripe-secret

4

Ngoài ra, bạn có thể thêm gói mới vào một gói subscription hiện có như sau:

STRIPE_KEY=your-stripe-key
STRIPE_SECRET=your-stripe-secret

5

Ví dụ trên sẽ thêm gói mới và khách hàng sẽ phải thanh toán cho gói đó vào chu kỳ thanh toán tiếp theo của họ. Nếu bạn muốn lập hóa đơn ngay cho khách hàng, bạn có thể sử dụng phương thức

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

17:

STRIPE_KEY=your-stripe-key
STRIPE_SECRET=your-stripe-secret

6

Nếu bạn muốn thêm một gói với một số lượng cụ thể, bạn có thể truyền số lượng đó làm tham số thứ hai của phương thức

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

18 hoặc

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

17:

STRIPE_KEY=your-stripe-key
STRIPE_SECRET=your-stripe-secret

7

Bạn có thể xóa các gói khỏi subscription bằng phương thức

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

20:

STRIPE_KEY=your-stripe-key
STRIPE_SECRET=your-stripe-secret

8

{note} Bạn không thể xóa gói cuối cùng tồn tại trên một subscription. Thay vào đó, bạn có thể hủy subscription đó.

Swapping

Bạn cũng có thể thay đổi các gói mà được gắn với một subscription nhiều plan. Ví dụ: hãy tưởng tượng bạn đang subscription gói

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

21 với thêm một tiện ích là

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

22 và bạn muốn nâng cấp lên gói

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

23:

STRIPE_KEY=your-stripe-key
STRIPE_SECRET=your-stripe-secret

9

Khi thực hiện đoạn code ở trên, subscription item với

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

21 sẽ bị xóa và subscription item mà có

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

22 sẽ vẫn được giữ nguyên. Ngoài ra, một subscription item mới cho

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

23 sẽ được tạo ra.

Bạn cũng có thể chỉ định thêm các tùy chọn cho subscription item. Ví dụ: bạn có thể cần chỉ định thêm số lượng gói subscription:

CASHIER_CURRENCY=eur

0

Nếu bạn muốn thay đổi một gói duy nhất trên một subscription, bạn có thể thực hiện việc này bằng cách sử dụng phương thức

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

01 trên chính subscription item đó. Phương thức này sẽ rất hữu ích nếu bạn, ví dụ, muốn giữ lại tất cả các dữ liệu hiện có, có trong subscription item.

CASHIER_CURRENCY=eur

1

Proration

Mặc định, Stripe sẽ tính phí theo tỷ lệ khi thêm hoặc xóa gói ra khỏi một subscription. Nếu bạn muốn thực hiện điều chỉnh một gói mà không cần theo tỷ lệ, bạn nên kết hợp thêm phương thức

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

07 vào code thay đổi gói của bạn:

CASHIER_CURRENCY=eur

2

Quantities

Nếu bạn muốn cập nhật số lượng gói trên các subscription riêng lẻ, bạn có thể thực hiện việc này bằng cách sử dụng và truyền thêm tên của gói đó làm tham số cho phương thức:

CASHIER_CURRENCY=eur

3

{note} Khi bạn set nhiều gói trên một subscription, thì các thuộc tính

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

29 và

php artisan migrate

68 trên model

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

31 sẽ là

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

32. Để truy cập vào một gói cụ thể, bạn nên sử dụng quan hệ

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

33 có sẵn trên model

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

31.

Subscription Items

Khi một subscription có nhiều gói, nó sẽ có nhiều subscription "items" được lưu trữ trong bảng

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

35 trong cơ sở dữ liệu của bạn. Bạn có thể truy cập vào những thứ này thông qua quan hệ

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

33 trên subscription:

CASHIER_CURRENCY=eur

4

Bạn cũng có thể lấy ra một gói cụ thể bằng phương thức

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

37:

CASHIER_CURRENCY=eur

5

Thuế của Subscription

Để khai báo thuế suất mà người dùng sẽ phải trả cho một subscription, hãy implement phương thức

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

38 trên model billable của bạn và trả về một mảng có ID thuế suất. Bạn có thể định nghĩa các thuế suất này trong bảng điều khiển Stripe của bạn:

CASHIER_CURRENCY=eur

6

Phương thức

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

38 cho phép bạn áp dụng thuế suất trên từng model, có thể hữu ích cho một người dùng trải dài trên nhiều quốc gia với nhiều loại thuế suất. Nếu bạn đang làm việc với một subscription nhiều gói, bạn có thể định nghĩa các mức thuế suất khác nhau cho từng gói bằng cách implement một phương thức

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

40 trên billable model của bạn:

CASHIER_CURRENCY=eur

7

{note} Phương thức

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

38 chỉ áp dụng cho các loại phí subscription. Nếu bạn sử dụng Cashier để thực hiện các khoản tính phí "một lần", bạn sẽ cần phải chỉ định một loại thuế suất cụ thể tại thời điểm đó.

Syncing Tax Rates

Khi thay đổi hard-code ID thuế suất được trả về từ phương thức

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

38, thì cài đặt thuế có trên bất kỳ subscription hiện có nào cho người dùng vẫn sẽ được giữ nguyên. Nếu bạn muốn cập nhật giá trị thuế cho các subscription hiện có với các giá trị

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

43 được trả về, bạn nên gọi phương thức

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

44 trên instance subscription của người dùng:

CASHIER_CURRENCY=eur

8

Điều này cũng sẽ đồng bộ tất cả các mức thuế của subscription item, vì vậy hãy đảm là rằng bạn cũng thay đổi đúng trong phương thức

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

40.

Tax Exemption

Cashier cũng đưa ra các phương thức để xác định xem khách hàng có được miễn thuế hay không bằng cách gọi API của Stripe. Các phương thức

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

46,

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

47, và

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

48 đã có sẵn trên billable model:

CASHIER_CURRENCY=eur

9

Các phương thức này cũng có sẵn trên tất cả các đối tượng

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

49. Tuy nhiên, khi gọi các phương thức này trên đối tượng

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

50, thì các phương thức đó sẽ xác định trạng thái miễn trừ tại thời điểm mà tạo hóa đơn.

Subscription cố định ngày

Mặc định, ngày cố định thanh toán là ngày đã tạo ra subscription hoặc nếu có thời gian dùng thử, thì ngày dùng thử kết thúc sẽ là ngày thanh toán. Nếu bạn muốn sửa ngày cố định thanh toán, bạn có thể sử dụng phương thức

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

51:

CASHIER_CURRENCY_LOCALE=nl_BE

0

Để biết thêm thông tin về cách quản lý chu kỳ thanh toán của subscription, hãy tham khảo tài liệu về chu kỳ thanh toán của Stripe

Huỷ Subscription

Để hủy một subscription, hãy gọi phương thức

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

52 trên subscription của người dùng:

CASHIER_CURRENCY_LOCALE=nl_BE

1

Khi một subscription bị hủy, Cashier sẽ tự động set cột

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

53 trong cơ sở dữ liệu của bạn. Cột này được sử dụng để biết xem khi nào phương thức

php artisan migrate

73 sẽ bắt đầu trả về

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

55. Ví dụ: nếu khách hàng hủy subscription vào ngày 1 tháng 3, nhưng subscription không thể kết thúc cho đến khi hết ngày 5 tháng 3, thì phương thức

php artisan migrate

73 vẫn sẽ tiếp tục trả về

php artisan migrate

74 cho đến ngày 5 tháng 3.

Bạn có thể biết những người dùng đã hủy subscription của họ nhưng vẫn đang trong "thời gian subscription có hiệu lực" bằng cách sử dụng phương thức

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

58:

use Laravel\Cashier\Billable;
class User extends Authenticatable
{
    use Billable;
}

8

Nếu bạn muốn hủy subscription ngay lập tức, hãy gọi phương thức

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

59 trên subscription của người dùng:

CASHIER_CURRENCY_LOCALE=nl_BE

3

Resume Subscription

Nếu một người dùng đã hủy subscription của họ và bạn muốn resume tiếp subscription đó, hãy sử dụng phương thức

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

60. Để resume một subscription, người dùng vẫn phải đang trong thời gian subscription có hiệu lực:

CASHIER_CURRENCY_LOCALE=nl_BE

4

Nếu người dùng đã hủy subscription nhưng sau đó lại muốn resume tiếp subscription đó trước khi subscription hết hạn, họ sẽ không bị tính tiền ngay lập tức. Thay vào đó, subscription của họ sẽ được kích hoạt lại và họ sẽ thanh toán theo đúng chu kỳ thanh toán ban đầu của họ.

Subscription dành cho dùng thử

Khai báo trước phương thức thanh toán

Nếu bạn muốn cung cấp thời gian dùng thử cho khách hàng của bạn trong khi vẫn muốn thu thập thông tin thanh toán của khách hàng, bạn nên sử dụng phương thức

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

61 khi tạo subscription của bạn:

CASHIER_CURRENCY_LOCALE=nl_BE

5

Phương thức này sẽ set ngày kết thúc của thời gian dùng thử vào trong bản ghi subscription trong cơ sở dữ liệu, và sẽ bảo với Stripee là sẽ không tính phí khách hàng cho đến khi hết ngày dùng thử. Khi sử dụng phương thức

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

61, Cashier sẽ ghi đè lên bất kỳ khoảng thời gian dùng thử nào được cấu hình cho gói trong Stripe.

{note} Nếu subscription của khách hàng không bị hủy trước ngày kết thúc dùng thử, họ sẽ bị tính phí ngay khi hết hạn dùng thử, vì vậy bạn nên chắc chắn là đã thông báo cho khách hàng biết về ngày kết thúc dùng thử của họ.

Phương thức

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

63 cho phép bạn cung cấp một instance

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

64 để chỉ định khi nào thời gian dùng thử kết thúc:

CASHIER_CURRENCY_LOCALE=nl_BE

6

Bạn có thể xác định xem người dùng hiện tại có đang trong thời gian dùng thử hay không bằng cách sử dụng phương thức

php artisan migrate

76 trên instance người dùng hoặc phương thức

php artisan migrate

76 trên instance subscription. Hai ví dụ dưới đây có kết quả giống hệt nhau:

CASHIER_CURRENCY_LOCALE=nl_BE

7

Defining Trial Days In Stripe / Cashier

Bạn có thể chọn định nghĩa số ngày dùng thử nhận được khi đăng ký gói của bạn trong bảng điều khiển Stripe hoặc luôn truyền chúng vào thông qua Cashier. Nếu bạn chọn định nghĩa ngày dùng thử cho gói của bạn trong Stripe, thì bạn nên biết rằng các subscription mới, bao gồm cả subscription mới cho những khách hàng đã có subscription trước đó, sẽ luôn nhận được thời gian dùng thử trừ khi bạn gọi phương thức

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

67.

Khai báo phương thức thanh toán sau

Nếu bạn muốn cung cấp thời gian dùng thử mà không muốn thu thập thông tin thanh toán của người dùng, bạn có thể set cột

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

68 trong bản ghi của người dùng thành ngày kết thúc dùng thử mà bạn mong muốn. Điều này thường được thực hiện trong quá trình đăng ký người dùng:

CASHIER_CURRENCY_LOCALE=nl_BE

8

{note} Hãy chắc chắn là bạn đã thêm cho cột

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

68 trong định nghĩa model của bạn.

Cashier sẽ coi các loại dùng thử như thế này là "dùng thử đại trà", vì nó sẽ không được gắn với bất kỳ thông tin subscription nào. Phương thức

php artisan migrate

76 trên instance

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

71 sẽ trả về

php artisan migrate

74 nếu ngày hiện tại không vượt quá giá trị của ngày

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

68:

CASHIER_CURRENCY_LOCALE=nl_BE

9

Bạn có thể sử dụng phương thức

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

74 nếu bạn muốn biết người dùng hiện tại có đang trong thời gian dùng thử "đại trà" và chưa tạo bất kỳ thông tin subscription nào hay không:

CASHIER_LOGGER=stack

0

Khi bạn đã sẵn sàng tạo một subscription thực sự cho người dùng, bạn có thể sử dụng phương thức

php artisan migrate

61 như bình thường:

CASHIER_LOGGER=stack

1

Mở rộng thời gian dùng thử

Phương thức

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

76 cho phép bạn kéo dài thời gian dùng thử của một subscription sau khi nó được tạo:

CASHIER_LOGGER=stack

2

Nếu bản dùng thử đã hết hạn và khách hàng đã được lập hóa đơn cho subscription, bạn vẫn có thể cung cấp cho họ thêm thời gian dùng thử. Thời gian sử dụng trong thời gian dùng thử sẽ được trừ vào hóa đơn tiếp theo của khách hàng.

Xử lý Stripe Webhooks

{tip} Bạn có thể sử dụng the Stripe CLI để giúp kiểm tra webhook trong quá trình phát triển local.

Stripe có thể thông báo cho ứng dụng của bạn về nhiều loại event khác nhau thông qua webhooks. Mặc định, sẽ có một route sẽ trỏ đến controller webhook của Cashier được cấu hình thông qua service provider của Cashier. Controller này sẽ xử lý tất cả các request webhook đến.

Mặc định, controller này sẽ tự động xử lý việc hủy subscription khi có quá nhiều lần tính phí không thành công (được định nghĩa trong cài đặt Stripe của bạn), cập nhật khách hàng, xóa khách hàng, cập nhật subscription và thay đổi phương thức thanh toán; tuy nhiên, bạn sẽ sớm khám phá ra là bạn có thể extend controller này để xử lý bất kỳ event webhook nào bạn thích.

Để đảm bảo ứng dụng của bạn có thể xử lý Stripe webhook, hãy nhớ cấu hình URL webhook trong bảng điều khiển Stripe. Mặc định, webhook controller của Cashier sẽ lắng nghe trên đường dẫn URL là

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

77. Danh sách đầy đủ của tất cả các webhook mà bạn nên cấu hình trong bảng điều khiển Stripe sẽ là:

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

  78

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

  79

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

  80

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

  81

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

  82

  {note} Hãy đảm bảo là bạn đã bảo vệ các request bằng các middleware của Cashier.

Webhooks & CSRF Protection

Vì các webhook của Stripe cần bỏ qua bước bảo vệ CSRF của Laravel, nên bạn hãy chắc chắn là đã khai báo URI của Stripe là một ngoại lệ trong middleware

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

83 của bạn hoặc bạn có thể khai báo route này ra khỏi group middleware

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

84:

CASHIER_LOGGER=stack

3

Định nghĩa xử lý event Webhook

Cashier sẽ tự động xử lý hủy subscription nếu như các lần trả phí không thành công, nhưng nếu bạn muốn thêm các event webhook mà bạn muốn tự xử lý, thì hãy extend controller Webhook. Tên phương thức của bạn phải tương ứng với quy ước của Cashier, cụ thể là, các phương thức sẽ cần được thêm tiền tố là

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

85 vào tên của webhook mà bạn muốn xử lý, theo kiểu "camel case". Ví dụ: nếu bạn muốn xử lý webhook

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

86, thì bạn cần thêm một phương thức

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

87 vào controller:

CASHIER_LOGGER=stack

4

Tiếp theo, định nghĩa một route đến Cashier controller của bạn trong file

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

88. Điều này sẽ ghi đè lên route mặc định của Cashier:

CASHIER_LOGGER=stack

5

Cashier sẽ phát ra một event

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

89 khi nhận được một webhook và một event

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

90 khi một webhook đã được xử lý bởi Cashier. Cả hai event đều chứa toàn bộ payload của webhook Stripe.

Subscription thất bại

Điều gì sẽ xảy ra nếu thẻ tín dụng của khách hàng hết hạn? Đừng lo lắng - Controller Webhook của Cashier sẽ hủy subscription của khách hàng cho bạn. Các khoản thanh toán không thành công sẽ được tự động kiểm soát và xử lý bởi controller. Controller này sẽ hủy subscription của khách hàng khi Stripe xác định rằng subscription không thành công (thông thường là sau ba lần thanh toán không thành công).

Kiểm tra Webhook Signatures

Để bảo mật webhook của bạn, bạn có thể sử dụng webhook signature của Stripe. Để thuận tiện, Cashier đã tự động thêm một middleware để kiểm tra các request webhook Stripe đến application là hợp lệ.

Để bật kiểm tra webhook, hãy đảm bảo rằng biến môi trường

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

91 được set trong file

php artisan migrate

24 của bạn. Webhook

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

93 có thể được lấy ra từ trang tổng quan trong tài khoản Stripe của bạn.

Phí

Tính phí một lần

{note} phương thức

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

94 chấp nhận số tiền mà bạn muốn tính phí theo loại tiền được set trong application của bạn.

Nếu bạn muốn thực hiện một khoản tính phí "một lần" đối với phương thức thanh toán của khách hàng đã subscription, bạn có thể sử dụng phương thức

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

94 trên một instance billable model. Bạn sẽ cần làm tham số thứ hai cho phương thức:

CASHIER_LOGGER=stack

6

Phương thức

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

94 chấp nhận một mảng làm tham số thứ ba của nó, cho phép bạn truyền vào bất kỳ tùy chọn nào mà bạn muốn cho việc tạo phí của Stripe. Tham khảo tài liệu của Stripe về các tùy chọn có sẵn cho bạn khi tạo phí:

CASHIER_LOGGER=stack

7

Bạn cũng có thể sử dụng phương thức

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

94 mà không cần có customer hoặc người dùng:

CASHIER_LOGGER=stack

8

Phương thức

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

94 sẽ đưa ra một ngoại lệ nếu việc tính phí không thành công. Nếu tính phí thành công, thì một instance của

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

99 sẽ được trả về từ phương thức:

CASHIER_LOGGER=stack

9

Tính phí với hoá đơn

Thỉnh thoảng bạn có thể cần phải tạo tính phí một lần nhưng cũng cần tạo cả một hóa đơn cho khoản phí đó để bạn có thể cung cấp hóa đơn PDF đó cho khách hàng của bạn. Phương thức

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

00 cho phép bạn làm điều đó. Ví dụ: hãy gửi hóa đơn "phí một lần" cho khách hàng của bạn là $5.00:

php artisan migrate

00

Hóa đơn sẽ được tính ngay lập tức cho phương thức thanh toán mặc định của người dùng. Phương thức

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

00 cũng chấp nhận một mảng làm tham số thứ ba của nó. Mảng này sẽ chứa các tùy chọn thanh toán cho các hàng được thanh toán. Tham số thứ tư được phương thức chấp nhận cũng là một mảng. Tham số cuối cùng này chấp nhận các tùy chọn thanh toán cho chính hóa đơn đó:

php artisan migrate

01

{note} Phương thức

use Laravel\Cashier\Cashier; Cashier::ignoreMigrations();

00 sẽ tạo ra một hóa đơn Stripe sẽ thử lại sau các lần thanh toán không thành công. Nếu bạn không muốn hóa đơn thử lại sau các lần trả phí không thành công, bạn sẽ cần phải close chúng bằng API Stripe sau lần tính phí không thành công đầu tiên.

Hoàn trả

Nếu bạn cần hoàn trả một phí đã được thanh toán trong Stripe, bạn có thể sử dụng phương thức

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

03. Phương thức này chấp nhận một ID của Payment Intent Stripe làm tham số đầu tiên của nó:

php artisan migrate

02

Hoá đơn

Lấy hoá đơn

Bạn có thể dễ dàng lấy ra một mảng các hóa đơn của một model billable bằng cách sử dụng phương thức

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

04:

php artisan migrate

03

Bạn có thể sử dụng phương thức

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

05 để lấy ra một hóa đơn cụ thể:

php artisan migrate

04

Displaying Invoice Information

Khi liệt kê hóa đơn cho khách hàng, bạn có thể sử dụng các phương thức helper của hóa đơn để hiển thị thông tin hóa đơn. Ví dụ: bạn có thể muốn liệt kê tất cả các hóa đơn có trong một bảng, cho phép người dùng dễ dàng tải xuống bất kỳ cái nào trong số chúng:

php artisan migrate

05

Tạo hoá đơn PDF

Từ trong một route hoặc một controller, sử dụng phương thức

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

06 để tạo một bản PDF cho hóa đơn để khách hàng có thể tải xuống. Phương thức này sẽ tự động tạo ra một response HTTP để gửi file download tới trình duyệt:

php artisan migrate

06

Phương thức

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

06 cũng cho phép một tùy chọn tên file làm tham số thứ ba. Tên file này sẽ tự động được gắn với đuôi là

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

08 cho bạn:

php artisan migrate

07

Xử lý lỗi thanh toán

Thỉnh thoảng, thanh toán cho các subscription hoặc các khoản phí một lần có thể thất bại. Khi điều này xảy ra, Cashier sẽ đưa ra một ngoại lệ là

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

09 để thông báo cho bạn biết rằng ngoại lệ đã xảy ra. Sau khi xử lý được ngoại lệ này, bạn có hai tùy chọn về cách tiếp tục.

Một là, bạn có thể chuyển hướng khách hàng của bạn đến trang xác nhận thanh toán chuyên dụng đi kèm với Cashier. Trang này đã có một route liên kết được đăng ký thông qua service provider của Cashier. Vì vậy, bạn có thể catch ngoại lệ

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

09 và chuyển hướng người dùng đến trang xác nhận thanh toán:

php artisan migrate

08

Trong trang xác nhận thanh toán, khách hàng sẽ được yêu cầu nhập lại các thông tin thẻ tín dụng của họ và thực hiện thêm bất kỳ hành động nào theo yêu cầu của Stripe, chẳng hạn như xác nhận "3D Secure". Sau khi xác nhận thanh toán của họ, người dùng sẽ được chuyển hướng đến URL được cung cấp bởi tham số

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

11 được chỉ định ở trên. Khi chuyển hướng, các biến query string như

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

12 (kiểu string) và

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

13 (kiểu integer) sẽ được thêm vào URL.

Ngoài ra, bạn cũng có thể cho phép Stripe xử lý xác nhận thanh toán cho bạn. Trong trường hợp này, thay vì chuyển hướng đến trang xác nhận thanh toán, bạn có thể thiết lập email thanh toán tự động của Stripe trong trang tổng quan Stripe của bạn. Tuy nhiên, nếu trường hợp ngoại lệ

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

09 xảy ra, bạn vẫn nên thông báo cho người dùng biết là họ sẽ nhận được một email kèm theo hướng dẫn xác nhận thanh toán.

Các ngoại lệ thanh toán có thể được áp dụng cho các phương thức sau:

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

94,

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

00, và

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

17 trên

php artisan migrate

22 user. Khi xử lý các subscription, phương thức

php artisan migrate

65 trên

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

20, và các phương thức

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

21 và

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

06 trên model

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

31 cũng có thể đưa ra các ngoại lệ.

Hiện có hai loại ngoại lệ thanh toán được extend từ

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

09. Bạn có thể catch những điều này một cách riêng biệt nếu bạn cần để có thể tùy chỉnh trải nghiệm cho người dùng:

• use Laravel\Cashier\Cashier; Cashier::ignoreMigrations();

  25: Exception này là Stripe yêu cầu xác minh thêm để xác nhận và xử lý thanh toán.

• use Laravel\Cashier\Cashier; Cashier::ignoreMigrations();

  26: Exception này là thanh toán không thành công vì nhiều lý do khác nhau, chẳng hạn như hết tiền chả hạn.

Strong Customer Authentication

Nếu doanh nghiệp của bạn có trụ sở tại Châu Âu, bạn sẽ cần tuân thủ các quy định về Strong Customer Authentication (SCA). Các quy định này đã được Liên minh Châu Âu áp dụng vào tháng 9 năm 2019 để ngăn chặn gian lận thanh toán. May mắn thay, Stripe và Cashier đã chuẩn bị sẵn sàng để xây dựng các ứng dụng tuân thủ SCA.

{note} Trước khi bắt đầu, hãy xem hướng dẫn của Stripe về PSD2 và SCA cũng như tài liệu về API SCA mới của họ.

Payments Requiring Additional Confirmation

Các quy định của SCA thường yêu cầu xác minh thêm để xác nhận và xử lý một khoản thanh toán. Khi điều này xảy ra, Cashier sẽ đưa ra một ngoại lệ

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

25 để thông báo cho bạn biết rằng cần phải xác minh thêm. Để tìm thấy thêm thông tin về cách xử lý cho các trường hợp ngoại lệ này bạn có thể .

Incomplete and Past Due State

Khi một khoản thanh toán yêu cầu xác nhận bổ sung, subscription sẽ vẫn ở trạng thái

php artisan migrate

89 hoặc

php artisan migrate

92, là giá trị cột

php artisan migrate

90. Cashier sẽ tự động kích hoạt subscription của khách hàng qua webhook ngay sau khi xác nhận thanh toán hoàn tất.

Để biết thêm thông tin về trạng thái

php artisan migrate

89 và

php artisan migrate

92, vui lòng tham khảo .

Thông báo thanh toán Off-Session

Vì các quy định của SCA yêu cầu khách hàng thỉnh thoảng cần xác minh chi tiết thanh toán của họ ngay cả khi subscription của họ đang hoạt động, nên Cashier có thể gửi thông báo thanh toán cho khách hàng khi yêu cầu xác nhận thanh toán off-session. Ví dụ: điều này có thể xảy ra khi subscription đang được gia hạn. Thông báo thanh toán của Cashier có thể được bật bằng cách set biến môi trường

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

33 thành một class thông báo. Mặc định, thông báo này sẽ bị tắt. Tất nhiên, Cashier có chứa một class thông báo mà bạn có thể sử dụng cho mục đích này, nhưng bạn có thể tự do thêm class thông báo của bạn nếu muốn:

php artisan migrate

09

Để đảm bảo rằng thông báo xác nhận thanh toán off-session sẽ được gửi, hãy chắc chắn rằng cho ứng dụng của bạn và webhook

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

82 được bật trong trang tổng quan Stripe của bạn. Ngoài ra, model

php artisan migrate

22 của bạn cũng nên sử dụng trait

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

36 của Laravel.

{note} Thông báo sẽ được gửi ngay cả khi khách hàng đang tự thực hiện thanh toán và nhận yêu cầu xác nhận bổ sung. Thật không may, không có cách nào để Stripe biết rằng một khoản thanh toán là được một khách hàng tự thực hiện hay là thông qua "off-session". Tuy nhiên, khách hàng sẽ chỉ nhận được thông báo "Thanh toán thành công" nếu họ truy cập vào trang thanh toán sau khi đã xác nhận thanh toán của mình. Khách hàng sẽ không được phép xác nhận cùng một khoản thanh toán tới hai lần và chịu khoản phí đến lần thứ hai.

Stripe SDK

Nhiều đối tượng của Cashier là các wrapper của các đối tượng Stripe SDK. Nếu bạn muốn tương tác trực tiếp với các đối tượng Stripe, bạn có thể lấy ra chúng bằng phương thức

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

37:

php artisan migrate

10

Bạn cũng có thể sử dụng phương thức

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

38 để cập nhật trực tiếp subscription Stripe:

php artisan migrate

11

Testing

Khi testing một ứng dụng sử dụng Cashier, bạn có thể cần mô phỏng các request HTTP thực tế đối với API của Stripe; tuy nhiên, điều này đòi hỏi bạn phải thực hiện lại một phần hành vi của chính Cashier. Do đó, chúng tôi khuyên bạn nên cho phép các bài test của bạn được chạm vào các API Stripe thực tế. Mặc dù điều này sẽ chậm hơn, nhưng nó sẽ cung cấp thêm niềm tin rằng ứng dụng của bạn đang hoạt động như mong đợi và bất kỳ bài test chậm nào cũng có thể được lưu vào trong một group testing PHPUnit của riêng nó.

Khi testing, hãy nhớ rằng bản thân Cashier đã có sẵn một bộ test case tuyệt vời, vì vậy bạn chỉ nên tập trung vào việc test các luồng subscription và thanh toán của ứng dụng của riêng bạn chứ không phải test mọi hành vi cơ bản của Cashier.

Để bắt đầu, hãy thêm phiên bản testing của Stripe secret vào file

use Laravel\Cashier\Cashier;
Cashier::ignoreMigrations();

39 của bạn:

php artisan migrate

12

Bây giờ, bất cứ khi nào bạn tương tác với Cashier trong khi testing, nó sẽ gửi các request API thực tế đến môi trường testing của Stripe của bạn. Để thuận tiện, bạn nên tạo ra trước các subscription và các gói cho tài khoản testing Stripe của bạn mà sau đó bạn có thể sử dụng các subscription đó hoặc các gói đó trong quá trình testing.

{tip} Để test nhiều tình huống thanh toán khác nhau, chẳng hạn như thẻ tín dụng bị từ chối và thất bại, bạn có thể sử dụng số thẻ và token dành cho test được cung cấp bởi Stripe.