🔖

Stripe Terminal Apps on Devicesのはじめかた：開発環境の整備から実装まで

に公開
Android
Capacitor
Stripe
決済
tech

この記事は、決済を実装した体験談や決済関連（クレカ、QRコード、何でもOK！）の情報を投稿しよう！ by PAY Advent Calendar 2025 の4日目の投稿です。

開発を始める前に：DevKitの購入手続きが最優先

Stripe Terminal Apps on Devicesの開発を始めるには、DevKit（開発用端末）が必要です。しかし、本番用端末とは異なり、DevKitはStripeダッシュボードから直接購入することはできません。営業担当者またはサポートへの連絡が必要です。この手続きを完了しない限り、DevKitを購入できず、開発を始めることができません。

DevKitを注文する手順

Stripe営業担当者がついている場合は、利用希望の旨を伝えてDevKitの購入手続きを依頼します。営業担当がついていない場合は、StripeサポートのフォームからApps on Devicesの利用リクエストを送信してください。ダッシュボードで有効化されたら、Terminal 端末 > 追加のリーダーとアクセサリー > Stripe Reader S700 Devkitから購入が可能になります。

devkit.png

開発を始めたいと思ったら、まず営業担当者またはサポートに連絡することをおすすめします。

通常のTerminalとApps on Devicesの違い

本記事で表記している「通常のStripe Terminal」とは、 ホストアプリ（POS / モバイルアプリ）側でUIや業務フローを実装し、 Stripe Terminal SDKを通じて決済端末（Reader）を制御する一般的な構成です。 この場合、決済端末に表示されるUIはStripeが提供する標準画面に限定されます。
Apps on Devices では、決済端末上で動作するアプリがUI・画面遷移・業務フローを担い、 端末自体がひとつのアプリ実行環境として振る舞います。 これにより、支払い前後を含めたUX全体をコードで設計できるようになります。。

DevKitが必要なのは、Apps on Devicesを使う場合のみです。通常のTerminalを使う場合は、DevKitは不要で本番用端末1台だけで開発・運用できます。一方、Apps on Devicesを使う場合は、DevKitと本番用端末の2台が必要になります。

DevKitと本番用端末の違い

DevKit（Stripe Reader S700 Devkit）は開発検証用のデバイスで、USBポートが有効でUSB経由でのadbやAndroid Studioでの実機デバッグが可能です。ただし、本番環境でのカード決済には対応していません（あくまで検証用）。価格は￥52,480です。

一方、本番用端末（Stripe Reader S700）では、USB経由でのadbやAndroid Studioでの実機デバッグは不可ですが、本番環境でのカード決済にも対応しています。価格は￥52,480です。

開発中はDevKitでデバッグを行い、本番環境では本番用端末を使うという流れになるため、2台分の端末費用がかかります。通常のTerminalを使う場合は本番用端末1台だけで問題ありません。

開発環境の整備

DevKitの購入手続きが完了したら、開発環境を整備しましょう。

Android Studioの用意

Androidアプリとして開発するため、Android Studioが必要です。Androidアプリ開発（Capacitorを使ったWebViewアプリ含む）と同じ開発環境で問題ありません。既にAndroid開発の環境が整っている方は、そのまま使えます。

デバイス仕様と制約

開発を始める前に、Stripe Reader S700の仕様と制約を理解しておくことが重要です。

デバイス仕様

Stripe Reader S700のハードウェア仕様は以下の通りです：

  • CPU：Qualcomm Snapdragon 665 QCM6125
  • RAM：4GB
  • ストレージ：64GB
  • OS：Android 10
  • 画面サイズ：1080x1920ピクセル
  • 画面解像度：420dpi（xxhdpi）

APKサイズとストレージの制限

Stripe APIにアップロードするAPKファイルは200MBまでという制限があります。また、アプリはデバイス上で8GB以下のストレージを使用する必要があります。Stripeはデバイス上で動作するすべてのアプリとソフトウェアコンポーネントのOTA（Over-The-Air）更新を管理するため、この制限が設けられています。

標準Androidとの違い

Stripe SmartPOS OSは、Android Open Source Project（AOSP）をベースにセキュリティとPCIコンプライアンスのために構築されています。標準のコンシューマー向けAndroidとはいくつかの点で異なります。

Google Play ServicesはStripe Androidデバイスでは利用できません。アプリにGoogle Play Services SDKを統合することはできますが、期待通りに動作するか確認が必要です。例えば、FirebaseやGoogle Maps SDKの一部はStripeデバイスでは機能しません。 通知は無効化されており、デバイスユーザーはホーム画面にアクセスできません。アプリまたはStripe Readerアプリのいずれかがプライマリとして常駐します。

本番用デバイスではUSBポートが無効化されており、Android Debug Bridge（adb）やデバッグは利用できません。開発目的ではDevKitデバイスを使用できます。

Android権限について

インストール時に、Stripe SmartPOS OSはアプリのマニフェスト内のAndroid権限を自動的に付与します。デバイスユーザーは実行時に権限承認を求められることはありません。アプリの権限は許可リストに対して検証され、許可リストを超える権限を要求するアプリは拒否されます。

許可されている権限のリストは公式ドキュメントで確認できます。カメラ、Bluetooth、位置情報の機能とAPIは実験段階であり、完全にテスト、検証、承認されていないことに注意が必要です。

日本の地理的制約について

日本でTerminal決済を処理する場合、いくつかの重要な制約があります。

アカウントとLocationの要件

Terminal決済を処理するには、資金を受け取るStripeアカウントとリーダーに関連付けられたLocationが同じ国にあり、現地通貨のみを受け入れる必要があります。日本でTerminal決済を受け付けるには、プラットフォームアカウントまたは接続アカウントのいずれかが日本にある必要があります。
詳細は公式ドキュメントを参照してください。

サポートされているカードブランドと通貨

日本では、Visa、Mastercard、American Express、JCB、Discoverの決済をサポートしています。すべての取引は日本円（JPY）で行う必要があります。

SetupIntentは使用不可

現在のところ、SetupIntentは使用できません。決済詳細の保存は、決済を収集した後にのみサポートされています。

開発を始めよう

開発環境と端末が整ったら、実際に開発を始めましょう。開発方法は、kotlin/React NativeをStripe公式がサポートしており、Flutter/Capacitorはコミュニティがプラットフォームで使うためのプラグインを開発、メンテしています。ここでは、公式がサンプルをだしているkotlinと、あと私がプラグインをつくっているCapacitorを簡単にご紹介します。

Kotlinで開発

ネイティブAndroidアプリとして開発する場合、Kotlinを使います。

公式のサンプルアプリケーションを見るのが一番の近道です。READMEには、立ち上げから決済完了までのアニメーションGIFがあるので、雰囲気を掴みやすいです。

サンプルアプリケーションは、バックエンドにRuby（Sinatra::Base）のものが用意されており、Renderでの自動デプロイまで用意されているので、すぐに試せます。決済フローはPaymentIntentで金額を確定して、そこから決済フローに入るだけというシンプルな構造になっています。

Kotlinがわかる開発者であれば、開発に苦戦することはないぐらいサンプルアプリケーションがしっかりしています。まずはこのサンプルを動かしてみて、コードを読んで理解するのがおすすめです。

Capacitor + @capacitor-community/stripe-terminal で開発

Web開発者にとっては、こちらの方が馴染みやすいかもしれません。Capacitorと@capacitor-community/stripe-terminalを使えば、Webスタックで開発できます。

実装の流れはKotlinでの開発と一緒です。PaymentIntentで金額を確定したら、TerminalConnectTypes: Handoffを指定してdiscoverReadersを実行し、返ってきたReaderで決済を実行します。

詳細はGitHubのIssueを見るとわかりやすいです。Web開発者であれば、このIssueの内容を見るだけで実装のイメージが掴めると思います。

サンプルアプリケーションは来年に作成予定です。それまでの間は、上記のIssueを参考にしながら実装を進めることになります。

まとめ

Stripe Terminal Apps on Devicesの開発を始めるには、まずDevKitの購入手続きが最優先です。営業担当者またはサポートに連絡して、DevKitの購入手続きを完了する必要があります。この手続きなしには開発を始められません。
次に、Android Studioを用意して開発環境を整備します。デバイス仕様と制約も理解しておくことが重要です。APKサイズ200MB以下、ストレージ8GB以下、Google Play Services非対応など、標準Androidとの違いを把握しておきましょう。

開発方法は、公式サンプルアプリケーションが充実しているKotlinでの開発か、Web開発者には馴染みやすいCapacitorでの開発を選択できます。日本で開発する場合は、SetupIntentが使用できないこと、Locationsの設定が特殊であること、非接触決済の制約など、地理的制約にも注意が必要です。

詳細な情報は公式ドキュメントで確認できます。
それでは、また。

Discussion