パッケージ - Cashier (Paddle) - 《Laravel 11.x ドキュメント》日本語

はじめに
Cashier のアップグレード
インストール
- Paddle サンドボックス
設定
クイックスタート
- 製品の販売
  - Paddle チェックアウトへのメタデータの提供
- サブスクリプションの販売
  - サブスクライブミドルウェアの構築
  - 顧客が請求プランを管理できるようにする
チェックアウトセッション
価格プレビュー
- 顧客価格プレビュー
- 割引
顧客
サブスクリプション
サブスクリプショントライアル
Paddle Webhookの処理
- WebhookとCSRF保護
- Webhookとローカル開発
Webhookイベントハンドラーの定義
Webhook署名の検証
単一の請求
取引
- 過去および今後の支払い
テスト

はじめに

このドキュメントは、Cashier Paddle 2.x の Paddle Billing との統合に関するものです。まだ Paddle Classic を使用している場合は、Cashier Paddle 1.x を使用する必要があります。

Laravel Cashier Paddle は、Paddleのサブスクリプション請求サービスに対する表現力豊かで流暢なインターフェースを提供します。これは、あなたが恐れているほとんどすべてのボイラープレートのサブスクリプション請求コードを処理します。基本的なサブスクリプション管理に加えて、Cashier は次のことを処理できます: サブスクリプションの交換、サブスクリプションの「数量」、サブスクリプションの一時停止、キャンセルの猶予期間など。

Cashier Paddle に深入りする前に、Paddle の概念ガイドと API ドキュメントも確認することをお勧めします。

Cashier のアップグレード

新しいバージョンの Cashier にアップグレードする際は、アップグレードガイドを注意深く確認することが重要です。

インストール

まず、Composer パッケージマネージャーを使用して Paddle 用の Cashier パッケージをインストールします:

composer require laravel/cashier-paddle

次に、vendor:publish Artisan コマンドを使用して Cashier のマイグレーションファイルを公開する必要があります:

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

次に、アプリケーションのデータベースマイグレーションを実行する必要があります。Cashier のマイグレーションは新しい customers テーブルを作成します。さらに、新しい subscriptions および subscription_items テーブルが作成され、すべての顧客のサブスクリプションが保存されます。最後に、すべての Paddle トランザクションを顧客に関連付けて保存するための新しい transactions テーブルが作成されます:

php artisan migrate

Cashier がすべての Paddle イベントを適切に処理できるようにするために、Cashier の Webhook 処理を設定することを忘れないでください。

Paddle サンドボックス

ローカルおよびステージング開発中は、Paddle サンドボックスアカウントを登録するべきです。このアカウントは、実際の支払いを行うことなくアプリケーションをテストおよび開発するためのサンドボックス環境を提供します。Paddle のテストカード番号を使用して、さまざまな支払いシナリオをシミュレートできます。

Paddle サンドボックス環境を使用する場合は、アプリケーションの PADDLE_SANDBOX 環境変数を true に設定する必要があります:

PADDLE_SANDBOX=true

アプリケーションの開発が完了したら、Paddle ベンダーアカウントに申し込むことができます。アプリケーションが本番環境に配置される前に、Paddle はアプリケーションのドメインを承認する必要があります。

設定

請求可能モデル

Cashier を使用する前に、ユーザーモデル定義に Billable トレイトを追加する必要があります。このトレイトは、サブスクリプションの作成や支払い方法情報の更新など、一般的な請求タスクを実行するためのさまざまなメソッドを提供します:

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

ユーザーでない請求可能エンティティがある場合は、それらのクラスにもトレイトを追加できます:

use Illuminate\Database\Eloquent\Model;
use Laravel\Paddle\Billable;
class Team extends Model
{
   use Billable;
}

API キー

次に、アプリケーションの .env ファイルで Paddle キーを設定する必要があります。Paddle コントロールパネルから Paddle API キーを取得できます:

PADDLE_CLIENT_SIDE_TOKEN=your-paddle-client-side-token
PADDLE_API_KEY=your-paddle-api-key
PADDLE_RETAIN_KEY=your-paddle-retain-key
PADDLE_WEBHOOK_SECRET="your-paddle-webhook-secret"
PADDLE_SANDBOX=true

PADDLE_SANDBOX 環境変数は、Paddle のサンドボックス環境を使用している場合は true に設定する必要があります。アプリケーションを本番環境にデプロイし、Paddle のライブベンダー環境を使用している場合は、PADDLE_SANDBOX 変数を false に設定する必要があります。

PADDLE_RETAIN_KEY はオプションであり、Retain と一緒に Paddle を使用している場合にのみ設定する必要があります。

Paddle JS

Paddle は、Paddle チェックアウトウィジェットを開始するために独自の JavaScript ライブラリに依存しています。アプリケーションレイアウトの閉じる </head> タグの直前に @paddleJS Blade ディレクティブを配置することで、JavaScript ライブラリを読み込むことができます:

<head>
   ...
   @paddleJS
</head>

通貨設定

請求書に表示する金額をフォーマットする際に使用するロケールを指定できます。内部的に、Cashier は PHP の NumberFormatter クラスを利用して通貨ロケールを設定します:

CASHIER_CURRENCY_LOCALE=nl_BE

en 以外のロケールを使用するには、サーバーに ext-intl PHP 拡張機能がインストールされ、設定されていることを確認してください。

デフォルトモデルのオーバーライド

Cashier によって内部で使用されるモデルを拡張するために、自分のモデルを定義し、対応する Cashier モデルを拡張することができます:

use Laravel\Paddle\Subscription as CashierSubscription;
class Subscription extends CashierSubscription
{
   // ...
}

モデルを定義した後、Laravel\Paddle\Cashier クラスを介して Cashier にカスタムモデルを使用するよう指示できます。通常、アプリケーションの App\Providers\AppServiceProvider クラスの boot メソッドで Cashier にカスタムモデルについて通知する必要があります:

use App\Models\Cashier\Subscription;
use App\Models\Cashier\Transaction;
/**
 * Bootstrap any application services.
 */
public function boot(): void
{
   Cashier::useSubscriptionModel(Subscription::class);
   Cashier::useTransactionModel(Transaction::class);
}

クイックスタート

製品の販売

Paddle チェックアウトを利用する前に、Paddle ダッシュボードで固定価格の製品を定義する必要があります。さらに、Paddle の Webhook 処理を設定するべきです。

アプリケーションを通じて製品およびサブスクリプション請求を提供することは、圧倒されることがあります。しかし、Cashier と Paddle のチェックアウトオーバーレイのおかげで、現代的で堅牢な支払い統合を簡単に構築できます。

非定期的な単一請求製品に対して顧客に請求するために、Cashier を利用して顧客に Paddle のチェックアウトオーバーレイを通じて請求します。顧客は支払い情報を提供し、購入を確認します。支払いがチェックアウトオーバーレイを通じて行われると、顧客はアプリケーション内の選択した成功 URL にリダイレクトされます:

use Illuminate\Http\Request;
Route::get('/buy', function (Request $request) {
   $checkout = $request->user()->checkout('pri_deluxe_album')
   ->returnTo(route('dashboard'));
   return view('buy', ['checkout' => $checkout]);
})->name('checkout');

上記の例に示すように、Cashier が提供する checkout メソッドを利用して、顧客に特定の「価格識別子」のための Paddle チェックアウトオーバーレイを提示するチェックアウトオブジェクトを作成します。Paddle を使用する際、「価格」は特定の製品のために定義された価格を指します。

必要に応じて、checkout メソッドは Paddle に顧客を自動的に作成し、その Paddle 顧客レコードをアプリケーションのデータベース内の対応するユーザーに接続します。チェックアウトセッションが完了すると、顧客は情報メッセージを表示できる専用の成功ページにリダイレクトされます。

buy ビューでは、チェックアウトオーバーレイを表示するボタンを含めます。paddle-button Blade コンポーネントは Cashier Paddle に含まれていますが、手動でオーバーレイチェックアウトをレンダリングすることもできます:

<x-paddle-button :checkout="$checkout" class="px-8 py-4">
   Buy Product
</x-paddle-button>

Paddle チェックアウトへのメタデータの提供

製品を販売する際、完了した注文や購入した製品を Cart および Order モデルを介して追跡することが一般的です。顧客を Paddle のチェックアウトオーバーレイにリダイレクトして購入を完了させる際、顧客がアプリケーションにリダイレクトされる際に、完了した購入を対応する注文に関連付けるために既存の注文識別子を提供する必要がある場合があります。

これを実現するために、checkout メソッドにカスタムデータの配列を提供できます。ユーザーがチェックアウトプロセスを開始すると、保留中の Order がアプリケーション内で作成されると想像してみてください。この例の Cart および Order モデルは説明用であり、Cashier によって提供されるものではありません。これらの概念は、アプリケーションのニーズに基づいて自由に実装できます:

use App\Models\Cart;
use App\Models\Order;
use Illuminate\Http\Request;
Route::get('/cart/{cart}/checkout', function (Request $request, Cart $cart) {
   $order = Order::create([
   'cart_id' => $cart->id,
   'price_ids' => $cart->price_ids,
   'status' => 'incomplete',
   ]);
   $checkout = $request->user()->checkout($order->price_ids)
   ->customData(['order_id' => $order->id]);
   return view('billing', ['checkout' => $checkout]);
})->name('checkout');

上記の例に示すように、ユーザーがチェックアウトプロセスを開始すると、カート/注文に関連するすべての Paddle 価格識別子を checkout メソッドに提供します。もちろん、アプリケーションは、顧客がアイテムを追加する際にこれらのアイテムを「ショッピングカート」または注文に関連付ける責任があります。customData メソッドを介して Paddle チェックアウトオーバーレイに注文の ID も提供します。

もちろん、顧客がチェックアウトプロセスを完了した後、注文を「完了」としてマークしたいと思うでしょう。これを実現するために、Paddle によって送信される Webhook をリッスンし、Cashier によって発生するイベントをリッスンして、データベースに注文情報を保存できます。

開始するには、Cashier によって送信される TransactionCompleted イベントをリッスンします。通常、アプリケーションの AppServiceProvider メソッドでイベントリスナーを登録する必要があります:

use App\Listeners\CompleteOrder;
use Illuminate\Support\Facades\Event;
use Laravel\Paddle\Events\TransactionCompleted;
/**
 * Bootstrap any application services.
 */
public function boot(): void
{
   Event::listen(TransactionCompleted::class, CompleteOrder::class);
}

この例では、CompleteOrder リスナーは次のようになります:

namespace App\Listeners;
use App\Models\Order;
use Laravel\Paddle\Cashier;
use Laravel\Paddle\Events\TransactionCompleted;
class CompleteOrder
{
   /**
     * Handle the incoming Cashier webhook event.
   */
   public function handle(TransactionCompleted $event): void
   {
   $orderId = $event->payload['data']['custom_data']['order_id'] ?? null;
   $order = Order::findOrFail($orderId);
   $order->update(['status' => 'completed']);
   }
}

transaction.completed イベントに含まれるデータに関する詳細は、Paddle のドキュメントを参照してください。

サブスクリプションの販売

Cashier と Paddle のチェックアウトオーバーレイを使用してサブスクリプションを販売する方法を学ぶために、基本的な月額 (price_basic_monthly) および年額 (price_basic_yearly) プランを持つサブスクリプションサービスのシンプルなシナリオを考えてみましょう。これらの 2 つの価格は、Paddle ダッシュボードの「基本」製品 (pro_basic) の下にグループ化できます。さらに、私たちのサブスクリプションサービスは、pro_expert としてエキスパートプランを提供するかもしれません。

まず、顧客が私たちのサービスにサブスクライブする方法を見てみましょう。もちろん、顧客はアプリケーションの価格ページで基本プランの「サブスクライブ」ボタンをクリックすることを想像できます。このボタンは、選択したプランのための Paddle チェックアウトオーバーレイを呼び出します。始めるには、checkout メソッドを介してチェックアウトセッションを開始します:

use Illuminate\Http\Request;
Route::get('/subscribe', function (Request $request) {
   $checkout = $request->user()->checkout('price_basic_monthly')
   ->returnTo(route('dashboard'));
   return view('subscribe', ['checkout' => $checkout]);
})->name('subscribe');

subscribe ビューでは、チェックアウトオーバーレイを表示するボタンを含めます。paddle-button Blade コンポーネントは Cashier Paddle に含まれていますが、手動でオーバーレイチェックアウトをレンダリングすることもできます:

<x-paddle-button :checkout="$checkout" class="px-8 py-4">
   Subscribe
</x-paddle-button>

今、サブスクライブボタンがクリックされると、顧客は支払い情報を入力し、サブスクリプションを開始できるようになります。サブスクリプションが実際に開始されたとき（いくつかの支払い方法は処理に数秒かかるため）、いつ開始されたかを知るために、Cashier の Webhook 処理を設定することも必要です。

顧客がサブスクリプションを開始できるようになったので、特定の部分を制限して、サブスクライブしたユーザーのみがアクセスできるようにする必要があります。もちろん、Cashier の Billable トレイトによって提供される subscribed メソッドを介して、ユーザーの現在のサブスクリプションステータスを常に確認できます:

@if ($user->subscribed())
   <p>You are subscribed.</p>
@endif

特定の製品または価格に対してユーザーがサブスクライブしているかどうかを簡単に判断することもできます:

@if ($user->subscribedToProduct('pro_basic'))
   <p>You are subscribed to our Basic product.</p>
@endif
@if ($user->subscribedToPrice('price_basic_monthly'))
   <p>You are subscribed to our monthly Basic plan.</p>
@endif

サブスクライブミドルウェアの構築

便利さのために、サブスクライブしたユーザーからの受信リクエストかどうかを判断するミドルウェアを作成したいかもしれません。このミドルウェアが定義されると、サブスクライブしていないユーザーがルートにアクセスできないように、簡単にルートに割り当てることができます:

<?php
namespace App\Http\Middleware;
use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;
class Subscribed
{
   /**
     * Handle an incoming request.
   */
   public function handle(Request $request, Closure $next): Response
   {
   if (! $request->user()?->subscribed()) {
   // Redirect user to billing page and ask them to subscribe...
   return redirect('/subscribe');
   }
   return $next($request);
   }
}

ミドルウェアが定義されたら、ルートに割り当てることができます:

use App\Http\Middleware\Subscribed;
Route::get('/dashboard', function () {
   // ...
})->middleware([Subscribed::class]);

顧客が請求プランを管理できるようにする

もちろん、顧客はサブスクリプションプランを別の製品や「ティア」に変更したいと思うかもしれません。上記の例では、顧客が月額サブスクリプションから年額サブスクリプションにプランを変更できるようにしたいと思います。これには、以下のルートに導くボタンを実装する必要があります:

use Illuminate\Http\Request;
Route::put('/subscription/{price}/swap', function (Request $request, $price) {
   $user->subscription()->swap($price); // With "$price" being "price_basic_yearly" for this example.
   return redirect()->route('dashboard');
})->name('subscription.swap');

プランを交換するだけでなく、顧客がサブスクリプションをキャンセルできるようにする必要があります。プランを交換するのと同様に、以下のルートに導くボタンを提供します:

use Illuminate\Http\Request;
Route::put('/subscription/cancel', function (Request $request, $price) {
   $user->subscription()->cancel();
   return redirect()->route('dashboard');
})->name('subscription.cancel');

これで、サブスクリプションは請求期間の終了時にキャンセルされます。

Cashier の Webhook 処理を設定している限り、Cashier は Paddle からの受信 Webhook を検査することによって、アプリケーションの Cashier 関連のデータベーステーブルを自動的に同期します。たとえば、Paddle のダッシュボードを介して顧客のサブスクリプションをキャンセルすると、Cashier は対応する Webhook を受信し、アプリケーションのデータベース内でサブスクリプションを「キャンセル済み」としてマークします。

チェックアウトセッション

顧客に請求するためのほとんどの操作は、Paddle のチェックアウトオーバーレイウィジェットを介して「チェックアウト」を使用するか、インラインチェックアウトを利用して実行されます。

Paddle を使用してチェックアウト支払いを処理する前に、Paddle チェックアウト設定ダッシュボードでアプリケーションのデフォルト支払いリンクを定義する必要があります。

オーバーレイチェックアウト

チェックアウトオーバーレイウィジェットを表示する前に、Cashier を使用してチェックアウトセッションを生成する必要があります。チェックアウトセッションは、請求操作を実行するためにチェックアウトウィジェットに通知します:

use Illuminate\Http\Request;
Route::get('/buy', function (Request $request) {
   $checkout = $user->checkout('pri_34567')
   ->returnTo(route('dashboard'));
   return view('billing', ['checkout' => $checkout]);
});

Cashier には paddle-button Blade コンポーネントが含まれています。このコンポーネントにチェックアウトセッションを「prop」として渡すことができます。次に、このボタンがクリックされると、Paddle のチェックアウトウィジェットが表示されます:

<x-paddle-button :checkout="$checkout" class="px-8 py-4">
   Subscribe
</x-paddle-button>

デフォルトでは、これにより Paddle のデフォルトスタイルを使用してウィジェットが表示されます。data-theme='light' 属性のような Paddle がサポートする属性をコンポーネントに追加することで、ウィジェットをカスタマイズできます:

<x-paddle-button :url="$payLink" class="px-8 py-4" data-theme="light">
   Subscribe
</x-paddle-button>

Paddle チェックアウトウィジェットは非同期です。ユーザーがウィジェット内でサブスクリプションを作成すると、Paddle はアプリケーションに Webhook を送信し、アプリケーションのデータベース内のサブスクリプション状態を適切に更新できるようにします。したがって、Paddle からの状態変更に対応するために、Webhook を適切に設定することが重要です。

サブスクリプションの状態が変更された後、対応する Webhook を受信するまでの遅延は通常最小限ですが、チェックアウトを完了した後にユーザーのサブスクリプションがすぐに利用可能でない可能性があることを考慮して、アプリケーションでこれを考慮する必要があります。

オーバーレイチェックアウトの手動レンダリング

Laravel の組み込み Blade コンポーネントを使用せずに、オーバーレイチェックアウトを手動でレンダリングすることもできます。始めるには、前の例で示したようにチェックアウトセッションを生成します:

use Illuminate\Http\Request;
Route::get('/buy', function (Request $request) {
   $checkout = $user->checkout('pri_34567')
   ->returnTo(route('dashboard'));
   return view('billing', ['checkout' => $checkout]);
});

次に、Paddle.js を使用してチェックアウトを初期化できます。この例では、paddle_button クラスが割り当てられたリンクを作成します。Paddle.js はこのクラスを検出し、リンクがクリックされるとオーバーレイチェックアウトを表示します:

<?php
$items = $checkout->getItems();
$customer = $checkout->getCustomer();
$custom = $checkout->getCustomData();
?>
<a
   href='#!'
   class='paddle_button'
   data-items='{!! json_encode($items) !!}'
   @if ($customer) data-customer-id='{{ $customer->paddle_id }}' @endif
   @if ($custom) data-custom-data='{{ json_encode($custom) }}' @endif
   @if ($returnUrl = $checkout->getReturnUrl()) data-success-url='{{ $returnUrl }}' @endif
>
   Buy Product
</a>

インラインチェックアウト

Paddle の「オーバーレイ」スタイルのチェックアウトウィジェットを使用したくない場合、Paddle はウィジェットをインラインで表示するオプションも提供します。このアプローチでは、チェックアウトの HTML フィールドを調整することはできませんが、ウィジェットをアプリケーション内に埋め込むことができます。

インラインチェックアウトを簡単に始めるために、Cashier には paddle-checkout Blade コンポーネントが含まれています。始めるには、チェックアウトセッションを生成する:

use Illuminate\Http\Request;
Route::get('/buy', function (Request $request) {
   $checkout = $user->checkout('pri_34567')
   ->returnTo(route('dashboard'));
   return view('billing', ['checkout' => $checkout]);
});

次に、チェックアウトセッションをコンポーネントの checkout 属性に渡すことができます:

<x-paddle-checkout :checkout="$checkout" class="w-full" />

インラインチェックアウトコンポーネントの高さを調整するには、height 属性を Blade コンポーネントに渡すことができます:

<x-paddle-checkout :checkout="$checkout" class="w-full" height="500" />

Paddle のインラインチェックアウトに関するガイドおよび利用可能なチェックアウト設定を参照して、インラインチェックアウトのカスタマイズオプションの詳細を確認してください。

インラインチェックアウトの手動レンダリング

Laravel の組み込み Blade コンポーネントを使用せずに、インラインチェックアウトを手動でレンダリングすることもできます。始めるには、前の例で示したようにチェックアウトセッションを生成します:

use Illuminate\Http\Request;
Route::get('/buy', function (Request $request) {
   $checkout = $user->checkout('pri_34567')
   ->returnTo(route('dashboard'));
   return view('billing', ['checkout' => $checkout]);
});

次に、Paddle.js を使用してチェックアウトを初期化できます。この例では、Alpine.js を使用してこれを示しますが、独自のフロントエンドスタックに合わせてこの例を変更することもできます:

<?php
$options = $checkout->options();
$options['settings']['frameTarget'] = 'paddle-checkout';
$options['settings']['frameInitialHeight'] = 366;
?>
<div class="paddle-checkout" x-data="{}" x-init="
   Paddle.Checkout.open(@json($options));
">
</div>

ゲストチェックアウト

時には、アカウントを必要としないユーザーのためにチェックアウトセッションを作成する必要があるかもしれません。そのためには、guest メソッドを使用できます:

use Illuminate\Http\Request;
use Laravel\Paddle\Checkout;
Route::get('/buy', function (Request $request) {
   $checkout = Checkout::guest('pri_34567')
   ->returnTo(route('home'));
   return view('billing', ['checkout' => $checkout]);
});

次に、チェックアウトセッションを Paddle ボタンまたはインラインチェックアウト Blade コンポーネントに提供できます。

価格プレビュー

Paddle は通貨ごとに価格をカスタマイズできるため、異なる国に対して異なる価格を設定できます。Cashier Paddle を使用すると、previewPrices メソッドを使用してこれらのすべての価格を取得できます。このメソッドは、価格を取得したい価格 ID を受け入れます:

use Laravel\Paddle\Cashier;
$prices = Cashier::previewPrices(['pri_123', 'pri_456']);

通貨はリクエストの IP アドレスに基づいて決定されますが、特定の国を提供して価格を取得することもできます:

use Laravel\Paddle\Cashier;
$prices = Cashier::previewPrices(['pri_123', 'pri_456'], ['address' => [
   'country_code' => 'BE',
   'postal_code' => '1234',
]]);

価格を取得した後、任意の方法で表示できます:

<ul>
   @foreach ($prices as $price)
   <li>{{ $price->product['name'] }} - {{ $price->total() }}</li>
   @endforeach
</ul>

小計価格と税額を別々に表示することもできます:

<ul>
   @foreach ($prices as $price)
   <li>{{ $price->product['name'] }} - {{ $price->subtotal() }} (+ {{ $price->tax() }} tax)</li>
   @endforeach
</ul>

詳細については、価格プレビューに関する Paddle の API ドキュメントを参照してください。

顧客価格プレビュー

ユーザーがすでに顧客であり、その顧客に適用される価格を表示したい場合は、顧客インスタンスから直接価格を取得することで実現できます:

use App\Models\User;
$prices = User::find(1)->previewPrices(['pri_123', 'pri_456']);

内部的に、Cashier はユーザーの顧客 ID を使用して、その通貨の価格を取得します。たとえば、アメリカに住むユーザーは米ドルで価格を表示し、ベルギーのユーザーはユーロで価格を表示します。一致する通貨が見つからない場合は、製品のデフォルト通貨が使用されます。製品またはサブスクリプションプランのすべての価格は、Paddle コントロールパネルでカスタマイズできます。

割引

割引後の価格を表示することもできます。previewPrices メソッドを呼び出すときに、discount_id オプションを介して割引 ID を提供します:

use Laravel\Paddle\Cashier;
$prices = Cashier::previewPrices(['pri_123', 'pri_456'], [
   'discount_id' => 'dsc_123'
]);

次に、計算された価格を表示します:

<ul>
   @foreach ($prices as $price)
   <li>{{ $price->product['name'] }} - {{ $price->total() }}</li>
   @endforeach
</ul>

顧客

顧客デフォルト

Cashier を使用すると、チェックアウトセッションを作成する際に顧客のために便利なデフォルトを定義できます。これらのデフォルトを設定すると、顧客のメールアドレスと名前を事前に入力できるため、すぐにチェックアウトウィジェットの支払い部分に進むことができます。これらのデフォルトは、請求可能モデルの次のメソッドをオーバーライドすることで設定できます:

/**
 * Get the customer's name to associate with Paddle.
 */
public function paddleName(): string|null
{
   return $this->name;
}
/**
 * Get the customer's email address to associate with Paddle.
 */
public function paddleEmail(): string|null
{
   return $this->email;
}

これらのデフォルトは、チェックアウトセッションを生成する Cashier のすべてのアクションで使用されます。

顧客の取得

Cashier::findBillable メソッドを使用して、Paddle 顧客 ID によって顧客を取得できます。このメソッドは、請求可能モデルのインスタンスを返します:

use Laravel\Paddle\Cashier;
$user = Cashier::findBillable($customerId);

顧客の作成

時には、サブスクリプションを開始せずに Paddle 顧客を作成したい場合があります。これを実現するには、createAsCustomer メソッドを使用します:

$customer = $user->createAsCustomer();

Laravel\Paddle\Customer のインスタンスが返されます。顧客が Paddle に作成された後、後でサブスクリプションを開始できます。Paddle API によってサポートされている追加の顧客作成パラメータを渡すために、オプションの $options 配列を提供できます:

$customer = $user->createAsCustomer($options);

サブスクリプション

サブスクリプションの作成

サブスクリプションを作成するには、まずデータベースから請求可能モデルのインスタンスを取得します。通常、これは App\Models\User のインスタンスです。モデルインスタンスを取得したら、subscribe メソッドを使用してモデルのチェックアウトセッションを作成できます:

use Illuminate\Http\Request;
Route::get('/user/subscribe', function (Request $request) {
   $checkout = $request->user()->subscribe($premium = 12345, 'default')
   ->returnTo(route('home'));
   return view('billing', ['checkout' => $checkout]);
});

subscribe メソッドに渡される最初の引数は、ユーザーがサブスクライブする特定の価格です。この値は、Paddle の価格識別子に対応する必要があります。returnTo メソッドは、ユーザーがチェックアウトを成功裏に完了した後にリダイレクトされる URL を受け入れます。subscribe メソッドに渡される 2 番目の引数は、サブスクリプションの内部「タイプ」です。アプリケーションが単一のサブスクリプションのみを提供する場合、default または primary と呼ぶことができます。このサブスクリプションタイプは、内部アプリケーション使用のためのものであり、ユーザーに表示されることを意図していません。さらに、スペースを含めず、サブスクリプションを作成した後に変更されるべきではありません。

customData メソッドを使用して、サブスクリプションに関するカスタムメタデータの配列を提供することもできます:

$checkout = $request->user()->subscribe($premium = 12345, 'default')
   ->customData(['key' => 'value'])
   ->returnTo(route('home'));

サブスクリプションチェックアウトセッションが作成されると、チェックアウトセッションは Cashier Paddle に含まれる paddle-button Blade コンポーネントに提供できます:

<x-paddle-button :checkout="$checkout" class="px-8 py-4">
   Subscribe
</x-paddle-button>

ユーザーがチェックアウトを完了すると、Paddle から subscription_created Webhook が送信されます。Cashier はこの Webhook を受信し、顧客のためにサブスクリプションを設定します。すべての Webhook がアプリケーションによって適切に受信および処理されることを確認するために、Webhook 処理を適切に設定してください。

サブスクリプションステータスの確認

ユーザーがアプリケーションにサブスクライブすると、さまざまな便利なメソッドを使用してそのサブスクリプションステータスを確認できます。まず、subscribed メソッドは、ユーザーが有効なサブスクリプションを持っている場合、true を返します。たとえそのサブスクリプションが現在トライアル期間内であっても:

if ($user->subscribed()) {
   // ...
}

アプリケーションが複数のサブスクリプションを提供している場合、subscribed メソッドを呼び出すときにサブスクリプションを指定できます:

if ($user->subscribed('default')) {
   // ...
}

subscribed メソッドは、ルートミドルウェアの優れた候補でもあり、ユーザーのサブスクリプションステータスに基づいてルートやコントローラーへのアクセスをフィルタリングできます:

<?php
namespace App\Http\Middleware;
use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;
class EnsureUserIsSubscribed
{
   /**
     * Handle an incoming request.
   *
     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
   */
   public function handle(Request $request, Closure $next): Response
   {
   if ($request->user() && ! $request->user()->subscribed()) {
   // This user is not a paying customer...
   return redirect('/billing');
   }
   return $next($request);
   }
}

ユーザーがまだトライアル期間内にいるかどうかを判断するには、onTrial メソッドを使用できます。このメソッドは、ユーザーにトライアル期間中であることを警告するメッセージを表示する必要があるかどうかを判断するのに役立ちます:

if ($user->subscription()->onTrial()) {
   // ...
}

subscribedToPrice メソッドは、ユーザーが特定のプランにサブスクライブしているかどうかを、特定の Paddle 価格 ID に基づいて判断するために使用できます。この例では、ユーザーの default サブスクリプションが月額価格にアクティブにサブスクライブされているかどうかを判断します:

if ($user->subscribedToPrice($monthly = 'pri_123', 'default')) {
   // ...
}

recurring メソッドは、ユーザーが現在アクティブなサブスクリプションを持っており、トライアル期間や猶予期間を過ぎているかどうかを判断するために使用できます:

if ($user->subscription()->recurring()) {
   // ...
}

キャンセルされたサブスクリプションステータス

ユーザーがかつてアクティブなサブスクライバーであったが、サブスクリプションをキャンセルしたかどうかを判断するには、canceled メソッドを使用できます:

if ($user->subscription()->canceled()) {
   // ...
}

ユーザーがサブスクリプションをキャンセルしたが、サブスクリプションが完全に期限切れになるまで「猶予期間」にあるかどうかを判断することもできます。たとえば、ユーザーが 3 月 5 日にサブスクリプションをキャンセルし、元々 3 月 10 日に期限切れになる予定だった場合、ユーザーは 3 月 10 日まで「猶予期間」にあります。さらに、subscribed メソッドは、この期間中も true を返します:

if ($user->subscription()->onGracePeriod()) {
   // ...
}

過去の支払い状況

サブスクリプションの支払いが失敗した場合、それは past_due としてマークされます。この状態のサブスクリプションは、顧客が支払い情報を更新するまでアクティブではありません。サブスクリプションが過去の支払い状況であるかどうかを判断するには、サブスクリプションインスタンスの pastDue メソッドを使用します:

if ($user->subscription()->pastDue()) {
   // ...
}

サブスクリプションが過去の支払い状況にある場合、ユーザーに支払い情報を更新するよう指示する必要があります。

サブスクリプションが past_due の場合でも有効と見なしたい場合は、Cashier によって提供される keepPastDueSubscriptionsActive メソッドを使用できます。通常、このメソッドは register メソッドの中で呼び出されるべきです:

use Laravel\Paddle\Cashier;
/**
 * Register any application services.
 */
public function register(): void
{
   Cashier::keepPastDueSubscriptionsActive();
}

サブスクリプションが past_due 状態にある場合、支払い情報が更新されるまで変更できません。したがって、swap および updateQuantity メソッドは、サブスクリプションが past_due 状態にあるときに例外をスローします。

サブスクリプションスコープ

ほとんどのサブスクリプション状態は、特定の状態にあるサブスクリプションをデータベースで簡単にクエリできるように、クエリスコープとしても利用可能です:

// Get all valid subscriptions...
$subscriptions = Subscription::query()->valid()->get();
// Get all of the canceled subscriptions for a user...
$subscriptions = $user->subscriptions()->canceled()->get();

利用可能なスコープの完全なリストは以下にあります:

Subscription::query()->valid();
Subscription::query()->onTrial();
Subscription::query()->expiredTrial();
Subscription::query()->notOnTrial();
Subscription::query()->active();
Subscription::query()->recurring();
Subscription::query()->pastDue();
Subscription::query()->paused();
Subscription::query()->notPaused();
Subscription::query()->onPausedGracePeriod();
Subscription::query()->notOnPausedGracePeriod();
Subscription::query()->canceled();
Subscription::query()->notCanceled();
Subscription::query()->onGracePeriod();
Subscription::query()->notOnGracePeriod();

サブスクリプション単一請求

サブスクリプション単一請求を使用すると、サブスクライバーにサブスクリプションの上に一度きりの請求を行うことができます。charge メソッドを呼び出すときに、1 つまたは複数の価格 ID を提供する必要があります:

// Charge a single price...
$response = $user->subscription()->charge('pri_123');
// Charge multiple prices at once...
$response = $user->subscription()->charge(['pri_123', 'pri_456']);

charge メソッドは、実際に顧客に請求するのはサブスクリプションの次の請求間隔までです。顧客に即座に請求したい場合は、chargeAndInvoice メソッドを代わりに使用できます:

$response = $user->subscription()->chargeAndInvoice('pri_123');

支払い情報の更新

Paddle は常にサブスクリプションごとに支払い方法を保存します。サブスクリプションのデフォルト支払い方法を更新したい場合は、サブスクリプションモデルの redirectToUpdatePaymentMethod メソッドを使用して、顧客を Paddle のホストされた支払い方法更新ページにリダイレクトする必要があります:

use Illuminate\Http\Request;
Route::get('/update-payment-method', function (Request $request) {
   $user = $request->user();
   return $user->subscription()->redirectToUpdatePaymentMethod();
});

ユーザーが情報の更新を完了すると、Paddle から subscription_updated Webhook が送信され、サブスクリプションの詳細がアプリケーションのデータベースに更新されます。

プランの変更

ユーザーがアプリケーションにサブスクライブした後、時折新しいサブスクリプションプランに変更したいと思うかもしれません。ユーザーのサブスクリプションプランを更新するには、Paddle 価格の識別子をサブスクリプションの swap メソッドに渡す必要があります:

use App\Models\User;
$user = User::find(1);
$user->subscription()->swap($premium = 'pri_456');

プランを交換し、次の請求サイクルを待つのではなく、ユーザーに即座に請求したい場合は、swapAndInvoice メソッドを使用できます:

$user = User::find(1);
$user->subscription()->swapAndInvoice($premium = 'pri_456');

按比例分配

デフォルトでは、Paddleはプラン間の切り替え時に料金を按分します。noProrateメソッドを使用すると、料金を按分せずにサブスクリプションを更新できます：

$user->subscription('default')->noProrate()->swap($premium = 'pri_456');

按分を無効にして顧客にすぐに請求したい場合は、swapAndInvoiceメソッドをnoProrateと組み合わせて使用できます：

$user->subscription('default')->noProrate()->swapAndInvoice($premium = 'pri_456');

また、サブスクリプションの変更に対して顧客に請求しない場合は、doNotBillメソッドを利用できます：

$user->subscription('default')->doNotBill()->swap($premium = 'pri_456');

Paddleの按分ポリシーに関する詳細は、Paddleの按分ドキュメントを参照してください。

サブスクリプションの数量

時には、サブスクリプションが「数量」に影響されることがあります。たとえば、プロジェクト管理アプリケーションは、プロジェクトごとに月額10ドルを請求するかもしれません。サブスクリプションの数量を簡単に増減させるには、incrementQuantityおよびdecrementQuantityメソッドを使用します：

$user = User::find(1);
$user->subscription()->incrementQuantity();
// Add five to the subscription's current quantity...
$user->subscription()->incrementQuantity(5);
$user->subscription()->decrementQuantity();
// Subtract five from the subscription's current quantity...
$user->subscription()->decrementQuantity(5);

または、updateQuantityメソッドを使用して特定の数量を設定することもできます：

$user->subscription()->updateQuantity(10);


``````php
$user->subscription()->noProrate()->updateQuantity(10);
`

複数製品を持つサブスクリプションの数量

サブスクリプションが複数製品を持つサブスクリプションの場合、増減させたい数量の価格のIDを増減メソッドの第2引数として渡す必要があります：

$user->subscription()->incrementQuantity(1, 'price_chat');

複数製品を持つサブスクリプション

複数製品を持つサブスクリプションでは、単一のサブスクリプションに複数の請求製品を割り当てることができます。たとえば、月額10ドルの基本サブスクリプションを持ち、追加で月額15ドルのライブチャットアドオン製品を提供するカスタマーサービス「ヘルプデスク」アプリケーションを構築していると想像してください。

サブスクリプションのチェックアウトセッションを作成する際、subscribeメソッドの第1引数として価格の配列を渡すことで、特定のサブスクリプションに複数の製品を指定できます：

use Illuminate\Http\Request;
Route::post('/user/subscribe', function (Request $request) {
   $checkout = $request->user()->subscribe([
   'price_monthly',
   'price_chat',
   ]);
   return view('billing', ['checkout' => $checkout]);
});

上記の例では、顧客はdefaultサブスクリプションに2つの価格が付随します。両方の価格はそれぞれの請求間隔で請求されます。必要に応じて、各価格の特定の数量を示すために、キー/値ペアの連想配列を渡すこともできます：

$user = User::find(1);
$checkout = $user->subscribe('default', ['price_monthly', 'price_chat' => 5]);

既存のサブスクリプションに別の価格を追加したい場合は、サブスクリプションのswapメソッドを使用する必要があります。swapメソッドを呼び出す際には、サブスクリプションの現在の価格と数量も含める必要があります：

$user = User::find(1);
$user->subscription()->swap(['price_chat', 'price_original' => 2]);

上記の例では新しい価格が追加されますが、顧客は次の請求サイクルまでその価格に対して請求されません。顧客にすぐに請求したい場合は、swapAndInvoiceメソッドを使用できます：

$user->subscription()->swapAndInvoice(['price_chat', 'price_original' => 2]);


``````php
$user->subscription()->swap(['price_original' => 2]);
`

サブスクリプションの最後の価格を削除することはできません。代わりに、サブスクリプションをキャンセルする必要があります。

複数のサブスクリプション

Paddleは、顧客が同時に複数のサブスクリプションを持つことを許可します。たとえば、プールのサブスクリプションとウエイトリフティングのサブスクリプションを提供するジムを運営している場合、各サブスクリプションには異なる価格が設定される可能性があります。もちろん、顧客はどちらか一方または両方のプランにサブスクライブできるべきです。

アプリケーションがサブスクリプションを作成する際、subscribeメソッドの第2引数としてサブスクリプションのタイプを提供できます。タイプは、ユーザーが開始しているサブスクリプションのタイプを表す任意の文字列である可能性があります：

use Illuminate\Http\Request;
Route::post('/swimming/subscribe', function (Request $request) {
   $checkout = $request->user()->subscribe($swimmingMonthly = 'pri_123', 'swimming');
   return view('billing', ['checkout' => $checkout]);
});

この例では、顧客のために月額のプールサブスクリプションを開始しました。しかし、後で年額サブスクリプションに切り替えたいかもしれません。顧客のサブスクリプションを調整する際、swimmingサブスクリプションの価格を単純に切り替えることができます：

$user->subscription('swimming')->swap($swimmingYearly = 'pri_456');

もちろん、サブスクリプションを完全にキャンセルすることもできます：

$user->subscription('swimming')->cancel();

サブスクリプションの一時停止

サブスクリプションを一時停止するには、ユーザーのサブスクリプションに対してpauseメソッドを呼び出します：

$user->subscription()->pause();

サブスクリプションが一時停止されると、Cashierは自動的にデータベース内のpaused_at列を設定します。この列は、pausedメソッドがtrueを返し始めるべき時期を決定するために使用されます。たとえば、顧客が3月1日にサブスクリプションを一時停止した場合、サブスクリプションは3月5日まで再開される予定ではなかった場合、pausedメソッドは3月5日までfalseを返し続けます。これは、ユーザーは通常、請求サイクルの終了までアプリケーションを使用し続けることが許可されているためです。

デフォルトでは、一時停止は次の請求間隔で発生するため、顧客は支払った期間の残りを使用できます。サブスクリプションをすぐに一時停止したい場合は、pauseNowメソッドを使用できます：

$user->subscription()->pauseNow();


``````php
$user->subscription()->pauseUntil(now()->addMonth());
`

または、pauseNowUntilメソッドを使用して、特定の時点までサブスクリプションを即座に一時停止できます：

$user->subscription()->pauseNowUntil(now()->addMonth());

ユーザーがサブスクリプションを一時停止しているが、まだ「猶予期間」にあるかどうかをonPausedGracePeriodメソッドを使用して確認できます：

if ($user->subscription()->onPausedGracePeriod()) {
   // ...
}

一時停止されたサブスクリプションを再開するには、サブスクリプションに対してresumeメソッドを呼び出します：

$user->subscription()->resume();

サブスクリプションが一時停止されている間は、変更することはできません。異なるプランに切り替えたり、数量を更新したりするには、まずサブスクリプションを再開する必要があります。

サブスクリプションのキャンセル

サブスクリプションをキャンセルするには、ユーザーのサブスクリプションに対してcancelメソッドを呼び出します：

$user->subscription()->cancel();

サブスクリプションがキャンセルされると、Cashierは自動的にデータベース内のends_at列を設定します。この列は、subscribedメソッドがfalseを返し始めるべき時期を決定するために使用されます。たとえば、顧客が3月1日にサブスクリプションをキャンセルした場合、サブスクリプションは3月5日まで終了する予定ではなかった場合、subscribedメソッドは3月5日までtrueを返し続けます。これは、ユーザーは通常、請求サイクルの終了までアプリケーションを使用し続けることが許可されているためです。

ユーザーがサブスクリプションをキャンセルしたが、まだ「猶予期間」にあるかどうかをonGracePeriodメソッドを使用して確認できます：

if ($user->subscription()->onGracePeriod()) {
   // ...
}

サブスクリプションをすぐにキャンセルしたい場合は、サブスクリプションに対してcancelNowメソッドを呼び出すことができます：

$user->subscription()->cancelNow();

キャンセルの猶予期間中にサブスクリプションを停止するには、stopCancelationメソッドを呼び出します：

$user->subscription()->stopCancelation();

Paddleのサブスクリプションは、キャンセル後に再開することはできません。顧客がサブスクリプションを再開したい場合は、新しいサブスクリプションを作成する必要があります。

サブスクリプショントライアル

前払いの支払い方法あり

顧客にトライアル期間を提供しながら、前払いで支払い方法情報を収集したい場合は、顧客がサブスクリプションしている価格のPaddleダッシュボードでトライアル時間を設定する必要があります。その後、通常通りチェックアウトセッションを開始します：

use Illuminate\Http\Request;
Route::get('/user/subscribe', function (Request $request) {
   $checkout = $request->user()->subscribe('pri_monthly')
   ->returnTo(route('home'));
   return view('billing', ['checkout' => $checkout]);
});

アプリケーションがsubscription_createdイベントを受信すると、Cashierはアプリケーションのデータベース内のサブスクリプションレコードにトライアル期間の終了日を設定し、この日以降に顧客の請求を開始しないようにPaddleに指示します。

顧客のサブスクリプションがトライアル終了日までにキャンセルされない場合、トライアルが終了するとすぐに請求されるため、ユーザーにトライアル終了日を通知することを確認してください。

ユーザーがトライアル期間内にいるかどうかを確認するには、ユーザーインスタンスのonTrialメソッドまたはサブスクリプションインスタンスのonTrialメソッドを使用できます。以下の2つの例は同等です：

if ($user->onTrial()) {
   // ...
}
if ($user->subscription()->onTrial()) {
   // ...
}

既存のトライアルが期限切れかどうかを確認するには、hasExpiredTrialメソッドを使用できます：

if ($user->hasExpiredTrial()) {
   // ...
}
if ($user->subscription()->hasExpiredTrial()) {
   // ...
}

特定のサブスクリプションタイプのトライアルにいるかどうかを確認するには、onTrialまたはhasExpiredTrialメソッドにタイプを提供できます：

if ($user->onTrial('default')) {
   // ...
}
if ($user->hasExpiredTrial('default')) {
   // ...
}

前払いの支払い方法なし

ユーザーの支払い方法情報を前払いで収集せずにトライアル期間を提供したい場合は、ユーザーに関連付けられた顧客レコードのtrial_ends_at列を希望するトライアル終了日に設定できます。これは通常、ユーザー登録中に行われます：

use App\Models\User;
$user = User::create([
   // ...
]);
$user->createAsCustomer([
   'trial_ends_at' => now()->addDays(10)
]);

Cashierはこのタイプのトライアルを「一般的なトライアル」と呼びます。これは、既存のサブスクリプションに関連付けられていないためです。onTrialメソッドは、Userインスタンスでtrueを返します。現在の日付がtrial_ends_atの値を過ぎていない場合：

if ($user->onTrial()) {
   // User is within their trial period...
}

ユーザーの実際のサブスクリプションを作成する準備ができたら、通常通りsubscribeメソッドを使用できます：

use Illuminate\Http\Request;
Route::get('/user/subscribe', function (Request $request) {
   $checkout = $user->subscribe('pri_monthly')
   ->returnTo(route('home'));
   return view('billing', ['checkout' => $checkout]);
});

ユーザーのトライアル終了日を取得するには、trialEndsAtメソッドを使用できます。このメソッドは、ユーザーがトライアル中であればCarbon日付インスタンスを返し、そうでなければnullを返します。特定のサブスクリプションのトライアル終了日を取得したい場合は、オプションのサブスクリプションタイプパラメータを渡すこともできます：

if ($user->onTrial('default')) {
   $trialEndsAt = $user->trialEndsAt();
}

ユーザーが「一般的な」トライアル期間内にあり、まだ実際のサブスクリプションを作成していないことを確認したい場合は、onGenericTrialメソッドを使用できます：

if ($user->onGenericTrial()) {
   // User is within their "generic" trial period...
}

トライアルの延長またはアクティブ化

既存のサブスクリプションのトライアル期間を延長するには、extendTrialメソッドを呼び出し、トライアルが終了すべき時点を指定します：

$user->subscription()->extendTrial(now()->addDays(5));

または、activateメソッドをサブスクリプションに対して呼び出すことで、トライアルを終了させてサブスクリプションを即座にアクティブ化できます：

$user->subscription()->activate();

Paddle Webhookの処理

Paddleは、さまざまなイベントをWebhookを介してアプリケーションに通知できます。デフォルトでは、CashierのWebhookコントローラーを指すルートがCashierサービスプロバイダーによって登録されます。このコントローラーは、すべての受信Webhookリクエストを処理します。

デフォルトでは、このコントローラーは、失敗した請求が多すぎるサブスクリプションのキャンセル、サブスクリプションの更新、および支払い方法の変更を自動的に処理します。ただし、すぐにわかるように、任意のPaddle Webhookイベントを処理するためにこのコントローラーを拡張できます。

Paddle Webhookを処理できるようにするには、PaddleコントロールパネルでWebhook URLを構成することを確認してください。デフォルトでは、CashierのWebhookコントローラーは/paddle/webhook URLパスに応答します。Paddleコントロールパネルで有効にする必要があるすべてのWebhookの完全なリストは次のとおりです：

顧客の更新
取引の完了
取引の更新
サブスクリプションの作成
サブスクリプションの更新
サブスクリプションの一時停止
サブスクリプションのキャンセル

受信リクエストをCashierのWebhook署名検証ミドルウェアで保護することを確認してください。

WebhookとCSRF保護

Paddle WebhookはLaravelのCSRF保護をバイパスする必要があるため、Laravelが受信Paddle WebhookのCSRFトークンを検証しようとしないようにする必要があります。これを実現するには、アプリケーションのbootstrap/app.phpファイルでpaddle/*をCSRF保護から除外する必要があります：

->withMiddleware(function (Middleware $middleware) {
   $middleware->validateCsrfTokens(except: [
   'paddle/*',
   ]);
})

Webhookとローカル開発

Paddleがローカル開発中にアプリケーションにWebhookを送信できるようにするには、NgrokやExposeなどのサイト共有サービスを介してアプリケーションを公開する必要があります。Laravel Sailを使用してローカルでアプリケーションを開発している場合は、Sailのサイト共有コマンドを使用できます。

Webhookイベントハンドラーの定義

Cashierは、失敗した請求によるサブスクリプションのキャンセルやその他の一般的なPaddle Webhookを自動的に処理します。ただし、処理したい追加のWebhookイベントがある場合は、Cashierによって発行される次のイベントをリッスンすることでそれを行うことができます：

Laravel\Paddle\Events\WebhookReceived
Laravel\Paddle\Events\WebhookHandled

両方のイベントには、Paddle Webhookの完全なペイロードが含まれています。たとえば、transaction.billed Webhookを処理したい場合は、リスナーを登録してイベントを処理できます：

<?php
namespace App\Listeners;
use Laravel\Paddle\Events\WebhookReceived;
class PaddleEventListener
{
   /**
     * Handle received Paddle webhooks.
   */
   public function handle(WebhookReceived $event): void
   {
   if ($event->payload['event_type'] === 'transaction.billed') {
   // Handle the incoming event...
   }
   }
}

Cashierは、受信したWebhookのタイプに特化したイベントも発行します。Paddleからの完全なペイロードに加えて、請求モデル、サブスクリプション、または領収書など、Webhookを処理するために使用された関連モデルも含まれています：

Laravel\Paddle\Events\CustomerUpdated
Laravel\Paddle\Events\TransactionCompleted
Laravel\Paddle\Events\TransactionUpdated
Laravel\Paddle\Events\SubscriptionCreated
Laravel\Paddle\Events\SubscriptionUpdated
Laravel\Paddle\Events\SubscriptionPaused
Laravel\Paddle\Events\SubscriptionCanceled

アプリケーションの.envファイルでCASHIER_WEBHOOK環境変数を定義することで、デフォルトの組み込みWebhookルートをオーバーライドすることもできます。この値は、Webhookルートへの完全なURLであり、Paddleコントロールパネルに設定されたURLと一致する必要があります：

CASHIER_WEBHOOK=https://example.com/my-paddle-webhook-url

Webhook署名の検証

Webhookを保護するために、PaddleのWebhook署名を使用できます。便利なことに、Cashierは受信したPaddle Webhookリクエストが有効であることを検証するミドルウェアを自動的に含めています。

Webhook検証を有効にするには、アプリケーションの.envファイルにPADDLE_WEBHOOK_SECRET環境変数が定義されていることを確認してください。Webhookシークレットは、Paddleアカウントダッシュボードから取得できます。

単一の請求

製品の請求

顧客のために製品購入を開始したい場合は、請求モデルインスタンスのcheckoutメソッドを使用して購入のチェックアウトセッションを生成できます。checkoutメソッドは、1つまたは複数の価格IDを受け入れます。必要に応じて、購入している製品の数量を提供するために連想配列を使用できます：

use Illuminate\Http\Request;
Route::get('/buy', function (Request $request) {
   $checkout = $request->user()->checkout(['pri_tshirt', 'pri_socks' => 5]);
   return view('buy', ['checkout' => $checkout]);
});

チェックアウトセッションを生成した後、Cashierが提供するpaddle-button Bladeコンポーネントを使用して、ユーザーがPaddleチェックアウトウィジェットを表示し、購入を完了できるようにします：

<x-paddle-button :checkout="$checkout" class="px-8 py-4">
   Buy
</x-paddle-button>

チェックアウトセッションにはcustomDataメソッドがあり、基盤となるトランザクション作成に渡したい任意のカスタムデータを渡すことができます。カスタムデータを渡す際に利用可能なオプションについては、Paddleのドキュメントを参照してください：

$checkout = $user->checkout('pri_tshirt')
   ->customData([
   'custom_option' => $value,
   ]);

取引の返金

取引の返金は、購入時に使用された顧客の支払い方法に返金額を戻します。Paddleの購入を返金する必要がある場合は、refundメソッドをCashier\Paddle\Transactionモデルに対して使用できます。このメソッドは、理由を最初の引数として受け入れ、返金する価格IDを1つ以上、オプションの金額を連想配列として受け入れます。transactionsメソッドを使用して、特定の請求モデルの取引を取得できます。

たとえば、価格pri_123とpri_456の特定の取引を返金したいと想像してください。pri_123を完全に返金したいが、pri_456については2ドルだけ返金したいとします：

use App\Models\User;
$user = User::find(1);
$transaction = $user->transactions()->first();
$response = $transaction->refund('Accidental charge', [
   'pri_123', // Fully refund this price...
   'pri_456' => 200, // Only partially refund this price...
]);

上記の例は、取引の特定の行項目を返金します。取引全体を返金したい場合は、理由を提供するだけです：

$response = $transaction->refund('Accidental charge');

返金に関する詳細は、Paddleの返金ドキュメントを参照してください。

返金は常にPaddleによって完全に処理される前に承認される必要があります。

取引のクレジット

返金と同様に、取引にクレジットを付与することもできます。取引にクレジットを付与すると、顧客の残高に資金が追加され、将来の購入に使用できるようになります。クレジット取引は、手動で収集された取引に対してのみ行うことができ、自動的に収集された取引（サブスクリプションなど）には行えません。Paddleはサブスクリプションのクレジットを自動的に処理します：

$transaction = $user->transactions()->first();
// Credit a specific line item fully...
$response = $transaction->credit('Compensation', 'pri_123');

詳細については、Paddleのクレジットに関するドキュメントを参照してください。

クレジットは手動で収集された取引にのみ適用できます。自動的に収集された取引は、Paddle自身によってクレジットされます。

取引

請求モデルの取引の配列をtransactionsプロパティを介して簡単に取得できます：

use App\Models\User;
$user = User::find(1);
$transactions = $user->transactions;

取引は、製品や購入の支払いを表し、請求書が付随します。完了した取引のみがアプリケーションのデータベースに保存されます。

顧客の取引をリストする際、取引インスタンスのメソッドを使用して関連する支払い情報を表示できます。たとえば、ユーザーが請求書を簡単にダウンロードできるように、すべての取引をテーブルにリストしたい場合があります：

<table>
   @foreach ($transactions as $transaction)
   <tr>
   <td>{{ $transaction->billed_at->toFormattedDateString() }}</td>
   <td>{{ $transaction->total() }}</td>
   <td>{{ $transaction->tax() }}</td>
   <td><a href="{{ route('download-invoice', $transaction->id) }}" target="_blank">Download</a></td>
   </tr>
   @endforeach
</table>


``````php
use Illuminate\Http\Request;
use Laravel\Paddle\Transaction;
Route::get('/download-invoice/{transaction}', function (Request $request, Transaction $transaction) {
   return $transaction->redirectToInvoicePdf();
})->name('download-invoice');
`

過去および今後の支払い


``````php
use App\Models\User;
$user = User::find(1);
$subscription = $user->subscription();
$lastPayment = $subscription->lastPayment();
$nextPayment = $subscription->nextPayment();
`

これらのメソッドはLaravel\Paddle\Paymentのインスタンスを返します。ただし、lastPaymentは、トランザクションがまだWebhookによって同期されていない場合にnullを返し、nextPaymentは請求サイクルが終了した場合（サブスクリプションがキャンセルされた場合など）にnullを返します：

Next payment: {{ $nextPayment->amount() }} due on {{ $nextPayment->date()->format('d/m/Y') }}

テスト

テスト中は、統合が期待通りに機能することを確認するために、手動で請求フローをテストする必要があります。

CI環境内で実行される自動テストを含め、LaravelのHTTPクライアントを使用してPaddleへのHTTP呼び出しをフェイクすることができます。これはPaddleからの実際の応答をテストするものではありませんが、PaddleのAPIを実際に呼び出すことなくアプリケーションをテストする方法を提供します。