Invoicing API による組み込み
ダッシュボードは、インボイスを作成するための最も一般的な方法です。インボイス作成を自動化する場合は、API を組み込むことができます。 組み込みサンプルを使用して、完全に機能する Invoicing の組み込みを構築します。
注
Invoicing API を組み込むために、Payments API を組み込む必要はありません。
Stripe を設定する
Stripe API にアクセスするには、Stripe の公式ライブラリーを使用します。
商品を作成する
商品を作成するには、その名前を入力します。
価格を作成する
Price (価格) には、商品の価格と請求期間を定義します。これには、商品の価格、使用通貨、およびサブスクリプションの価格の場合は請求期間も含まれます。商品と同様に、価格の種類が少ない場合はダッシュボードで管理することをお勧めします。単価は、当該通貨の最小単位とします。この場合はセントになります (10 USD は 1,000 セントのため、単価は 1000)。
注
商品の価格を作成する必要がない場合は、インボイスアイテムの作成時に amount パラメーターを使用できます。
価格を作成してそれを商品に割り当てるには、商品 ID、単価、および通貨を指定します。次の例では、「Gold Special」商品の価格は 10 USD です。
顧客を作成する
Customer (顧客) オブジェクトはお客様の商品を購入する顧客を表すもので、請求書を作成する際に必須です。name
、email
、description
を指定して顧客を作成するには、次のコードを追加します。その際、使用する値に置き換えてください。
顧客を作成後、顧客の id
をデータベースに保存して、後で使用できるようにします。たとえば、次の手順では、顧客 ID を使用して請求書を作成します。
注
その他のパラメーターについては、顧客の作成をご覧ください。
インボイスを作成する
collection_method 属性を send_invoice
に設定します。Stripe が請求書を期限切れとしてマークできるようにするために、days_until_due パラメーターを追加する必要があります。請求書を送るときに、請求書および支払い手順がメールで顧客に送信されます。
次に、顧客 id
、商品 price
、請求書 ID invoice
を指定してインボイスアイテムを作成します。
インボイスアイテムの最大数は 250 です。
auto_advance
を false
に設定した場合、請求書は、確定する前であればいつでも修正できます。請求書の下書きを確定するには、ダッシュボードを使用するか、請求書を顧客に送信するか、または請求書に対する支払いを行います。また、以下のように確定 API を使用することもできます。
支払い後のイベントを処理する
Stripe は、請求書の支払いが完了すると、invoice.paid
イベントを送信します。このイベントをリッスンして、フルフィルメントが確実に行われるようにします。実装でクライアント側のコールバックのみを使用している場合は、コールバックの実行前に顧客の接続が失われ、そのためにサーバーに通知されることなく、顧客への請求が行われることがあります。非同期型のイベントをリッスンするように実装を設定すると、一度の導入で複数の異なるタイプの決済手段を受け付けることもできます。
注
請求書の支払いが成功すると、invoice.paid
と invoice.payment_succeeded
の両方のイベントがトリガーされます。どちらのイベントタイプにも同じ請求書データが含まれているため、請求書の支払いの成功の通知を受けるには、どちらかのイベントをリッスンするだけですみます。相違点は、invoice.payment_succeeded
イベントは、請求書の支払いが成功すると送信されますが、請求書に paid_out_of_band のマークを付けた場合には送信されません。一方、invoice.paid
イベントは、支払いの成功と外部での支払いの両方に対してトリガーされます。invoice.paid
が両方のシナリオに対応しているため、通常は、invoice.payment_succeeded
ではなく、invoice.paid
をリッスンすることをお勧めします。
これらのイベントを受信して、顧客への注文確認メールの送信、データベースでの売上の記録、配送ワークフローの開始などのアクションを実行するには、ダッシュボードの Webhook ツールを使用するか、Webhook クイックスタートに従ってください。
Payment Element を使用して支払いを回収する場合は、invoice.paid
イベントの他に 2 つのイベントを処理することをお勧めします。
イベント | 説明 | アクション |
---|---|---|
payment_intent.processing | 顧客が正常に支払いを開始したが、支払いがまだ完了していない場合に送信されます。このイベントは、多くの場合、銀行口座からの引き落としが開始されたときに送信されます。その後、invoice.paid イベントまたは invoice.payment_failed イベントが送信されます。 | 顧客に注文確認メールを送信し、支払いが保留中であることを示します。デジタル商品では、支払いの完了を待たずに注文のフルフィルメントを行うことが必要になる場合があります。 |
invoice.payment_failed | 顧客が請求書の支払いを試みたが、支払いに失敗した場合に送信されます。 | 支払いが processing から payment_failed に変わった場合は、顧客に再度支払いを試すように促します。 |