Ruby
Rails
stripe

Stripe Connectを使ってEコマースの決済システムを構築する

背景

Eコマースの決済プラットフォームを構築するにあたってStripe Connectを利用しました。
https://stripe.com/connect

サービスの概要やAPIの仕様など大体の事は公式のドキュメントを見ればわかりますが、実際に作業を進める際はドキュメントを追うだけではわからないことも出てくるかと思います。

ここでは公式のドキュメントと合わせて、自分が躓いた点について追記しつつ情報をまとめました。

想定する環境

プラットフォーム

ショップが商品を販売、カスタマーが商品を購入することができるEコマースプラットフォーム。
この販売と購入を実現する決済システムをStripe Connectで構築します。

  • プラットフォーム
    • Eコマースプラットフォームを提供する開発者
    • Stripe上の決済から手数料を徴収する
  • ショップ
    • 商品を販売する店舗
    • 売上を特定の口座で受け取る
  • カスタマー
    • 商品を購入する顧客
    • クレジットカード決済を行う

APIについて

ベースとなるシステムがRailsだったのでStripe APIのうちruby版を利用しました。
https://stripe.com/docs/api/ruby
https://github.com/stripe/stripe-ruby

StripeではAPIを使用する際アカウントごとに割り当てられたSecret Keyを使います。
Secret Keyには本番環境で使うlive keyとテスト用のtest keyがあるので、開発環境でlive keyを使わないよう注意しましょう。

1. プラットフォームの作成

Stripeのアカウントを開設するだけです。
アカウントを開設した時点でtest keyを使用できるので、とりあえず色々試すには十分でしょう。
live keyを使用するためにはアカウントをactivateする必要があります。
https://stripe.com/docs/dashboard#activating-your-account

2. ショップに関する情報を作成・管理する

決済を実行するためにはショップに売上を出金するための口座情報を登録してもらう必要があります。
Stripe Connect上にショップのアカウント(Connected account)を作成し、口座情報(External account)を登録するまでの手順を見ていきます。

Stripe ConnectにはStandard, Express, Customというアカウントタイプが提供されており、ビジネスモデルに応じていずれかのタイプを選択することができます。
ここではCustomを使う場合について記載しています。
https://stripe.com/connect/account-types

2.1. Custom accountの作成

Custom accountの作成はtypeにcustomを指定します。
https://stripe.com/docs/api/ruby#create_account
https://stripe.com/docs/connect/custom-accounts#create

Custom accountは個人事業主(individual)と法人(company)に対して作成することができますが、それぞれで必要な情報(legal entity)が異なります。
https://stripe.com/docs/connect/required-verification-information

個人事業主の場合、住所、生年月日、氏名、性別、電話番号が必要となります。
ここで登録する住所は店舗住所ではなく、個人事業主として登録されている本人の住所とのことです。

法人の場合、会社情報と担当者情報の両方が必要となります。
会社情報については会社名、会社住所、電話番号にあわせてbusiness tax idが必要となります。
business tax idは日本では会社法人等番号と呼ばれる数字12桁のことです。
法人の担当者情報については住所、生年月日、氏名、性別が必要ですが、この住所は所属する会社ではなく担当者個人の住所を登録します。

また個人事業主、法人のいずれにおいても本人確認書類(verification document)が必要となります。
これは運転免許証やパスポートなど公的な身分証明書であればいいようですが、保険証など顔写真の無いものに関しては追加の書類を提出する必要があるようです。
本人確認書類はStripeにアップロードしてidを指定します。
https://stripe.com/docs/connect/required-verification-information#additional-verification-requirements-for-japan
https://stripe.com/docs/file-upload

2.2. External accountの作成

Custom accountが作成できたら、次はExternal accountを作成します。
External accountでobjectをbank accountとすることで口座情報を登録します。
https://stripe.com/docs/api/ruby#account_create_bank_account
https://stripe.com/docs/connect/payouts#formats

口座番号や口座名義などは問題ないのですが、routing numberについては少し悩みました。
公式のドキュメントによるとrouting numberは銀行コード(数字4桁)と支店コード(数字3桁)を繋げたものとありましたが、ショップが登録してもらう際にいちいち調べてもらうのも手間ですし、これに関して問い合わせがきたら対応が面倒です。
そこでzengin-codeというGemを用いてフロントで銀行名と支店名を選択させつつ、APIリクエスト時に銀行コードと支店コードを繋げる仕組みにしてみました。
金融機関のデータは定期的に更新されているようなので、国内の金融機関はほぼカバーできると思います。
https://github.com/zengin-code/zengin-rb

また、登録できるのは普通口座のみで当座口座では登録できないそうです。

2.3. Dashboardで確認

正常に情報が送信できるとDashboard上で確認することができます。

Custom accountはまずpendingというStripeの審査を待つ状態になります。
登録情報に問題がなければverifiedとなりますが、情報に間違いや不足があるとunverifiedとなります。
unverifiedになったらDashboardから確認して情報を更新しましょう。

2.4. サービスとの関連付け

Stripeを使えば担当者の個人情報や口座情報は直接管理する必要がありません。
データベースの設計はサービスによって異なると思いますが、サービス上のショップアカウントとStripeのCustom accountが関連付けできるようにCustom accountを作成した際のレスポンスに含まれるidを保持しておけばOKです。

3. カスタマーに関する情報を作成・管理する

ショップが商品を販売する準備ができたので、次はカスタマーが決済を行うための準備をしていきます。
Stripe上にカスタマーのアカウント(Customer)を作成し、カード情報(Card)を登録するまでの手順を見ていきます。

3.1. Customerの作成

Customer自体の作成は特に追加の情報など不要です。
https://stripe.com/docs/api/ruby#create_customer

3.2. Cardの作成

Customerが作成できたら、クレジットカードを登録していきます。
CardはCustomerのsourceに追加する形で登録することができます。
https://stripe.com/docs/api/ruby#create_card

CardはCustomerに複数登録することができ、現在はVISA, Master, AMEXが対応しているようです。

3.3. サービスとの関連付け

ショップの場合と同様、カード情報などはStripe上で管理されます。
サービス上のカスタマーアカウントとStripeのCustomerが関連付けできるようCustomerの作成した際のレスポンスに含まれるidを保持しておきましょう。

4. 決済を行う

Stripeにショップとカスタマーの情報が揃ったら決済を行うことができるようになります。
ここでショップが出品した商品をカスタマーが購入するという決済に対して、プラットフォームが20%の手数料を徴収する場合を想定します。

4.1. 支払情報の作成

決済から手数料を徴収するにはDestination Chargeという仕組みを利用します。
https://stripe.com/docs/connect/destination-charges

Destination Chargeにおいてdestinationを指定することで、手数料を引いた分だけショップの売上とすることができます。
例えば10,000円の決済に20%の手数料を設定する場合次のようなリクエストになります。

charge = Stripe::Charge.create(
  amount: 10000, # 総額
  currency: 'JPY', # 通貨
  card: 'card_xxxxxxxx', # Cardのid
  customer: 'cus_xxxxxxxx', # Customerのid
  destination: {
    amount: 8000, # 手数料20%を引いた金額
    account: 'acct_xxxxxxxx' # Custom accountのid
  }
)

ショップは8,000円が売上となり、プラットフォームは手数料20%から決済手数料などを引いた分が売上となります。

4.2. サービスとの関連付け

Destination Chargeが成功するとidが取得できるので、サービス上の注文情報に関連付けて保持しておきましょう。
決済のキャンセルを行う場合はこのidに対してRefundを行うことになります。

Destination ChargeのRefundはreverse_transferをtrueにしないとプラットフォームが返金することになるので注意しましょう。
https://stripe.com/docs/connect/destination-charges#issuing-refunds

まとめ

文章ばかりですがざっくりとStripe Connectを利用して決済システムを構築するための作業をまとめてみました。

ここでまとめたのは2017年9月現在の情報なので、ご利用の際は必ず最新の情報を参照するようにして下さい。
更新や削除の方法については触れていませんが、ご利用の際は適切なサービス設計を心がけましょう。

あとは悩んだらStripeのサポートに連絡することをおすすめします、対応が迅速丁寧で大変お世話になりました。