デスティネーション支払いを作成する

プラットフォームアカウントで支払いを作成し、手数料を回収し、残りの売上を連結アカウントに即時に送金します。

連結アカウントが提供する商品またはサービスについて、顧客がプラットフォームと取引するときに「デスティネーション支払い」を作成し、連結アカウントに売上を即時に送金します。この支払いタイプの特徴は以下のとおりです。

プラットフォームのアカウントで支払いを作成します。
売上の一部または全額を、連結アカウントに送金するかどうかを決定します。
Stripe の手数料、返金、チャージバックは、お客様のアカウント残高から引き落とされます。

この支払いタイプは、住宅賃貸マーケットプレイスの Airbnb や、ライドシェアアプリの Lyft などのマーケットプレイスに最適です。

デスティネーション支払いは、プラットフォームと連結アカウントの両方が同じ国に所在する場合にのみサポートされます。国境を超える場合に対応するには、Payment Intent で on_behalf_ofパラメーターを使用して連結アカウントに売上処理加盟店を指定する必要があります。あるいは、その他の有効な海外送金のシナリオをご確認ください。

注

Express ダッシュボードにアクセスできる連結アカウント、またはダッシュボードにアクセスできない連結アカウントには、デスティネーション支払いを使用することをお勧めします。

ウェブ

iOS

Android

React Native

Stripe Elements を使用して、サイトに UI コンポーネントを埋め込むことでカスタムの決済システムを構築します。クライアント側とサーバー側のコードでさまざまな支払い方法を受け付ける決済フォームを構築します。この実装と、Stripe のその他の実装タイプとの比較をご覧ください。

リピートユーザーに対する Link のしくみを見るには、メールアドレス demo@stripe.com を入力してください。新規登録中の Link のしくみを見るには、他の任意のメールアドレスを入力し、フォームの残りの部分に入力してください。 Google Pay または Apple Pay ウォレットのいずれかが関連付けられた有効カードがある場合、このデモでは対応するウォレットのみが表示されます。

導入作業

コーディングが一部必須

接続方法のタイプ

カスタムの決済フローに UI コンポーネントを組み合わせる

UI のカスタマイズ

Appearance API による CSS レベルのカスタマイズ

まず、Stripe アカウントを登録します。

アプリケーションから Stripe API にアクセスするには、Stripe の公式ライブラリを使用します。

PaymentIntent を作成する
サーバー側

Stripe は PaymentIntent (支払いインテント) オブジェクトを使用して、顧客から支払いを回収する意図を示し、プロセス全体を通して請求の実施と支払い状態の変化を追跡します。

購入プロセスで顧客に表示される支払い方法は、PaymentIntent にも含まれています。Stripe によってダッシュボードの設定から支払い方法を自動的に取得することも、手動でリスト化することもできます。

貴社の構築済みのシステムで支払い方法の提供にコードベースのオプションを必要とする場合を除き、支払い方法を手動でリスト化しないでください。Stripe は通貨、支払い方法の制約、その他のパラメーターを評価し、対応可能な支払い方法のリストを決定します。購入完了率の上昇につながり、使用通貨と顧客の所在地に最も適した支払い方法を優先的に表示します。一方、優先度の低い支払い方法は、オーバーフローメニューに隠された状態になります。

サーバーで金額と通貨を有効にして PaymentIntent を作成します。最新バージョンの API では、Stripe はデフォルトで機能を有効にしているため、automatic_payment_methods パラメーターの指定は必要ありません。支払い方法はダッシュボードで管理できます。Stripe は、取引の金額、通貨、決済フローなどの要素に基づいて、適切な支払い方法が返されるように処理します。

client secret を取得する

PaymentIntent には、client secret が含まれています。これは、支払いプロセスを安全に完了するためにクライアント側で使用されます。client secret をクライアント側に渡す際は、いくつかの方法を使用できます。

ブラウザーの fetch 関数を使用して、サーバーのエンドポイントから client secret を取得します。この方法は、クライアント側が 1 ページのアプリケーションで、特に React などの最新のフロントエンドフレームワークで構築されている場合に最適です。client secret を処理するサーバーのエンドポイントを作成します。

その後、クライアント側で JavaScript を使用して client secret を取得します。

(async () => {
  const response = await fetch('/secret');
  const {client_secret: clientSecret} = await response.json();
  // Render the form using the clientSecret
})();

支払いの詳細を収集する
クライアント側

Payment Element を使用してクライアント側で支払い詳細を収集します。Payment Element は事前構築された UI コンポーネントであり、さまざまな決済手段の詳細の収集をシンプルにします。

Payment Element には、HTTPS 接続を介して支払い情報を Stripe に安全に送信する iframe が含まれています。一部の支払い方法では、支払いを確定するために別のページにリダイレクトする必要があるため、Payment Element を別の iframe 内に配置しないでください。

iframe の使用を選択し、Apple Pay または Google Pay を受け付ける場合、iframe の allow 属性が "payment *" に設定されている必要があります。

構築済みのシステムを機能させるには、決済ページのアドレスの先頭を http:// ではなく https:// にする必要があります。HTTPS を使用しなくてもシステムをテストできますが、本番環境で決済を受け付ける準備が整ったら、必ず、HTTPS を有効にしてください。

Stripe.js を設定する

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

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/v3/"></script>
</head>

決済ページで以下の JavaScript を使用して、Stripe のインスタンスを作成します。

checkout.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 ノード (コンテナー) を作成します。

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

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

client secret は支払いを完了できるため、慎重に取り扱う必要があります。記録したり、URL に埋め込んだり、当該の顧客以外に漏洩することがないようにしてください。

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

// Set up Stripe.js and Elements to use in checkout form, passing the client secret obtained in a previous step
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 をカスタマイズできます。

住所を収集

デフォルトでは、Payment Element は必要な請求先住所情報のみを収集します。(たとえば、デジタル商品およびサービスの税金を計算するなどの目的で) 顧客の詳細な請求先住所または配送先住所を収集するには、Address Element を使用します。

Apple Pay マーチャントトークンをリクエストする

Apple Pay の決済を受け付けるよう自社のシステムを構築している場合、マーチャントトークンを返すように Apple Pay インターフェイスを設定して、加盟店が開始する取引 (MIT) を有効にすることをお勧めします。Payment Element で関連するマーチャントトークンのタイプをリクエストします。

Stripe に支払いを送信する
クライアント側

Payment Element からの詳細を指定して stripe.confirmPayment を使用し、支払いを完了します。ユーザーが支払いを完了した後に Stripe がユーザーをリダイレクトする場所を指定するには、この関数に return_url を指定します。ユーザーはまず、銀行のオーソリページなどの中間サイトにリダイレクトされ、その後 return_url にリダイレクトされます。カード支払いでは、支払いが正常に完了するとすぐに return_url にリダイレクトします。

カード決済で支払いの完了後にリダイレクトを行わない場合は、redirect に if_required を設定できます。これで、リダイレクトベースの決済手段で購入する顧客のみがリダイレクトされます。

checkout.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`.
  }
});

return_url が、Web サイト上の支払いステータスを表示するページと対応していることを確認します。Stripe が顧客を return_url にリダイレクトするときは、以下の URL クエリーパラメーターが指定されます。

パラメーター	説明
`payment_intent`	`PaymentIntent` の一意の識別子。
`payment_intent_client_secret`	`PaymentIntent` オブジェクトの client secret。

注意

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

クエリパラメーターのいずれか 1 つを使用して 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 は payment_intent.succeeded イベントを送信します。ダッシュボードの Webhook ツールを使用するか Webhook のガイドに従ってこれらのイベントを受信し、顧客への注文確認メールの送信、データベースでの売上の記録、配送ワークフローの開始などのアクションを実行します。

クライアントからのコールバックを待つのではなく、これらのイベントをリッスンします。クライアントでは、コールバックが実行される前に顧客がブラウザーのウィンドウを閉じたり、アプリを終了する場合、また悪意を持つクライアントがレスポンスを不正操作する場合もあります。非同期型のイベントをリッスンするよう組み込みを設定すると、単一の組み込みで複数の異なるタイプの支払い方法を受け付けることができます。

Payment Element を使用して支払いを回収する場合は、payment_intent.succeeded イベントのほかにこれらのイベントを処理することをお勧めします。

イベント	説明	アクション
payment_intent.succeeded	顧客が正常に支払いを完了したときに送信されます。	顧客に注文の確定を送信し、顧客の注文のフルフィルメントを実行します。
payment_intent.processing	顧客が正常に支払いを開始したが、支払いがまだ完了していない場合に送信されます。このイベントは、多くの場合、顧客が口座引き落としを開始するときに送信されます。その後、`payment_intent.succeeded` イベント、また、失敗の場合は `payment_intent.payment_failed` イベントが送信されます。	顧客に注文確認メールを送信し、支払いが保留中であることを示します。デジタル商品では、支払いの完了を待たずに注文のフルフィルメントを行うことが必要になる場合があります。
payment_intent.payment_failed	顧客が支払いを試みたが、支払いに失敗する場合に送信されます。	支払いが `processing` から `payment_failed` に変わった場合は、顧客に再度支払いを試すように促します。

実装内容をテストする

カード番号	シナリオ	テスト方法
	カード支払いは成功し、認証は必要とされません。	クレジットカード番号と、任意の有効期限、セキュリティコード、郵便番号を使用してクレジットカードフォームに入力します。
	カード支払いには認証が必要です。	クレジットカード番号と、任意の有効期限、セキュリティコード、郵便番号を使用してクレジットカードフォームに入力します。
	カードは、`insufficient_funds` などの拒否コードで拒否されます。	クレジットカード番号と、任意の有効期限、セキュリティコード、郵便番号を使用してクレジットカードフォームに入力します。
	UnionPay カードは、13 ～ 19 桁の可変長です。	クレジットカード番号と、任意の有効期限、セキュリティコード、郵便番号を使用してクレジットカードフォームに入力します。

実装内容をテストするためのその他の情報については、テストをご覧ください。

オプションその他の支払い方法を有効にする

手数料を回収する

When a payment is processed, rather than transfer the full amount of the transaction to a connected account, your platform can decide to take a portion of the transaction amount in the form of fees. You can set fee pricing in two different ways:

Use the Platform Pricing Tool to set and test application fee pricing rules. This no-code feature in the Stripe Dashboard is currently only available for platforms responsible for paying Stripe fees.
Set your pricing rules in-house, specifying fees directly in a PaymentIntent using either the application_fee_amount or transfer_data[amount] parameter. Fees set with this method override the pricing logic specified in the Platform Pricing Tool.

application_fee_amount を指定して支払いを作成すると、支払いのキャプチャー後に、支払いの総額が即座にプラットフォームから transfer_data[destination] アカウントに送金されます。その後、application_fee_amount (上限は支払い総額) がプラットフォームに送金されます。

プラットフォーム手数料が回収されると、Application Fee (プラットフォーム手数料) オブジェクトが作成されます。プラットフォーム手数料のリストは、ダッシュボード、プラットフォーム手数料、または Sigma で確認できます。プラットフォーム手数料オブジェクトの amount プロパティを使用して、項目別の手数料レポートを作成することもできます。

application_fee_amount を使用する際には、以下の点に留意します。

application_fee_amount は合計取引額が上限です。
application_fee_amount は常に取引と同じ通貨で計算されます。
プラットフォーム手数料は、連結アカウントの売上処理通貨と同じ通貨で売上として処理されます。クロスボーダーデスティネーション支払いの場合は、プラットフォームの売上処理通貨と異なる通貨になる場合があります。
application_fee_amount がお客様のアカウントに送金された後に、お客様のプラットフォームが Stripe 手数料を支払います。
金額には追加の Stripe 手数料は適用されません。
プラットフォームは埋め込みのプラットフォーム手数料レポートを使用して、回収した手数料を照合できます。
Stripe がオンラインで提供するダッシュボードや、支払い詳細コンポーネントなどのコンポーネントでは、連結アカウントは合計金額とプラットフォーム手数料のどちらの金額も表示できます。

売上のフロー

上記のコードでは、支払いの全額 (10.00 USD) が連結アカウントの保留残高に追加されます。application_fee_amount (1.23 USD) はその支払い金額から差し引かれ、お客様のプラットフォームに送金されます。次に Stripe 手数料 (0.59 USD) がプラットフォームアカウントの残高から差し引かれます。プラットフォーム手数料から Stripe 手数料を差し引いた金額 (1.23 USD - 0.59 USD = 0.64 USD) は、プラットフォームアカウントの残高に残ります。

通常の Stripe 支払いからの売上と同様に、プラットフォームアカウントの通常の送金スケジュールで application_fee_amount が利用可能になります。

売上処理加盟店を指定する

売上処理加盟店は、アカウントに設定されたケイパビリティと支払いの作成方法によって決まります。売上処理加盟店は、支払いの作成に誰の情報を使用するかを決定します。これには、その支払いに使用される顧客のクレジットカードまたは銀行口座の明細に表示される明細書表記 (プラットフォームまたは連結アカウントのもの) が含まれます。

売上処理加盟店を指定することにより、誰に対して支払いを作成するかをより明確にすることができます。たとえば、一部のプラットフォームは最終顧客がプラットフォーム (オンデマンドプラットフォームなど) と直接やり取りすることを理由として、売上処理加盟店となることを希望します。ただし、これと異なり最終顧客と直接やり取りする連結アカウントが存在するプラットフォームもあります (E コマースプラットフォーム上のストアなど)。こうしたシナリオでは、連結アカウントを売上処理加盟店にするのが合理的です。

連結アカウントの ID に on_behalf_of パラメーターを設定して、そのアカウントを支払いの売上処理加盟店にすることができます。on_behalf_of を使用すると、以下のようになります。

連結アカウントの国と売上処理通貨を使用して、支払いが売上として処理されます。
連結アカウントの国の手数料体系が使用されます。
連結アカウントの明細書表記が顧客のクレジットカード明細書に表示されます。
連結アカウントがプラットフォームと異なる国に所在する場合、連結アカウントの住所と電話番号が顧客のクレジットカード明細書に表示されます。
入金前の保留中の残高が保持される日数は、連結アカウントの delay_days 設定によって異なります。

on_behalf_of が省略された場合、プラットフォームが取引に関する金銭的責任を負います。

注意

on_behalf_of パラメーターは、card_payments などの支払いケイパビリティを持つ連結アカウントのみで利用できます。受取人利用規約が適用されているアカウントは、card_payments やその他の支払いケイパビリティをリクエストできません。

返金する

Payment Intents API を使用している場合、返金は最も最近に作成された支払いに対して発行する必要があります。

プラットフォームアカウントで作成された支払いは、プラットフォームアカウントのシークレットキーを使用して返金できます。transfer_data[destination] が設定された支払いを返金する場合、デフォルトではデスティネーションアカウントがそこに送金された売上を保持し、プラットフォームアカウントがその返金からマイナスの残高をカバーします。その返金をカバーするために連結アカウントから売上を取り戻すには、返金を作成する際に reverse_transfer パラメータを true に設定します。

デフォルトでは支払い額すべてが返金されますが、amount 値を正の整数に設定することで、一部返金を作成することができます。

その払い戻しによって支払い額全額が返金される場合、送金額全額が差し戻しされます。それ以外の場合には、送金額の比例配分された部分が差し戻しされます。

プラットフォーム手数料を返金する

プラットフォーム手数料が含まれる支払いを返金すると、デフォルトではプラットフォームアカウントがプラットフォーム手数料の売上を確保します。プラットフォーム手数料の売上を連結アカウントに戻すには、返金を作成する際に refund_application_fee パラメーターに true を設定します。

デスティネーション支払いのプラットフォーム手数料を返金する場合には、送金も差し戻す必要があることに注意します。その返金によって支払い額全額が返金される場合、プラットフォーム手数料の全額も払い戻されます。それ以外の場合には、プラットフォーム手数料の比例配分された部分が返金されます。

別の方法として、false 値の refund_application_fee を指定し、API を通じてプラットフォーム手数料を別途返金することもできます。

失敗した返金

返金が失敗した場合、またはキャンセルした場合、失敗した返金額はプラットフォームアカウントの Stripe 残高に戻されます。必要に応じて、送金を作成して、資金を連結アカウントに移動します。

不審請求の申請を処理する

デスティネーション支払いでは、on_behalf_of の有無にかかわらず、プラットフォームアカウントから不審請求の申請に係る金額と手数料が引き落とされます。

We recommend setting up a webhook to listen to dispute created events. When that happens, you can attempt to recover funds from the connected account by reversing the transfer through the Dashboard or by creating a transfer reversal.

If the connected account has a negative balance, Stripe attempts to debit its external account if debit_negative_balances is set to true.

If you challenge the dispute and win, you can transfer the funds that you previously reversed back to the connected account. If your platform has an insufficient balance, the transfer fails. Prevent insufficient balance errors by adding funds to your Stripe balance.

よくある間違い

Retransferring a previous reversal is subject to cross-border transfer restrictions, meaning you might have no means to repay your connected account. Instead, wait to recover disputed cross-border payment transfers for destination charges with on_behalf_of until after a dispute is lost.