オフラインでカード支払いを回収する
インターネット接続の問題が生じているときにカード支払いを回収します。
Terminal SDK を使用すると、アプリケーションではネットワーク接続なしで、モバイルリーダーを使用して支払いの回収を続行できます。
よくある間違い
オフラインで実行するときは、販売時に決済情報が収集されます。オーソリは接続の回復後にのみ試行され、支払いが転送されます。ユーザーであるお客様が、オフライン取引に関連する支払い拒否や改ざんに関するすべてのリスクを負います。改ざんされたリーダーが支払いを Stripe に転送できない場合、またはカード発行会社が取引を拒否した場合、売上を回収する方法はなく、すでに提供した商品やサービスへの顧客の支払いを受け取れなくなることがあります。
カード発行会社による拒否を減らすため、以下のことが推奨されます。
- できる限り早急にインターネット接続を再確立して、支払いを Stripe に記録します。
- 所定の金額を超える場合は取引を制限します。
- 合計すると所定の金額を超える複数の取引を SDK が保存した場合、すべてのオフライン決済を失敗させます。
オフライン中に決済を回収する
オフライン決済の手順は、オンライン決済と同じで、決済の作成、回収、処理、およびキャプチャーが含まれます。このプロセスのどの段階でも、デバイスをオンラインからオフラインにできます。
- オフラインモードを有効にする
- オフライン中にリーダーに接続する
- オフラインイベントを処理する
- オフライン中に PaymentIntent を作成する
- 支払い方法を収集する
- 支払いを確定する
- 支払いが転送されるまで待つ
- (オプション) 支払いをキャプチャーする
- (オプション) オフラインで回収した支払いを調べる
オフラインモードを有効にする
オフラインモードを使用するには、アプリケーションが Terminal iOS SDK のバージョン 3.
以降を使用している必要があります。
Configuration オブジェクトまたはダッシュボードを使用して、Location
でサポートされているデバイスのオフラインモードを有効にします。
Configuration
オブジェクトでオフラインモードを有効にすると、Location
に割り当てることができます。また、アカウントのデフォルトの Configuration
オブジェクトを更新すると、すべての Locations
でオフラインモードをデフォルトで有効にすることもできます。Configuration API の変更が SDK とリーダーに反映されるまで数分かかる場合があり、反映するには、リーダーの接続をいったん切断してから再接続する必要があります。
オフライン中にリーダーに接続する
SDK はオンラインに接続した後、必要な Location
情報をローカルに保存します。後続のオフライン接続では、その Location
に保存されている設定情報が使用されます。
オフライン時にスマートリーダーで支払いを回収するには、直前の 30 日以内のオンライン時に、あらかじめ同じ Location
の同じタイプのモバイルリーダーに接続し、また期間内にリーダーのソフトウェアを更新する必要があります。
オフライン時にこれらの要件を満たさずリーダーに接続しようとすると、リクエストはエラーで失敗します。
エラー | 解決策 |
---|---|
SDK がインターネットに接続されていません | 使用している Location がオフラインモード用に設定されていることを確認します。それ以外の場合は、オンライン時に任意のリーダーに接続してから、オフライン時に同じタイプのリーダーに接続します。 |
選択したリーダーをオフラインでの支払い回収に使用するには、ソフトウェアの更新が必要です。 | リーダーのソフトウェアが 30 日以上更新されていません。オンライン時にリーダーに接続して更新してください。 |
選択したリーダーをオフラインでの支払い回収に使用するには、この場所でオンラインのペアリングを行う必要があります。 | POS がこれまでオンライン中に接続していないタイプのリーダーに接続しようとしています。まずオンライン中に、このリーダーまたは同じタイプのリーダーに接続する必要があります。または、オフライン中に接続する場合は、以前オンライン中に POS が接続していたタイプのリーダーに接続できます。 |
アプリケーションを再インストールしたり、SDK のディスクストレージを消去する操作 (POS デバイス設定での POS アプリのキャッシュの消去など) を実行すると、SDK が保存している未転送の支払いがすべて失われます。破壊的なアクションを実行する前に、保存された決済がないことを確認してください。
オフラインイベントを処理するクライアント側
アプリケーションが SDK のネットワークステータスと転送された支払いの状態に関する更新を受信できるようにするには、OfflineDelegate
プロトコルを実装して Terminal SDK に渡します。オフラインで支払いを回収する前に、OfflineDelegate
を設定する必要があります。
オフライン中に PaymentIntent を作成するクライアント側
オフラインでの操作に対応するには、SDK の createPaymentIntent
を使用して PaymentIntent オブジェクトを作成します。これにより、SDK はオフライン時に PaymentIntents を作成し、接続が再確立された後で Stripe に転送できます。
オフラインでの実行中、PaymentIntent
オブジェクトは null の stripeId
を保持します。PaymentIntent のメタデータにカスタム識別子を追加して、オフラインで作成された PaymentIntent
オブジェクトをデータベースで照合できるようにすることをお勧めします。
ステップ 7 で PaymentIntent
が正常に Stripe に転送されたら、カスタム識別子を使用して OfflineDelegate.
コールバックで調整します。
Terminal.
は CreateConfiguration
パラメーターを受け付けます。デフォルトでは、オフラインで実行している場合、Terminal SDK はすべてのオフライン決済を保存し、接続が回復したときに Stripe のバックエンドに転送します。
この動作をカスタマイズするには、offlineBehavior
属性を REQUIRE_
、PREFER_
または FORCE_
に設定して CreateConfiguration
オブジェクトを渡すことができます。
リスクの管理
offlineBehavior
を REQUIRE_
に設定すると、現在の取引はオフラインでの操作時に失敗します。たとえば、一定の金額を越える取引を拒否したり、SDK に合計額が一定の金額を超える複数の取引が保存されている場合に、すべてのオフライン取引を拒否したりすることができます。
SDK では、リスクを管理しやすいように、次の 2 つのプロパティーを公開しています。
Terminal.
offlineStatus. sdk. offlinePaymentsCount Terminal.
offlineStatus. sdk. offlinePaymentAmountsByCurrency
オフライン時の遅延管理
Terminal SDK は、ネットワークの接続状態に基づき、支払いをオンラインとオフラインのどちらで回収すべきかを自動的に判断します。ただし、ネットワーク接続がアクティブな場合でも、オフラインでの操作が必要になることがあります (たとえば、取引を素早く収集する必要があり、ネットワーク接続が遅い場合など)。offlineBehavior
を FORCE_
に設定して CreateConfiguration
オブジェクトを渡すと、接続状態に関係なく支払いをオフラインで回収できます。
Terminal SDK のネットワーク接続がアクティブな状態にあるときにオフラインで回収された支払いは、バックグラウンドで転送されます。
支払い方法を収集するクライアント側
注
オフラインでリーダーを実行する間は、決済の責任をお客様が負うことになります。磁気ストライプデータはなりすましが簡単なため、Stripe はオフラインでの実行中はこのオプションを許可していません。強力な顧客認証 (SCA) が要求される市場では、カードのタップもサポートされていません。
オフラインでの支払いの回収は、オンラインでの支払いの回収と似ています。didRequestReaderInput
メソッドを使用して、有効なカード提示オプションを顧客に表示します。
注
承認前に決済手段の詳細を調査する機能は、オフラインではサポートされていません。CollectConfiguration
で initWithUpdatePaymentIntent
パラメーターを引き続き使用できますが、SDK がオフラインで実行されている場合、PaymentIntent の paymentMethod
フィールドは表示されません。
支払いを確定するクライアント側
オフラインでの支払いの確定は、オンラインでの支払いの確定と似ています。主な違いは、Stripe が適用するオフライン取引の上限額である 1 万 USD、または運用通貨で相当する額を超えた場合などは、オフライン固有のエラーケースを自社のシステムで処理する必要がある点です。
場合によっては、SDK がオンラインで PaymentIntent
を作成し、オフラインで確定することがあります。これが発生すると、PaymentIntent
に null 以外の stripeId
が含まれる可能性があります。オフラインで確定された場合は、offlineDetails
が定義され、入力されます。
領収書の提供
オフライン時に支払いの完了に使用されたカードの情報が必要になることがあります。たとえば、購入時の領収書を求める顧客に領収書を生成する必要がある場合などです。
PaymentIntent がオフラインで確定された場合、その OfflineCardPresentDetails、 を paymentIntent.
から取得できます。
このハッシュには、領収書の生成に使用される ReceiptDetails、 プロパティのほか、カード保有者の名前やカードブランドなどのカード情報が含まれます。
オフラインで処理された PaymentIntents では、account_
および authorization_
の領収書フィールドを使用できません。構築済みのメール領収書は接続が回復し、支払いのキャプチャーが成功するまで送信されません。
支払いが転送されるまで待つクライアント側
インターネットアクセスが復旧すると、SDK は保存されていたオフラインの支払いの転送を自動的に開始します。
SDK は、ネットワークステータスがオフラインであっても支払いの転送を試みます。つまり、デバイスがオフラインの場合でも、接続トークンプロバイダーは、接続トークンの提供を求めるリクエストを受け取る可能性があります。
POS デバイスの電源オフのタイミングが早すぎると、支払いが転送されない可能性があります。Terminal.
をクエリすると、POS がオンライン状態にあり、支払いを転送できるか確認することができます。また、Terminal.
をクエリすると、Terminal SDK の転送が必要な支払いの件数を確認できます。
決済をキャプチャーする
オフライン時には、captureMethod
を automatic
に設定して、PaymentIntents を作成できます。
これらの PaymentIntent を確定すると、ステータスは RequiresCapture
ではなく、Succeeded
になります。Stripe は転送後の支払いを自動的にキャプチャーします。
手動キャプチャーを選択した場合、正常に転送されオーソリされた支払いは、バックエンドまたはアプリケーションからキャプチャーする必要があります。
- バックエンドから支払いをキャプチャーするには、Webhook を使用して、
requires_
ステータスの PaymentIntents をリッスンします。capture - アプリケーションから支払いをキャプチャーするには、 SDK が各 PaymentIntent を転送するたびに、
OfflineDelegate.
のコールをアプリケーションが受け取るのを待ちます。PaymentIntent のステータスがdidForwardPayment RequiresCapture
であり、さらにofflineDetails
が null、あるいはrequiresUpload
value ofNO
の場合、キャプチャーする準備ができています。
オフライン決済は、 SDK によって OfflineDelegate の didForwardPaymentIntent
で転送された後にキャプチャーします。
オフラインで回収した支払いを調べる
オーソリ後は、PaymentIntents API を使用して支払いのオフライン情報を調べることができます。PaymentIntent
の最新の Charge オブジェクトの payment method details にアクセスすると、オフラインで回収されたものであるかどうかを判定できます。