支払いを回収する
注
BBPOS WisePOS E リーダーまたは Stripe リーダー S700 などのスマートリーダーの場合、支払いの回収には JavaScript SDK ではなくサーバー主導型の実装を使用することをお勧めします。サーバー主導型の実装では、LAN 通信に依存せず Stripe API を使用して支払いを回収します。JavaScript SDK および SDI はオフラインでの実行に対応していません。ニーズに合う最適なプラットフォームの選択に役立つプラットフォームの比較をご覧ください。
Stripe Terminal で支払いを回収するには、アプリケーションに支払いフローを記述する必要があります。Stripe Terminal SDK を使用して、1 つの支払いセッションを表すオブジェクトである PaymentIntent (支払いインテント) を作成して更新します。
Terminal の組み込みは支払いプロセスにおける失敗に対応できるように設計されており、支払いプロセスを複数のステップに分割し、各ステップを安全に再試行できるようになっています。
ステップ 1 では、自動または手動のどちらで支払いをキャプチャーするかを定義できます。顧客のカードのオーソリは、SDK が支払いを処理するときにステップ 3 で行われます。
PaymentIntent を作成するサーバー側
支払いを回収する最初のステップは、支払いフローを開始することです。顧客が決済フローを開始したときに、アプリケーションは PaymentIntent
オブジェクトを作成する必要があります。これは、Stripe の新しい支払いセッションを表します。
テスト金額を使用して、さまざまな結果を生成してみてください。00
で終わる金額では、支払いが承認されます。
次の例は、サーバーで PaymentIntent
を作成する方法を示しています。
Terminal の支払いでは、payment_method_types
パラメーターに card_present
が含まれている必要があります。
以下のように決済フローを制御できます。
card_present
決済の決済フローを完全に管理するには、capture_method
をmanual
に設定します。これにより、決済を確定する前に照合ステップを追加できます。- 1 ステップで支払いのオーソリとキャプチャーを行うには、
capture_method
をautomatic
に設定します。
注
カナダで Interac の支払いを受け付けるには、payment_method_types
に interac_present
も含める必要があります。詳細については、カナダ向けのドキュメントをご覧ください。
PaymentIntent には、各 PaymentIntent の一意のキーである、client secret が格納されます。client secret を使用するには、これをサーバーで PaymentIntent から入手し、クライアント側に渡す必要があります。
collectPaymentMethod
を呼び出す際に、client secret をパラメーターとして使用します。
注
支払い方法の収集に進むためにクライアント側アプリケーションで必要なものは、client_secret
だけです。
支払い方法を収集する クライアント側
PaymentIntent を作成したら、次のステップは SDK で支払い方法を収集することです。
決済手段を収集するには、アプリをリーダーに接続する必要があります。アプリが collectPaymentMethod
を呼び出した後、接続されたリーダーはカードが提示されるのを待ちます。
async () => { // clientSecret is the client_secret from the PaymentIntent you created in Step 1. const result = await terminal.collectPaymentMethod(clientSecret); if (result.error) { // Placeholder for handling result.error } else { // Placeholder for processing result.paymentIntent } }
この方法では、接続されたカードリーダーを使用して暗号化された支払い方法のデータを収集し、この暗号化されたデータをローカルの PaymentIntent に関連付けます。
注意
決済手段の収集はローカルで行われ、次のステップである支払いの処理 the paymentまで、Payment Intents API オブジェクトのオーソリまたは更新は必要ありません。
決済手段の詳細を調べる (オプション) ベータ
高度なユースケースでは、提示されたカードの決済手段の詳細を調査し、オーソリ前に自社のビジネスロジックを実行できます。
Use the update_payment_intent
parameter to attach a PaymentMethod to the server-side PaymentIntent. This data is returned in the collectPaymentMethod
response.
async () => { // clientSecret is the client_secret from the PaymentIntent you created in Step 1. const result = await terminal.collectPaymentMethod(clientSecret, { config_override: { update_payment_intent: true } }); if (result.error) { // Placeholder for handling result.error } else { const pm = result.paymentIntent.payment_method const card = pm?.card_present ?? pm?.interac_present // Placeholder for business logic on card before processing result.paymentIntent } }
注
この方法では、収集済みの暗号化された決済手段データを PaymentIntent API オブジェクトへの更新に関連付けます。次のステップである支払いの処理まで、オーソリは必要ありません。
この高度なユースケースは、Verifone P400 またはシミュレーションされた Terminal リーダーではサポートされていません。
この時点で、カードブランド、口座情報、その他の役立つデータなどの属性にアクセスできます。
注
Stripe は wallet.type
属性で示すとおり、取引でモバイルウォレットが使用されたかどうかを検出するよう試みます。ただし、カード発行会社がモバイルウォレットのリーダーによる識別に対応していない場合、この属性は自動入力されないため、正確な検出は保証されません。確認ステップでオーソリが行われた後に、Stripe はネットワークから最新の情報を取得し、wallet.type
を確実に更新します。
Cancel collection
Programmatic cancellation
JavaScript SDK で cancelCollectPaymentMethod
を呼び出すことで、決済手段の収集をキャンセルできます。
Customer-initiated cancellation
When you set enable_customer_cancellation
to true for a transaction, smart reader users see a cancel button. Tapping the cancel button cancels the active transaction.
terminal.collectPaymentMethod( clientSecret, { config_override: { enable_customer_cancellation: true } } )
イベントを処理する
注
JavaScript SDK は、ディスプレイが内蔵されている Verifone P400、BBPOS WisePOS E、Stripe リーダー S700 のみをサポートします。リーダーがイベントを表示するため、支払い方法の収集プロセスのイベントをアプリケーションがユーザーに表示する必要はありません。取引で支払い方法を消去するには、レジ担当者が赤色の X キーを押します。
支払いを確定するクライアント側
顧客から決済手段を収集できたら、次のステップでは SDK で支払いを処理します。支払いを続行する準備ができたら、ステップ 2 からの更新後の PaymentIntent
を使用して processPayment
を呼び出します。
- 支払いの手動キャプチャーでは、
processPayment
コールが成功すると、PaymentIntent
のステータスがrequires_capture
になります。 - 支払いの自動キャプチャーでは、
PaymentIntent
はsucceeded
状態に移行します。
async () => { const result = await terminal.processPayment(paymentIntent); if (result.error) { // Placeholder for handling result.error } else if (result.paymentIntent) { // Placeholder for notifying your backend to capture result.paymentIntent.id } }
警告
2 日以内に PaymentIntents
を手動でキャプチャーする必要があり、キャプチャーしなければオーソリは期限切れになり、売上は顧客にリリースされます。
失敗に対処する
支払いの処理に失敗した場合、SDK は、更新された PaymentIntent
を含むエラーを返します。アプリケーションでは、PaymentIntent
を確認してエラーの対処方法を決定する必要があります。
PaymentIntent のステータス | 意味 | 解決策 |
---|---|---|
requires_payment_method | 支払い方法が拒否されました | 同じ PaymentIntent を使用して collectPaymentMethod を再度呼び出し、別の決済手段の収集を試みます。 |
requires_confirmation | 一時的な接続の問題 | 同じ PaymentIntent を使用して、processPayment を再度呼び出し、リクエストを再試行します。 |
PaymentIntent が nil | Stripe へのリクエストがタイムアウトし、PaymentIntent のステータスが不明です | 元の PaymentIntent の処理を再試行します。新しい PaymentIntent を作成しないでください。新しく作成すると、カード保有者に複数のオーソリが発生する可能性があります。 |
タイムアウトが複数回、連続して発生する場合、接続に問題がある可能性があります。アプリがインターネットと通信できることを確認してください。
二重支払いの防止
PaymentIntent オブジェクトは、Stripe での資金移動を可能にします。1 つの取引を表すには、PaymentIntent を 1 つ使用します。
カードが (残高不足などのために) 拒否された後、同じ PaymentIntent を再利用して、顧客が別のカードで再試行できるようにします。
PaymentIntent を編集する場合、collectPaymentMethod
を呼び出して、リーダーの決済情報を更新する必要があります。
PaymentIntent を Stripe で処理するには、ステータスが requires_payment_method
ある必要があります。オーソリ済み、キャプチャー済み、キャンセル済みの PaymentIntent をリーダーで処理することはできません。
支払いをキャプチャーするサーバー側
ステップ 1 の PaymentIntent
の作成時に capture_method
を manual
として定義した場合、SDK はオーソリ済みでキャプチャーはされていない PaymentIntent
をアプリケーションに返します。オーソリとキャプチャーの違いについて、詳細を確認してください。
アプリが SDK から確定済みの PaymentIntent
を受信したら、その支払いをキャプチャーするようにアプリからバックエンドに対して通知するようにしてください。バックエンドにエンドポイントを作成し、PaymentIntent
ID を受け付け、それをキャプチャーするように Stripe API にリクエストを送信します。
capture
コールが成功すると、PaymentIntent
のステータスは succeeded
になります。
注
キャプチャーされたプラットフォーム手数料が連結アカウントに対して正確であることを確認するために、支払いを手動でキャプチャーする前にそれぞれの PaymentIntent
を調べ、必要に応じてプラットフォーム手数料を修正します。
支払いを照合する
ビジネスの支払いアクティビティーを監視するため、毎日の最後の作業としてサーバーで PaymentIntent と内部注文システムを照合することをお勧めします。
PaymentIntent のステータスが requires_capture
のままの場合、以下の 2 つの可能性があります。
顧客のカード明細上の不要なオーソリ
- 原因: ユーザーが取引の途中でアプリの決済フローを中止した
- 解決策: キャプチャーされていない PaymentIntent が、サーバーにある完了済みの注文に関連付けられていない場合は、キャンセルできます。キャンセルされた PaymentIntent は支払いの実行に使用できなくなります。
顧客からの売上回収が未完了
- 原因: 支払いをキャプチャーするようにバックエンドに通知する、アプリからのリクエストのエラー
- 解決策: キャプチャーされていない PaymentIntent が、サーバーにある完了済みの注文に関連付けられていて、その注文について他の支払い (現金による支払いなど) を受けていない場合には、この PaymentIntent をキャプチャーできます。
チップを徴収する アメリカのみ
アメリカでは、対象ユーザーは支払いのキャプチャー時にチップを徴収できます。