はじめに

Stripeは非常にドキュメントが充実しており、サポートも手厚い印象です。一方ユースケースや利用APIのベストプラクティスは探し当てるのが大変な印象もあります。サポートの方に聞くのもいいのですが、なるべく往復回数を減らすために、まずは自分で調べ切ることが必要だと思います。そんな方々にプラットフォーム×Stripeでの実装方針を最短で把握できるようにこちらの記事を書きました。参考になれば幸いです。

今回は「実装編」になります。プラットフォームのオーソドックスなStripe実装方法についてご紹介していきます。

資金フロー

今回私が作成したプラットフォーム資金の動きはデスティネーション支払いになります。一般的なプラットフォームは売り手が商品を買手に提供して、対価を支払います。プラットフォーム事業であればこの形になることが多いかと思います。

上記を参考に、ISSUEプラットフォームを表すとこのような形になります。
企業はエンジニアに技術力を提供してもらい、その対価として報酬を支払います。支払われた報酬は一度ISSUEプラットフォームを介してエンジニアへ送金されます。

要件

企業(ユーザー)

①報酬支払い用のクレカ登録ができる
②支払いは承認されるまで、売上を確定したくない

エンジニア

①報酬入金のための銀行口座が登録できる
②customアカウントを有効化するために、必要情報の入力をする
③本人確認できる

CS

①返金処理が容易にできる
②入金スケジュール等を把握できる
③顧客情報の状況を確認できる

開発者

①基本的にオペレーションは自動化したい。
→クレカ、口座登録、必要事項入力、本人確認などの処理はAPIが提供されているので、そちらを利用しました。
②クレカ登録などセキュリティが求められるものはライブラリを使いたい

実装編

それでは決済フローの実装を見ていきます。
こちらはプラットフォーム決済のオーソドックスなフローを想定したものです。

カード登録(買い手)

今回は支払い方法にクレジットカード決済を採用しています。比較的簡単に実装できてライブラリも充実しているのでおすすめの支払い方法です。個人、法人問わず決済方法として利用できるのも魅力的です。

実装方針のポイントは2つです。

• クレカ入力フォームは公式が出しているものを利用する
• 具体的なクレカの情報(番号や名義など)はプラットフォームのDBには持たせない

クレカ入力フォームは公式が出しているものを利用する

クレカに限らず、メンテナンスを考慮すると決済周りのライブラリはStripe公式が出しているものを利用するのが安全だと思います。React.js、TypeScriptでカード登録をする際はreact-stripe-jsを利用しました。その他の言語にも対応しています。詳しくはstripe organizationを参考ください。CardElementコンポーネントを利用することでフロントから安全にpaymentMethodを作成することができます。詳しくはReadme参考

【カード入力フォーム実装例】

公式Readmeを参考にしたフォーム実装例

開発時に便利なテストカード

銀行口座登録(売り手)

【実装イメージ】

銀行口座登録用のフォームはライブラリから提供されていませんので自身で作る必要があります。今回はStripe connectアカウント(売り手)に銀行口座を紐づけるために、銀行口座情報をトークン化してacountsオブジェクトに紐付けます。

account_holder_type: 銀行口座を設定する対象の種類です。 個人ならindividual、法人ならcompanyを設定する必要があります。

routing_number: 銀行を識別する機関コードです。【金融機関コード+支店コード】から構成されています。例えば「三菱ＵＦＪ銀行 八重洲通支店」の場合、routing_numberは0005022になります。ポイントは必ず7桁にする必要があることです。右詰めで数字がない場合は「0」をおきましょう。

銀行名	三菱ＵＦＪ銀行
金融機関コード	0005
支店名	八重洲通支店
支店コード	022
routing_number	0005022

bank accountのtokenをcustomアカウントのexternal_accountに紐付けて、銀行口座の登録は完了になります。最後に、userに銀行口座情報のidを保持させれば、口座情報が必要なたびに問い合わせすることができます。
`

必要情報の登録(売り手)

【実装イメージ】

connectアカウントを利用するためには、必要情報の入力が必要になります。これは各国で求められる情報が異なりますが、日本だと以下のようになります(詳しくは公式から最新の情報を確認してください)

*ビジネスタイプがindividualの場合

	PARAMETER
(アカウント情報)
ビジネスタイプ	Business type=individual
利用規約への同意	tos_acceptance.ip(同意した時点のip) tos_acceptance.date(同意した日付)
銀行口座(External account)	external_account
(ビジネスタイプがindividualの場合に必要な情報)
名前	individual.first_name_kana(性カナ) individual.first_name_kanji(性漢字) individual.last_name_kana(名前カナ) individual.last_name_kanji(名前漢字)
誕生日	individual.dob.day individual.dob.month individual.dob.year
住所(カナ)	individual.address_kana.line1 individual.address_kana.postal_code individual.address_kana.city individual.address_kana.state individual.address_kana.town
住所(漢字)	individual.address_kanji.line1 individual.address_kanji.postal_code individual.address_kanji.city individual.address_kanji.state individual.address_kanji.town
電話番号	individual.phone
性別	individual.gender

(tips)住所のカナ変換はgooラボさんのひらがなAPIを使う

必要情報住所での入力内容は漢字のみにして、カタカナ化はAPIを利用すると入力量が減ってUXが向上するのでおすすめです。
ひらがな化API

本人確認(売り手)

【実装イメージ】

本人確認はAPIが提供されているので、こちらを利用します。

本人確認に利用可能な書類

詳しくは公式から最新の情報をご覧ください

• パスポート (Passport)
• 運転免許証 (Driver's license)
• 在留カード・特別永住者証明書 (Residence Card)
• マイナンバーカード (顔写真付き) (My Number Card, with photo)
• 住民基本台帳カード (顔写真付き)/住基カード (顔写真付き) (Juki Card, with photo)

本人確認を更新する方法はPersonかAccountオブジェクトのindividual.verificationを更新する必要がありますが、今回はAccountからの更新にします。

本人確認処理アップロード手順
① Stripeに本人確認書類をアップロードする
② ①で返却されたfileオブジェクトをcustomアカウントに紐づける

本人確認処理アップロード手順

本人確認か必要な状態かどうかを検証する

本人確認済みかどうかによって、フロントの表示を制御したい場合はaccount.requirements.currently_dueと言う文字列の配列に、"individual.verification.document"と言う文字列が含まれるかで判断できます。requirementsはアカウントの確認に必要な要件のことを表します。本人確認のテスト時にもこのフィールドを確認することによって本人確認が完了しているかどうかを判断できます。

本人確認書類を提出したかどうかを判断する

individual.verification.documentのfrontとbackを参照することで判断できます。frontとbackフィールドはstringで書類データがアップロードされていればfileのidが入ります。アップロードしていなければnullになります。

支払い処理(買い手)

今回お伝えする支払い処理は2種類です。

• 仮売上・実売上
• 即時売上

仮売上・実売上

仮売上とはカード限度額を確保するだけの処理区分になります。実売上は仮売上後に、売上確定する処理区分になります。これは、予約やECサービスなどでよく使われる決済方式になります。例えば、Airbnbのようなサービスをイメージするとわかりやすいと思います。宿泊先を予約した時点ではカードからの引き落としは確定していません。実際は宿泊が終わってからカードからの引き落としがされます。メリットとしてはなんらかの理由で宿泊がキャンセルになった場合は引き落としされないと言う点です。予約もキャンセルしたのに引き落としがあったなどのようなトラブルを防ぐことができます。

参考
クレジットカード／【仮売上】と【実売上】と【即時売上】の違いは何ですか？
クレジットカードのよくある質問

即時売上

【仮売上】と【実売上】の処理を同時に実施し、売上確定する処理区分になります。デジタルコンテンツのダウンロードなどすぐに、即時にサービス提供する必要があるものなどに適しています。

参考
クレジットカード決済の課金タイミングは変えられる！仮売上・実売上について知ろう

仮売上・実売上の実装

支払い処理にはStripe APIのPaymentIntentsを使用します。以前はChargeでの決済が行われていましたが、今後新機能はPaymentIntentsで開発されるので新しく決済を実装される際は、PaymentIntentsの利用をおすすめします。

仮売上・実売上の実装手順

① 仮売上処理
② 実売上処理

① 仮売上処理

Stripeの仮売上期間は7日間とGMOの60日間と比べると短いので注意しましょう。実装は下記のようになります。

idempotencyKey: リクエストの冪等性を担保するためのkeyになります。冪等性を担保することによってネットワーク接続エラーなどの原因よる重複したPaymentIntentsを作成されなくなり、2重支払いのバグなどを防ぎます。idempotencyKeyにはリクエストごとに一意になるようにトランザクションなどのid(V4 UUIDs推奨)を設定します。idempotencyKeyの有効期限は24時間です。

capture_method: 資金を顧客の口座から引き落とすタイミングを設定します。manualならオーソリしてカードの枠だけ確保しに行きます。automaticなら即時売上になります。

confirm: 顧客が支払い情報を入力し内容が一致していれば確定するフローが想定されています。支払い情報は既に作成済でpaymentMethodIdに紐付けられているので確認する必要はありません。ですので確認済みのtrueに設定します。

② 実売上処理

capture_methodをmanualで作成したpaymentIntentsを指定してcaptureすることで支払いが確定します。サービスが提供された時点でこちらのメソッドを呼び出すことになります。

即時売上の実装手順

description: 支払いの説明を追加することができます。Stripeのダッシュボードの支払い一覧でも誰の決済かが一目瞭然になるのでオススメです。

指定したcustomアカウントに送金する

支払いデータ作成時に、直接売り手に報酬を送金する場合は下記のようなコードになります。paymentIntents作成時にtransfer_dataを指定することで送金先と送金額を設定できます。下記のコードだと10,000円の支払額の内、8,000円を売り手(customユーザー)に送金しています。

transfer_dataは内部的にTransferという送金を管理するデータを作成しています。paymentIntents.amountとpaymentIntents.transfer_data.amountの差額を利用してプラットフォーム手数料を利用することが可能です。

例) プラットフォーム手数料が20%で取引額(支払額)が10,000円の場合

paymentIntents.amount→10,000円 (支払額)
paymentIntents.transfer_data.amount→8,000円　(送金額)

支払額-送金額の差額2,000円がプラットフォーム手数料になります。手数料の計算については公式のドキュメントがわかりやすいので一読をおすすめします。

最後に

いかがでしたでしょうか。
基礎的な内容ですが、プラットフォームを構築する上で必要な実装を記載しました。これからサービスを構築していく方の参考になれば幸いです。