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