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 を使用することもできます。

注

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

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

請求書が確定されると、PaymentIntent が生成され、請求書に関連付けられます。Stripe Elements を使用して、支払いの詳細を収集し、請求書の PaymentIntent を確定します。

注

請求書の確定後に金額や collection_method パラメーターを編集することはできません。この制限は、確定された請求書の PaymentIntent にも適用されます。update コールで請求書の) PaymentIntent) を更新する場合、変更できるのは setup_future_usage、metadata、payment_method、description、receipt_email、payment_method_data、payment_method_options、shipping の各パラメーターのみです。

Payment Element は、さまざまな決済手段で必要な支払い情報のすべてを安全に収集します。設定した決済手段が Invoicing と Payment Element の両方でサポートされているかどうかを確認するには、決済手段と製品サポートを参照してください。

フロントエンドに client secret を渡す

Stripe.js uses the PaymentIntent’s client_secret to securely complete the payment process. Get the invoice’s client secret by expanding its confirmation_secret attribute when finalizing the invoice or when making another API call, such as retrieve or update, on the invoice after you finalize it. Return the client_secret to the front end to complete payment.

After the invoice returns, access the client secret on the expanded confirmation_secret field.

Stripe Elements を設定する

Payment Element は Stripe.js の機能として自動的に使用できるようになります。決済ページに Stripe.js スクリプトを含めるには、HTML ファイルの head にスクリプトを追加します。常に js.stripe.com から Stripe.js を直接読み込むことにより、PCI 準拠が維持されます。スクリプトをバンドルに含めたり、そのコピーを自身でホストしたりしないでください。

pay-invoice.html
<head>
  <title>Pay Invoice</title>
  <script src="https://js.stripe.com/basil/stripe.js"></script>
</head>

購入ページで次の JavaScript を使用して、Stripe のインスタンスを作成します。

pay-invoice.js
// Set your publishable key: remember to change this to your live publishable key in production
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

Payment Element をページに追加する

決済ページには Payment Element を配置する場所が必要です。決済フォームで、一意の ID を持つ空の DOM ノード (コンテナー) を作成します。

pay-invoice.html
<form id="payment-form">
  <div id="payment-element">
    <!-- Elements will create form elements here -->
  </div>
  <button id="submit">Pay</button>
  <div id="error-message">
    <!-- Display error message to your customers here -->
  </div>
</form>

フォームが読み込まれたら、Payment Element のインスタンスを作成して、コンテナーの DOM ノードにマウントします。Elements のインスタンスを作成する際に、PaymentIntent の client secret をオプションとして渡します。

pay-invoice.js
const options = {
  clientSecret: '{{CLIENT_SECRET}}',
  // Fully customizable with appearance API.
  appearance: {/*...*/},
};

// Set up Stripe.js and Elements to use in your checkout form, passing in the client secret.
const elements = stripe.elements(options);

// Create and mount the Payment Element
const paymentElementOptions = { layout: 'accordion'};
const paymentElement = elements.create('payment', paymentElementOptions);
paymentElement.mount('#payment-element');

Payment Element によって動的なフォームが表示され、顧客はここで支払い方法を選択できます。このフォームでは、顧客が選択した支払い方法で必要な決済の詳細のすべてが自動的に収集されます。

Elements のインスタンスを作成する際に Appearance (デザイン) オブジェクトを options に渡すことで、サイトのデザインに合わせて Payment Element をカスタマイズできます。

支払いを完了する

stripe.confirmPayment を使用して、Payment Element からの詳細を指定した支払いを完了します。これにより支払い方法が作成され、請求書の支払いインテントが確定され、その結果支払いが実行されます。支払いに強力な顧客認証 (SCA) が必要とされる場合は、支払いインテントの確定前に Payment Element によって認証プロセスが処理されます。

支払いの完了後に Stripe がユーザーをリダイレクトする場所を指定するには、return_url を confirmPayment 関数に指定します。ユーザーは、まず発行会社のオーソリページなどの中間サイトにリダイレクトされてから、return_url にリダイレクトされることになります。カード支払いでは、支払いが正常に完了するとすぐに return_url にリダイレクトされます。

pay-invoice.js
const form = document.getElementById('payment-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const {error} = await stripe.confirmPayment({
    //`Elements` instance that was used to create the Payment Element
    elements,
    confirmParams: {
      return_url: "https://example.com/order/123/complete",
    }
  });

  if (error) {
    // This point will only be reached if there is an immediate error when
    // confirming the payment. Show error to your customer (for example, payment
    // details incomplete)
    const messageContainer = document.querySelector('#error-message');
    messageContainer.textContent = error.message;
  } else {
    // Your customer will be redirected to your `return_url`. For some payment
    // methods like iDEAL, your customer will be redirected to an intermediate
    // site first to authorize the payment, then redirected to the `return_url`.
  }
});

顧客が支払いを送信すると、Stripe は顧客を return_url にリダイレクトし、以下の URL クエリーパラメーターを含めます。返品ページでは、これらを使用して PaymentIntent のステータスを取得し、顧客に支払いステータスを表示できます。

return_url を指定する際に、返品ページで使用する独自のクエリパラメーターを追加することもできます。

パラメーター	説明
`payment_intent`	`PaymentIntent` の一意の識別子。
`payment_intent_client_secret`	The client secret of the `PaymentIntent` object. For subscription integrations, this client_secret is also exposed on the `Invoice` object through `confirmation_secret`

顧客が自社のサイトにリダイレクトされたら、payment_intent_client_secret を使用して PaymentIntent をクエリし、顧客に取引ステータスを表示できます。

注意

顧客のブラウザーセッションを追跡するツールを利用している場合、リファラー除外リストに stripe.com ドメインの追加が必要になる場合があります。リダイレクトを行うと、一部のツールでは新しいセッションが作成され、セッション全体の追跡ができなくなります。

payment_intent_client_secret クエリパラメーターを使用して、PaymentIntent を取得します。PaymentIntent のステータスを調べて、顧客に表示する内容を決定します。また、return_url を指定するときに自社のクエリパラメーターを追加することもできます。このパラメーターはリダイレクトプロセス全体を通じて存続します。

status.js
// Initialize Stripe.js using your publishable key
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

// Retrieve the "payment_intent_client_secret" query parameter appended to
// your return_url by Stripe.js
const clientSecret = new URLSearchParams(window.location.search).get(
  'payment_intent_client_secret'
);

// Retrieve the PaymentIntent
stripe.retrievePaymentIntent(clientSecret).then(({paymentIntent}) => {
  const message = document.querySelector('#message')

  // Inspect the PaymentIntent `status` to indicate the status of the payment
  // to your customer.
  //
  // Some payment methods will [immediately succeed or fail][0] upon
  // confirmation, while others will first enter a `processing` state.
  //
  // [0]: https://stripe.com/docs/payments/payment-methods#payment-notification
  switch (paymentIntent.status) {
    case 'succeeded':
      message.innerText = 'Success! Payment received.';
      break;

    case 'processing':
      message.innerText = "Payment processing. We'll update you when payment is received.";
      break;

    case 'requires_payment_method':
      message.innerText = 'Payment failed. Please try another payment method.';
      // Redirect your user back to your payment page to attempt collecting
      // payment again
      break;

    default:
      message.innerText = 'Something went wrong.';
      break;
  }
});

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

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

注