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 に設定した場合、インボイスは、確定する前であればいつでも修正できます。インボイスの下書きを確定するには、ダッシュボードを使用するか、インボイスを顧客に送信するか、またはインボイスに対する支払いを行います。また、以下のようにFinalize (確定) API を使用することもできます。

注

インボイスを誤って作成した場合、無効にすることができます。また、インボイスを回収不能とマークすることもできます。

請求書支払いを受け付ける

顧客に関連付けられているメールアドレスに請求書を送信します。請求書が送信されるとすぐに、Stripe は請求書を確定します。多くの管轄区域では、確定済みの請求書は法的文書と見なされ、一部のフィールドは変更不可能になります。支払い済みの請求書を送信する場合、メールに支払いの参照情報は記載されません。

注

支払い済みの請求書を送信した場合は、メールに支払いの参照情報は含まれません。Stripe は、顧客に関連付けられたメールアドレスに請求書を送信します。

支払い後のイベントを処理する

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` に変わった場合は、顧客に再度支払いを試すように促します。

注