支払いを回収してマーケットプレイスに入金する

/v2/core/accounts API を使用して 連結アカウントのダッシュボードと責任 を指定して連結アカウントを 作成 します。

curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-08-27.preview" \
  --json '{
    "contact_email": "furever_contact@example.com",
    "display_name": "Furever",
    "defaults": {
        "responsibilities": {
            "fees_collector": "application",
            "losses_collector": "application"
        }
    },
    "dashboard": "express",
    "identity": {
        "business_details": {
            "registered_name": "Furever"
        },
        "country": "us",
        "entity_type": "company"
    },
    "configuration": {
        "merchant": {
            "capabilities": {
                "card_payments": {
                    "requested": true
                }
            }
        },
        "recipient": {
            "capabilities": {
                "stripe_balance": {
                    "stripe_transfers": {
                        "requested": true
                    }
                }
            }
        }
    },
    "include": [
        "configuration.merchant",
        "configuration.recipient",
        "identity",
        "requirements"
    ]
  }'

連結アカウントの情報をすでに収集している場合は、Account オブジェクトにその情報を事前入力できます。個人情報や事業情報、外部のアカウント情報など、あらゆるアカウント情報を事前に入力できます。

Connect アカウント登録で、事前入力された情報が要求されることはありません。ただし、アカウント所有者は Connect 利用規約に同意する前に、事前入力された情報を確認するよう求められます。

実装内容をテストする場合、テストデータを使用してアカウント情報を事前入力します。

アカウントリンクを作成する

以下のパラメーターを使用して Account Links v2 API を呼び出すことでアカウントリンクを作成できます。

• account
• refresh_url
• return_url
• type = account_onboarding
• configurations = recipient と merchant

curl -X POST https://api.stripe.com/v2/core/account_links \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-08-27.preview" \
  --json '{
    "account": 
"{{CONNECTED_ACCOUNT_ID}}",
    "use_case": {
        "type": "account_onboarding",
        "account_onboarding": {
            "configurations": [
                "recipient",
                "merchant"
            ],
            "refresh_url": "https://example.com/reauth",
            "return_url": "https://example.com/return"
        }
    }
  }'

ユーザーをアカウントリンク URL にリダイレクトする

アカウントリンク作成レスポンスには url 値が含まれます。アプリケーションでユーザーを認証したら、この URL にリダイレクトしてフローに送ります。アカウントリンク URL は連結アカウントユーザーの個人情報へのアクセスを許可するため、一時的な 1 回限りの使用です。情報を事前入力する場合は、アカウントリンクを生成する前に入力する必要があります。アカウントリンクの作成後は連結アカウントの情報の読み取りまたは書き込みができなくなります。

import UIKit
import SafariServices

let BackendAPIBaseURL: String = "" // Set to the URL of your backend server

class ConnectOnboardViewController: UIViewController {

    // ...

    override func viewDidLoad() {
        super.viewDidLoad()

        let connectWithStripeButton = UIButton(type: .system)
        connectWithStripeButton.setTitle("Connect with Stripe", for: .normal)
        connectWithStripeButton.addTarget(self, action: #selector(didSelectConnectWithStripe), for: .touchUpInside)
        view.addSubview(connectWithStripeButton)

        // ...
    }

    @objc
    func didSelectConnectWithStripe() {
        if let url = URL(string: BackendAPIBaseURL)?.appendingPathComponent("onboard-user") {
          var request = URLRequest(url: url)
          request.httpMethod = "POST"
          let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
              guard let data = data,
                  let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any],
                  let accountURLString = json["url"] as? String,
                  let accountURL = URL(string: accountURLString) else {
                      // handle error
              }

              let safariViewController = SFSafariViewController(url: accountURL)
              safariViewController.delegate = self

              DispatchQueue.main.async {
                  self.present(safariViewController, animated: true, completion: nil)
              }
          }
        }
    }

    // ...
}

extension ConnectOnboardViewController: SFSafariViewControllerDelegate {
    func safariViewControllerDidFinish(_ controller: SFSafariViewController) {
        // the user may have closed the SFSafariViewController instance before a redirect
        // occurred. Sync with your backend to confirm the correct state
    }
}

プラットフォームに戻るユーザーを処理する

Connect アカウント登録では return_url と refresh_url の両方を渡して、アカウントユーザーがプラットフォームにリダイレクトされるすべてのケースを処理する必要があります。

return_url

連結アカウントユーザーがアカウント登録フローを完了すると、Stripe はこの URL へのリダイレクトを実行します。ただしこれはすべての情報が収集されたことを意味するものでも、アカウントの要件がすべて満たされたことを意味するものでもありません。ユーザーがフローに正常に入りそこから正常に出たことのみを意味します。

この URL を通じて状態は渡されません。ユーザーが return_url にリダイレクトされたら、以下のいずれかを行いアカウントの要件の状態を確認します。

• v2.core.account[requirements].updated Webhook をリッスンします。
• Accounts v2 API を呼び出し、返されたオブジェクトを検査します。

refresh_url

以下のケースでは、Stripe はユーザーを refresh_url にリダイレクトします。

• リンクの期限が切れている (リンク作成後、数分が経過した)。
• ユーザーがすでに URL にアクセスしている (ユーザーがページを更新したか、ブラウザーで戻るボタンまたは進むボタンをクリックした)。
• プラットフォームがアカウントにアクセスできなくなった。
• アカウントが拒否された。

サーバーで同じパラメーターを使用して Account Links v2 を再度呼び出すメソッドをトリガーし、ユーザーを新しいリンクにリダイレクトするように refresh_url ページを設定します。

アカウント登録を完了していないユーザーを処理する

return_url にリダイレクトされたユーザーがアカウント登録プロセスを完了していない可能性があります。/v2/core/accounts エンドポイントを使用してユーザーのアカウントを取得し configuration.recipient.capabilities.stripe_balance.stripe_transfers.status が active かどうかを確認します。ステータスが active ではなく configuration.recipient.capabilities.stripe_balance.stripe_transfers.status_details.code が requirements_past_due の場合は UI プロンプトを表示してユーザーが新しいアカウントリンクを使用してアカウント登録を続行できるようにします。必要に応じて他のコードも処理します。

Checkout セッションを作成する クライアントおよびサーバー

Checkout セッションは、ラインアイテム、注文金額と通貨、および受け付け可能な支払い方法など、Stripe のオンライン決済ページで顧客に表示する内容を制御します。

サーバー側のエンドポイントを呼び出して Checkout セッションを作成する購入ボタンをウェブサイトに追加します。

<html>
  <head>
    <title>Checkout</title>
  </head>
  <body>
    <form action="/create-checkout-session" method="POST">
      <button type="submit">Checkout</button>
    </form>
  </body>
</html>

サーバー側で、Stripe の API に以下の呼び出しを行います。Checkout セッションを作成したら、レスポンスで返された URL に顧客をリダイレクトします。

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d mode=payment \
  -d "line_items[0][price]"=
"{{PRICE_ID}}" \
  -d "line_items[0][quantity]"=1 \
  -d "payment_intent_data[application_fee_amount]"=123 \
  -d "payment_intent_data[transfer_data][destination]"=
"{{CONNECTED_ACCOUNT_ID}}" \
  --data-urlencode success_url="https://example.com/success" \
  --data-urlencode cancel_url="https://example.com/cancel"

• line_items: この引数は、顧客が購入しようとしているアイテムを表します。このアイテムは Stripe がオンラインで提供するユーザーインターフェイスに表示されます。
• success_url: この引数は、支払いを完了したユーザーのリダイレクト先を示します。
• cancel_url: この引数は、キャンセルをクリックしたユーザーのリダイレクト先を示します。
• payment_intent_data[application_fee_amount]: この引数は、プラットフォームが取引で受け取る予定の金額を指定します。支払いがキャプチャーされると、プラットフォームから、transfer_data[destination] で指定された連結アカウントに支払い金額の全額が即時送金されます。その後 application_fee_amount がプラットフォームに返金され、プラットフォームの金額から Stripe 手数料が差し引かれます。
• payment_intent_data[transfer_data][destination]: この引数は、支払いがデスティネーション支払いであることを示します。デスティネーション支払いでは、支払いがプラットフォームで処理され、売上が即時かつ自動的に連結アカウントの保留中の残高に送金されます。賃貸住宅の例では、顧客がプラットフォームを使用して支払い、住宅所有者がプラットフォームで支払いを受ける機能を構築します。

Checkout では、デスティネーション支払いにプラットフォームアカウントのブランド設定を使用します。詳細については、ブランディングをカスタマイズするをご覧ください。

このセッションは、デスティネーション支払いを作成します。送金のタイミングを管理したり、1 回の支払いの売上を複数の当事者に送金したりする必要がある場合は、代わりに、支払いと送金別方式を使用してください。支払いと送金別方式を使用する場合は、連結アカウントによる支払いの受け付けを有効化する方法をご覧ください。

支払い後のイベントを処理する サーバー側

支払いが完了すると Stripe は checkout.session.completed イベントを送信します。Webhook を使用してこのイベントを受信し、顧客への注文確認メールの送信、データベースへの売上の記録、配送ワークフローの開始などのアクションを実行します。

クライアントからのコールバックを待つのではなく、これらのイベントをリッスンします。クライアント側では、コールバックの実行前に顧客がブラウザーのウィンドウを閉じたり、アプリケーションを終了したりする可能性があります。また、一部の支払い方法では支払いの確定までに 2 ～ 14 日かかることがあります。実装で非同期イベントをリッスンするように設定すると、1 つの実装で複数の支払い方法に対応できるようになります。

Checkout で支払いを回収するときは、checkout.session.completed イベントの処理に加えて、以下の 2 つのイベントも処理することをお勧めします。

これらのイベントのすべてに、Checkout Session (Checkout セッション) オブジェクトが含まれています。支払いが成功すると、基となる PaymentIntent のステータスが processing から succeeded に変わります。