支払いを複数回キャプチャーする

オーソリされた金額に達するまで、PaymentIntent を複数回キャプチャーします。

マルチキャプチャーを実行すると、1 回の取引に対し、CheckoutSession の確定ステップで作成された PaymentIntent を複数回キャプチャーできるようになります (PaymentIntent の総額に達するまで)。配送が数回に分かれる注文があり、注文のフルフィルメントを部分的に実行するたびにその売上をキャプチャーしたい場合は、このマルチキャプチャーが有効です。

IC+ の特長

マルチキャプチャーは、IC+ 料金体系のユーザーに提供される機能に含まれています。現在 Stripe の料金体系を組み合わせてご利用で、この機能へのアクセスをご希望の場合は、Stripe サポートにお問い合わせください。

サポート状況

マルチキャプチャーを行う際は、次の制限事項に注意してください。

オンラインカード決済のみサポートしています
アメリカン・エキスプレス、Visa、ディスカバー、Mastercard、Cartes Bancaires、ダイナースクラブ、銀聯カード (CUP)、JCB で利用可能です。
source_transaction を使用する支払いと送金別方式の売上フローには対応していない
Stripe では 1 つの PaymentIntent に対して最大 50 回キャプチャーできます
CheckoutSession で mode は payment に設定され、capture_method は manual に設定されます

CUP と JCB のサポート

CUP によるマルチキャプチャーは、アメリカでのみご利用いただけます。JCB によるマルチキャプチャーは、アメリカ、カナダ、オーストラリア、ニュージーランドでのみご利用いただけます。

ベストプラクティス

1 つの注文を複数回に分けて配送する場合は、各配送の詳細を最終顧客に事前通知するようにしてください。そうすることで、銀行取引明細書に複数の取引が表示されていることに混乱した顧客からの問い合わせやチャージバックを防止できます。顧客への通知については、以下のベストプラクティスを参考にしてください。

購入前の段階で、配送予定日と取引金額を顧客に通知する。
配送の都度、取引金額を通知する。
全額返金とキャンセルに関するポリシーを開示する。

新しい CheckoutSession を作成する際、custom_text フィールドを使用して決済ページに追加のテキストを表示することで、法令遵守要件を満たせます。

法令遵守

マルチキャプチャーを行うにあたり、お客様は適用されるすべての法律、規制、ネットワーク規則を遵守する責任を負うものとします。この機能を使用するカードネットワークの規則に照らし、取引の内容が適用されるすべての規則に準拠していることを確認してください。規則はネットワークごとに異なります。たとえば、ほとんどのカードネットワークでは、マルチキャプチャーの用途を個別配送される商品の販売に対するカード非提示取引に制限しています。一部のカードネットワークでは、業種 (旅行業など) によって企業のマルチキャプチャーを認めていますが、分割払いや入金のワークフローでマルチキャプチャーを行うことは認められない場合があります。

このページに記載されている情報のうち、これらの要件の遵守に関する情報は一般的なガイダンスであり、法律、税務、会計、その他の専門的なアドバイスではありません。自らの義務について不明な点がある場合は、専門家に相談することをお勧めします。

Checkout セッションを作成する

サーバーで Checkout セッションを作成し、ui_mode を embedded に設定します。Checkout セッションを設定する際、line items に加え、currency などのオプションを指定できます。

自社サイトでホストされているカスタムページに顧客を戻すには、そのページの URL を return_url パラメーターに指定します。URL にテンプレート変数 {CHECKOUT_SESSION_ID} を含めて、戻り先ページでセッションのステータスを取得します。Checkout では、リダイレクト前にこの変数が Checkout セッション ID に自動的に置き換えられます。

戻り先ページの設定と、リダイレクト動作をカスタマイズするためのオプションについてご紹介します。

Checkout セッションの作成後、レスポンスで返される client_secret を使用して、Checkout をマウントします。

マルチキャプチャー機能を有効にするには、request_multicapture を if_available に設定します。

決済手段

デフォルトでは、カードとその他の一般的な決済手段が有効になっています。Stripe ダッシュボードで個々の決済手段をオンまたはオフにできます。Checkout では、Stripe は通貨と制限事項を評価して、対応している決済手段を顧客に動的に提示します。

決済手段が顧客にどのように表示されるか確認するには、ダッシュボードで取引 ID を入力するか、または注文金額と通貨を設定します。

決済手段の設定では Apple Pay と Google Pay を有効にすることができます。デフォルトでは、Apple Pay は有効で、Google Pay は無効になっています。ただし、有効になっていても Stripe が除外する場合があります。配送先住所を収集せずに税金の自動計算を有効にした場合、Google Pay は除外されます。

Checkout の Stripe 上のオンラインページでは、Apple Pay や Google Pay を有効にするために実装内容を変更する必要はありません。Stripe は、これらの決済を他のカード決済と同じように処理します。

Checkout をマウントする

Checkout は Stripe.js の一部として利用できます。HTML ファイルのヘッダーに Stripe.js スクリプトを追加してページに含めます。次に、マウンティングに使用する空の DOM ノード (コンテナー) を作成します。

index.html
<head>
  <script src="https://js.stripe.com/basil/stripe.js"></script>
</head>
<body>
  <div id="checkout">
    <!-- Checkout will insert the payment form here -->
  </div>
</body>

公開可能な API キーで Stripe.js を初期化します。

Checkout セッションの作成、および client secret の取得をサーバーにリクエストする、非同期の fetchClientSecret 関数を作成します。 Checkout インスタンスを作成する際に、この関数を options に渡します。

index.js
// Initialize Stripe.js
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

initialize();

// Fetch Checkout Session and retrieve the client secret
async function initialize() {
  const fetchClientSecret = async () => {
    const response = await fetch("/create-checkout-session", {
      method: "POST",
    });
    const { clientSecret } = await response.json();
    return clientSecret;
  };

  // Initialize Checkout
  const checkout = await stripe.initEmbeddedCheckout({
    fetchClientSecret,
  });

  // Mount Checkout
  checkout.mount('#checkout');
}

Checkout は、HTTPS 接続を介して支払い情報をStripeに安全に送信する iframe でレンダリングされます。

よくある間違い

一部の支払い方法では、別のページにリダイレクトして支払いを確定する必要があるため、Checkout は別の iframe 内に配置しないでください。

デザインをカスタマイズする

アカウントのブランディング設定で、背景色、ボタンの色、枠線の角丸半径、フォントを設定して、サイトのデザインに合わせて Checkout をカスタマイズします。

デフォルトでは、Checkout は外側に余白やマージンが追加されずに表示されます。必要なマージンを適用するには (四方すべてに 16px など)、目的の余白を適用するコンテナー要素 (div など) を使用することをお勧めします。

戻り先ページを表示する

顧客が支払いを試行すると、Stripe はサイトがホストしている戻りページに顧客をリダイレクトします。Checkout セッションを作成したときに、return_url パラメーターで戻りページの URL は指定されています。リダイレクト動作をカスタマイズするためのオプションについては、こちらの記事をご覧ください。

戻り先ページを表示する際は、URL に含まれる Checkout セッション ID を使用して、Checkout セッションのステータスを取得します。セッションのステータスに応じて、結果を次のように処理します。

complete:支払いが成功しました。Checkout セッションの情報を成功ページに表示します。
open:支払いが失敗したか、またはキャンセルされました。顧客が再試行できるように Checkout を再マウントしてください。

client.js
const session = await fetch(`/session_status?session_id=${session_id}`)
if (session.status == 'open') {
  // Remount embedded Checkout
} else if (session.status == 'complete') {
  // Show success page
  // Optionally use session.payment_status or session.customer_email
  // to customize the success page
}

リダイレクトベースの決済手段

決済手段によっては、決済中に顧客が銀行のオーソリページなどの中間ページにリダイレクトされることがあります。顧客はそのページでアクションを完了すると、戻り先ページにリダイレクトされます。

リダイレクトベースの決済手段とリダイレクト動作についてご紹介します。

PaymentIntent をキャプチャーする

PaymentIntent が requires_capture 状態で、かつマルチキャプチャーが available の場合、オプションの final_capture パラメーターを false に設定すると、キャプチャー用の API を呼び出す際に未キャプチャーの残額をリリースしないよう Stripe に指示が送られます。たとえば、10 USD の PaymentInent を確定した場合に、7 USD を final_capture=false にしてキャプチャーすると、残りの 3 USD はオーソリ状態が維持されることになります。

PI キャプチャーのレスポンスに含まれる amount_capturable と amount_received フィールドは適宜更新されます。

// PaymentIntent Response
{
  "id": "pi_ANipwO3zNfjeWODtRPIg",
  "object": "payment_intent",
  "amount": 1000,
  "amount_capturable": 300, // 1000 - 700 = 300
  "amount_received": 700,
  // if latest_charge is expanded
  "latest_charge": {
      "id": "ch_xxx",
      "object": "charge",
      "amount": 1000,
      "amount_captured": 700,
      "amount_refunded": 0,
      ...
    }
  ...
}

最終キャプチャー

以下のいずれかが実行されるまで、PaymentIntent のステータスは requires_capture のままです。

final_capture を true に設定する。
final_capture パラメーターを使わずにキャプチャーする (final_capture はデフォルトで true に設定されているため)。
オーソリの有効期間が切れる。

この時点で Stripe は残りの売上をリリースし、PaymentIntent のステータスが succeeded に変わります。

PI キャプチャーのレスポンスに含まれる amount_capturable と amount_received フィールドは適宜更新されます。

// PaymentIntent Response
{
  "id": "pi_ANipwO3zNfjeWODtRPIg",
  "object": "payment_intent",
  "amount": 1000,
  "amount_capturable": 0, // not 100 due to final_capture=true
  "amount_received": 900, // 700 + 200 = 900
  // if latest_charge is expanded
  "latest_charge": {
      "id": "ch_xxx",
      "object": "charge",
      "amount": 1000,
      "amount_captured": 900,
      "amount_refunded": 0,
      ...
    }
  ...
}

未キャプチャーの PaymentIntent は canceled になりますが、一部キャプチャーされた PaymentIntent は succeeded になります。

オプションキャプチャーされていない売上をリリースする

構築したシステムをテストする

Stripe テストカードと任意のセキュリティコード、郵便番号、将来の日付の有効期限を使用して、マルチキャプチャーによる決済をテストします。

番号	決済手段	説明
	`pm_card_visa`	このテストカードは、マルチキャプチャーをサポートしています。
	`pm_card_visa_cartesBancaires`	マルチキャプチャーをサポートする Cartes Bancaires または Visa のテストカード。

返金

PaymentIntent のステータスが requires_capture の場合、キャプチャー合計額から返金合計額を引いた金額 (amount_received — amount_refunded に達するまで、何度でも返金できます。charge.refunded フィールドは、最後のキャプチャーが実行され、amount_received の全額が返金された場合にのみ true に移行します。

Stripe は、refund_application_fee=true または reverse_transfer=true を指定した一部返金に対応していません。代わりに、application fee refund (プラットフォーム手数料の返金) エンドポイントと transfer reversal (送金の差戻し) エンドポイントを使用して、手数料の一部返金と送金の差戻しを手動で実行できます。application fee refund エンドポイントまたは transfer reversal エンドポイントを使用すると、Stripe は refund_application_fee=true または reverse_transfer=true の返金に対応できなくなります。

Connect

Multicapture は、source_transaction パラメーターを伴う支払いと送金別方式を除き、Connect のすべてのユースケースに対応します。application_fee_amount と transfer_data[amount] パラメーターにはいくつかの追加検証があります。Multicapture を Connect に実装する際は以下の検証を考慮してください。

最初のキャプチャー時に application_fee_amount または transfer_data[amount] を設定した場合、後続のすべてのキャプチャーで同じ値が要求されます。キャプチャー時に渡される application_fee_amount または transfer_data[amount] は、PaymentIntent の作成、確定、更新時に渡される値を上書きします。
Stripe は、refund_application_fee=true または reverse_transfer=true を指定したマルチキャプチャーに対する一部返金に対応していません。application fee refund (プラットフォーム手数料の返金) エンドポイントと transfer reversal (送金の差戻し) エンドポイントを使用すると、手数料の一部返金や送金の差戻しを実行できます。

Webhook

支払いの更新 Webhook

Stripe は、支払いのキャプチャーが行われるたびに、charge.updated Webhook を送信します。

たとえば、application_fee_amount が指定されたデスティネーション支払いをマルチキャプチャーする場合、最初のキャプチャーが行われると、Stripe はこれらの空のフィールドに値を入力します。

// charge.updated
{
  "data": {
    "id": "ch_xxx",
    "object": "charge",
    "amount": 1000,
    "balance_transaction": "txn_xxx", // applicable to all charges
    "transfer": "tr_xxx",             // applicable to destination charges only
    "application_fee": "fee_xxx",     // applicable to Connect only
    ...
  },
  "previous_attributes": {
    "balance_transaction": null, // applicable to all charges
    "transfer": null,            // applicable to destination charges only
    "application_fee": null,     // applicable to Connect only
  }
}

payment_intent.amount_capturable_updated

Stripe は、amount_to_capture と final_capture の値に関係なく、キャプチャーのたびに payment_intent.amount_capturable_updated を送信します。

たとえば、10 USD の金額の PaymentIntent から 1 USD をキャプチャーすると、PaymentIntent の amount_capturable フィールドが 9 USD に更新されます。

// payment_intent.amount_capturable_updated
{
  "data": {
    "id": "pi_xxx",
    "object": "payment_intent",
    "amount": 1000,
    "amount_capturable": 900 // 1000 - 100 = 900
     ...
  },
  "previous_attributes": {
    "amount_capturable": 1000
  }
}

支払いのキャプチャーイベント

Stripe は最後のキャプチャー、またはオーソリ期間の終了時に、未キャプチャーの金額のオーソリを差戻すために charge.captured イベントを送信します。支払いの captured フィールドは、最後のキャプチャーまたはオーソリの差戻しが終わった時にのみ true になります。

たとえば、amount=0 と final_capture=true を指定してキャプチャーを行うと、支払いの captured 属性は false から true に変わります。

// charge.captured
{
  "data": {
    "id": "ch_xxx",
    "object": "charge",
    "captured": true
        ...
  },
  "previous_attributes": {
    "captured": false
  }
}

返金 Webhook

マルチキャプチャーの返金 Webhook は、マルチキャプチャー以外の返金 Webhook と同じです。

部分返金が行われるたびに、refund.created イベントが送信されます。連結アカウントの場合、これに加えてプラットフォーム手数料を返金する際には application_fee.refunded イベント、また送金を差戻す際には transfer.reversed イベントも送信されます。