Chapter 10

Onboarding via API

Toru Furukawa
Toru Furukawa
2021.12.10に更新

API を使って Connected Account を登録するフローを見ていく。 API を利用した確認処理 をベースにしている。

データ

下図のようなエンティティの関係を想定する。

Platform           Seller
    |                 |
    |              Seller Info
    |                 |
Platform Account   Connected Account

現実世界には Platform と Seller という事業主体が存在する。

Stripe 内には、Platform にひもづく Platform Account と、Seller にひもづく Connected Account を作る。

Custom Connect では、Platform がアカウント管理の権限と責任を持つ。なので、Seller が直接 Connected Account とはつながらない。Platform があつめてきた Seller Info が Connected Account の情報源である。

Platform が提供するサービスは、Seller を管理する情報を持っているだろう。管理画面にログインする認証情報とか、連絡先とか、その他、Platform サービスの利用者アカウント的なものがある。上図の Seller Info というのが、それだ。

シーケンス

Connected Account の登録シーケンスは、次のようになる。

  1. Seller が Platform サービスにログイン
  2. (まだだったら)Platform が、Stripe に Connected Account を作成する
  3. Seller が Platform サービスの入力フォームで情報を登録する
  4. Platform が Stripe に情報を登録する
  5. Stripe が Platform に、非同期で結果を送る

Platform は、Seller ごとに Seller Info を管理するので、認証機能を提供する。

Account と Person を作成・更新するんだけれど、データフォーマットの validation がとおれば、API コールは完了する。ここで失敗すると、もう一度登録用の API コールが必要になる。なので事実上、Platform がウェブフォームのレベルでバリデーションする必要がある。

その後、非同期に verify (審査)されて、問題なければ完了する。問題があれば再入力・再登録などが必要。全部完了してから、Seller とビジネスができる状態になる。

API 呼び出し

法人の director と representative が異なる場合
# 法人情報
curl https://api.stripe.com/v1/accounts \
  -u sk_xxxx: \
  -d type=custom \
  -d business_type=company \
  -d "company[name_kanji]"="鈴木コンツェルン株式会社" \
  ...

# director の情報
curl https://api.stripe.com/v1/accounts/acct_xxxx/persons \
  -u sk_xxxx: \
  -d "relationship[director]"=true \
  -d last_name_kanji="鈴木" \
  ...

# representative の情報
curl https://api.stripe.com/v1/accounts/acct_xxxx/persons \
  -u sk_xxxx: \
  -d "relationship[representative]"=true \
  -d last_name_kanji="佐藤" \
  ...
法人の director と representative が同一の場合
# 法人情報
curl https://api.stripe.com/v1/accounts \
  -u sk_xxxx: \
  -d type=custom \
  -d business_type=company \
  -d "company[name_kanji]"="鈴木株式会社" \
  ...

# director の情報
curl https://api.stripe.com/v1/accounts/acct_xxxx/persons \
  -u sk_xxxx: \
  -d "relationship[director]"=true \
  -d "relationship[representative]"=true \
  -d last_name_kanji="鈴木" \
  ...
個人事業主の場合
# 個人事業主の情報
curl https://api.stripe.com/v1/accounts \
  -u sk_xxxx: \
  -d type=custom \
  -d business_type=individual \
  -d "individual[last_name_kanji]"="鈴木"
  ...

Account の状態

Account と Person のそれぞれに検証(validation)と確認(verification)が行われる。validation は API でパラメータチェック、verification は審査。後者は account.verification.statusperson.verification.status で確認できる。何が足りないか、は account.requirements を確認する。

まとめ

API を使って Connected Account を登録するフローを見てきた。明日は、Stripe が用意したフォームを使って登録するフローを見ていく。