💭

Stripe Terminalを実装する上での3つの注意事項

に公開
terminal
Stripe
payment
tech

9月4日、Stripeから「Stripe Terminal」の日本国内提供開始が発表されました。これにより、日本の開発者も対面決済システムを構築できるようになったのです。

しかし、実際に実装を進めると、公式ドキュメントだけでは分かりづらい重要な注意点がいくつか存在します。本記事では、日本最速でStripe Terminalのイベントでお話した内容から、最初に知っておくべき3つの重要な注意事項を詳しく解説します。

参考イベント: https://nishinomiya.connpass.com/event/368493/

1. インターネット接続対応はでかい

Stripe Terminalの日本対応端末は、インターネット接続の有無によって大きく2種類に分かれます。この違いが、実装方法と運用コストに大きな影響を与えるため、慎重に選択する必要があります。まず、対応端末を比較してみましょう。

端末名 価格（税別） インターネット接続 接続方法
Stripe Reader S700 52,480円 ✅ 対応 Wi-Fi直接接続
BBPOS Wise Pad 3 10,480円 ❌ 非対応 Bluetooth経由

価格差は約5倍もありますが、安い方を選ぶと実装が大幅に複雑化します。なぜなら、インターネット接続非対応端末は以下の制約があるからです。

実装方法の違い

インターネット接続対応端末（S700）の場合

ブラウザ経由で直接接続可能で、JavaScriptの知識があれば実装できます。

// Stripe Terminal JS SDKの例
import { loadStripeTerminal } from '@stripe/terminal-js';

const terminal = await loadStripeTerminal();
const reader = await terminal.discoverReaders({
  simulated: false,
  locationId: 'tml_xxx'
});

✅ Webアプリケーションから直接制御可能
✅ サーバ主導型の実装が可能
✅ 開発・運用が比較的簡単

インターネット接続非対応端末（BBPOS）の場合

ネイティブアプリ開発が必須になります。また、運用のためのiOSもしくはAndroidデバイスも必要になりますので、初期コストは端末以外もかかることになります。

❌ ブラウザ経由での接続不可
❌ iPhone/Androidアプリの開発が必要
❌ 開発・運用コストが大幅に増加

2. 端末は定期的な更新が必要

Stripe Terminalの端末は、セキュリティと機能向上のため定期的な更新が必須です。この更新プロセスは、端末の種類によって運用方法が大きく異なります。

必要な更新では、リーダーに接続するとインストールが開始されます。更新が完了するまでリーダーを使用できません。

https://docs.stripe.com/terminal/payments/connect-reader?terminal-sdk-platform=android&reader-type=bluetooth#optional-updates

もう少し厳密にいうと、端末の更新は「緊急の更新」と「任意の更新」に分かれます。緊急の更新は、端末がインターネットに接続した瞬間から強制的にはじまり、完了するまで端末を利用できません（インターネット接続非対応機器は、iPhoneやAndroidアプリを経由するため、アプリから端末に接続した時から開始）。

任意の更新は、端末がインターネットに接続した際に、 MobileReaderListener を通じて、任意の更新があることがわかります。更新を実行しないことは可能ですが、任意の更新は requiredAt を持っていて、それをすぎると緊急の更新と同様、強制で更新がはじまります。

更新は内容によりますが、数ヶ月更新をしていない場合、15分や20分かかることを覚悟する必要があります。

2.1. インターネット接続端末はそうはいっても気軽

インターネット接続に対応している端末は、端末がインターネットに接続した瞬間から更新がはじまります。つまり、店舗のWi-Fiに接続した瞬間から更新がはじまるため、店舗の営業時間外に更新を完了させることが可能です。

また、ベースがAndroidですので、アプリから操作しなくても、端末単体で、更新のチェックも、任意の更新のスキップも可能です。本当楽。これは覚えておいてください。本当に楽。

2.2. インターネット接続非対応端末は、更新のタイミングが難しい

インターネット接続に対応していない端末は、iPhoneやAndroidアプリを経由してインターネット接続を行います。つまり、iPhoneやAndroidアプリから端末に接続した瞬間から更新がはじまります。

iPhoneやAndroidアプリから端末に接続するタイミングはいつでしょう。そう、決済する時です。ただし、そこで緊急の更新がはじまると、お客さんを更新完了まで下手すると15分も待たせることになります。これは非常にまずい。

ですので、インターネット接続に対応していない端末を利用する場合、以下のような運用が必要になります。

  • 端末を定期的にiPhoneやAndroidアプリに接続し、更新を完了させる
  • 端末をiPhoneやAndroidアプリに接続するタイミングを決済するタイミングとは別に設ける

インターネット接続非対応端末を採用する場合は、必ずアプリに更新だけを行うためのUIを用意する必要があります。これを忘れると、更新がたまりにたまって、決済のタイミングで緊急の更新がはじまり、お客さんを長時間待たせることになります。

3. Locationに注意

Stripe Terminalは、実機を「店舗」（Location）に登録して利用します。Locationは、Stripe Dashboardから登録します。

ですが、Stripeのアカウント自体が別の国の場合、決済は失敗します。以下のエラーは、Stripeアカウントは、USで登録して、実機の店舗はNZになっている時のエラー文章です。

The reader being used to confirm this payment is registered to a Location in a country (NZ) that is not supported for this account. Please register to a Location in US. See https://stripe.com/docs/terminal/fleet/locations for more information.

また、現地通貨のみの受付しか行うことができません。
https://docs.stripe.com/terminal/payments/regional

これ以上の規制については、ドキュメント上では確認することができませんが、redditに以下のような投稿があって結論がでていない程度には、登録したLocationからどこまで動かして大丈夫かは公式ではでていません。

Stripe 端末リーダーは、アカウントの居住国でのみ機能しますか、それとも海外でも機能しますか?
https://www.reddit.com/r/stripe/comments/1cganrh/do_stripe_terminal_readers_work_only_in_the/?utm_source=chatgpt.com

国内レベルだと大丈夫だと思いますが、海外に持っていく場合は、事前にStripeサポートに確認することをお勧めします。

まとめ

Stripe Terminalは、日本国内の対面決済市場に新たな選択肢をもたらす革新的なサービスです。Stripeサービス群との連携により、従来とは異なる決済体験の提供や経営効率化が期待できます。

しかし、実装前に以下の3点を必ず検討してください：

  1. 端末選択：初期コスト vs 開発・運用コストの総合判断
  2. 更新運用：端末の更新スケジュール設計
  3. Location設定：使用地域と通貨の事前確認

これらの注意点を理解した上で実装を進めることで、スムーズなStripe Terminal導入が可能になります。

Stripe Terminalの導入を検討されている方は、まずは公式ドキュメントと併せて本記事の内容を参考に、プロジェクトの要件をご検討ください。

Discussion