Invoicing API を組み込む

コードを使用して請求書を作成し、送信する方法をご紹介します。

ダッシュボードは、請求書を作成するための最も一般的な方法です。請求書作成を自動化する場合は、API を組み込むことができます。実装のサンプルを使用して、完全に機能する Invoicing の実装を構築します。

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

オプション請求書をカスタマイズする

請求書をカスタマイズする方法はいくつかあります。Stripe のカスタマイズオプションを使用すると、独自のブランディングを追加したり、お客様が操業する管轄区域の規制に準拠するように変更できます。

カスタムフィールド

カスタムフィールドを追加すると、請求書の PDF ドキュメントが具体化され、ビジネス慣行や税務報告義務をより遵守しやすくなります。カスタムフィールドには、請求書のヘッダーに表示するキーと値のペアを最大 4 つまで指定できます。請求書エディター、Invoices API、または請求書テンプレートで、最大 4 つまでカスタムフィールドのキーと値のペアを設定できます。

以下は、一般的なカスタムフィールドの使用方法です。

注文 (PO) 番号
請負業者番号
税金コンプライアンス

PO 番号と付加価値税 (VAT) をカスタムフィールドとして使用して請求書を作成する例を次に示します。

カスタムフィールドの継承

Customer (顧客) オブジェクトでインボイスのカスタムフィールドを設定できます。顧客レベルで設定したカスタムフィールドは、その顧客のために生成するすべての請求書の下書きに適用されます。インボイスが下書きの間は、これらの継承されたカスタムフィールドをいつでも変更できます。請求書の確定後は、カスタムフィールドを更新できません。

顧客レベルでカスタムフィールドを追加して、今後作成されるすべての請求書の下書きに適用する場合の例を以下に示します。