オフライン中に決済を回収するベータ
Terminal SDK を使用すると、アプリケーションではネットワーク接続がなくてもモバイルリーダーを使用して 支払いの回収を続行できます。
警告
オフラインで実行するときは、販売時に決済情報が収集され、接続の回復後にのみオーソリが試行され、支払いが転送されます。ユーザーであるお客様が取引の支払い拒否リスクのすべての責任を負います。カード発行会社がオフライン取引を拒否した場合、売上を回収する方法はなく、すでに提供した商品やサービスへの顧客の支払いを受け取れなくなることがあります。
カード発行会社による拒否を減らすため、以下のことが推奨されます。
- できる限り早急にインターネット接続を再確立して、支払いを Stripe に記録します。
- 所定の金額を超える場合は取引を制限します。
- 合計すると所定の金額を超える複数の取引を SDK が保存した場合、すべてのオフライン支払いを失敗させます。
オフライン中に決済を回収する
オフライン決済の手順は、オンライン決済と同じで、決済の作成、回収、処理、およびキャプチャーが含まれます。このプロセスのどの段階でも、デバイスをオンラインからオフラインにできます。
- オフラインモードを有効にする
- オフライン中にリーダーに接続する
- オフラインイベントを処理する
- オフライン中に PaymentIntent を作成する
- 決済手段を収集する
- 支払いを確定する
- 支払いが転送されるまで待つ
- 支払いをキャプチャーする
- オフライン支払いを調べる
オフラインモードを有効にする
To use offline mode, your application needs to consume version 3.3.0 or later of the Terminal iOS SDK.
Use a Configuration object to enable offline mode for the BBPOS Chipper 2X BT, Stripe Reader M2 or BBPOS WisePad 3 devices at your Location
.
Configuration
オブジェクトでオフラインモードを有効にすると、Location
に割り当てることができます。また、アカウントのデフォルトの Configuration
オブジェクトを更新すると、すべての Locations
でオフラインモードをデフォルトで有効にすることもできます。Configuration API を変更して SDK およびリーダーに反映させるには数分かかることがあり、有効にするには、リーダーの接続をいったん切断してから再接続する必要があります。
オフライン中にリーダーに接続する
The SDK stores necessary Location
information locally after connecting online. On subsequent offline connections, it uses the stored configuration information from that Location
.
To connect to a reader while offline, you must have previously connected to any Bluetooth reader of the same type at the same Location
while online within the last 30 days, and have updated your reader’s software within that time. If you attempt to connect to a reader while offline without meeting these requirements, the request fails with an error.
Error | Resolution |
---|---|
The SDK is not connected to the internet | Make sure the Location you’re using is configured for offline mode. Otherwise, if your Location is properly configured, your POS hasn’t previously connected to any readers while online. You should first connect to any reader while online, and then connect to a reader of the same type while offline. |
The selected reader requires a software update before it can be used to collect payments offline. | The reader’s software hasn’t been updated in 30 days or more. Connect to the reader while online to update it. |
The selected reader must be paired online at this location before it can be used to collect payments offline. | You’re attempting to connect to a reader type that your POS hasn’t previously connected to while online. You must first connect to this reader or any reader of the same type while online. Or, if you want to connect while offline, you can connect to a reader type that your POS previously connected to while online. |
アプリケーションを再インストールするか、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 のネットワーク接続がアクティブな状態にあるときにオフラインで収集された支払いは、バックグランドで転送されることにご注意ください。
決済手段を収集するクライアント側
Swiping cards isn’t supported while offline. Tapping cards is also not supported in markets where Strong Customer Authentication is required. Use the BluetoothReaderDelegate didRequestReaderInput method to display the valid card presentment options to the customer. Using the initWithUpdatePaymentIntent
parameter in CollectConfiguration
is disabled when offline mode is enabled unless the offlineBehavior
is set to REQUIRE_ONLINE
.
注
オフラインでリーダーを実行中の決済の責任をお客様が負います。磁気ストライプデータはなりすましが簡単なため、Stripe はオフラインでの実行中はこのオプションを許可していません。
支払いを確定するクライアント側
このステップは、オンライン時の支払い確定に類似しています。主要な違いは、Stripe で適用されるオフラインの上限額である 1 万ドル、または運用通貨でその相当額を超えた場合などは、オフライン固有のエラーケースを自社のシステムで処理する必要がある点です。
In some cases, the SDK might create a PaymentIntent
online, but confirm it while offline. When this happens, the PaymentIntent
might have a non-null stripeId
. You can check offlineDetails.storedAt
to determine if it was confirmed offline.
領収書の提供
オフライン時に支払いの完了に使用されたカードの情報が必要になることがあります。たとえば、購入時の領収書を求める顧客に領収書を生成する必要がある場合などです。
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 (決済手段情報) にアクセスすると、オフラインで回収されたものであるかどうかを判定できます。