カード支払いを回収する
Stripe Terminal を使用したカード支払いの回収ができるように、アプリケーションとバックエンドを準備します。
注
BBPOS WisePOS E リーダーまたは Stripe Reader S700 などのスマートリーダーの場合、JavaScript SDK を使用するのではなくサーバー主導型の連携にすることをお勧めします。サーバー主導型の連携ではローカルネットワーク通信は使用せず、代わりに Stripe API を使用して支払いを回収します。プラットフォーム比較を参照して、ニーズに合ったプラットフォームをお選びください。
Stripe Terminal で支払いを回収するには、アプリケーションに決済フローを記述する必要があります。Stripe Terminal SDK を使用して、1 つの支払いセッションを表すオブジェクトである PaymentIntent (支払いインテント) を作成して更新します。
Terminal の組み込みは支払いプロセスにおける失敗に対応できるように設計されており、支払いプロセスを複数のステップに分割し、各ステップを安全に再試行できるようになっています。
- PaymentIntent を作成します。
- 決済手段を収集する支払いを自動と手動のどちらでキャプチャーするかを定義できます。
- 支払いを処理します。顧客のカードのオーソリは、SDK が支払いを処理するときに行われます。
- (オプション) 支払いをキャプチャーする
注
この実装形式は、オフラインでのカード決済に対応していません。
PaymentIntent を作成するサーバー側
支払いを回収する最初のステップは、支払いフローを開始することです。顧客がチェックアウトを開始するとき、アプリケーションは PaymentIntent
オブジェクトを作成する必要があります。これは、Stripe での新しい支払いセッションを表します。
テスト金額を使用して、さまざまな結果を生成してみてください。00
で終わる金額では、支払いが承認されます。
次の例は、サーバで PaymentIntent
を作成する方法を示しています。
Terminal の支払いでは、payment_
パラメータに card_
が含まれている必要があります。
以下のように決済フローを制御できます。
card_
支払いの支払いフローを完全に制御するには、present capture_
をmethod manual
に設定します。これにより、支払いを確定する前に照合ステップを追加できます。- 1 ステップで支払いのオーソリとキャプチャーを行うには、
capture_
をmethod automatic
に設定します。
カナダで Interac の支払いを受け付けるには payment_
に interac_
も含める必要があります。詳細については、カナダ向けのドキュメントをご覧ください。
PaymentIntent
には、個々の PaymentIntent
に固有のキーである client secret が含まれています。client secret を使用するには、これをサーバーで PaymentIntent
から取得し、クライアント側に渡す必要があります。
collectPaymentMethod を呼び出す際に、client secret をパラメーターとして使用します。
決済手段の収集に進むためにクライアント側アプリケーションで必要なものは、client_
だけです。
支払い方法を収集する クライアント側
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
に関連付けます。
支払い方法の詳細をオプションで調査する
高度なユースケースでは、提示されたカードの支払い方法の詳細を調査し、オーソリ前に自社のビジネスロジックを実行できます。
update_
パラメーターを使用して、PaymentMethod
をサーバー側の PaymentIntent
に関連付けます。このデータは、collectPaymentMethod
レスポンスで返されます。
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 } }
注
この時点で、カードブランド、口座情報、その他の役立つデータなどの属性にアクセスできます。
注
Stripe は wallet.
属性で示すとおり、取引でモバイルウォレットが使用されたかどうかを検出するよう試みます。ただし、カード発行会社がモバイルウォレットのリーダーによる識別に対応していない場合、この属性は自動入力されないため、正確な検出は保証されません。確定ステップでオーソリが行われた後に、Stripe はネットワークから最新の情報を取得し、wallet.
を確実に更新します。
収集をキャンセルする
プログラムによるキャンセル
JavaScript SDK で cancelCollectPaymentMethod を呼び出すと、決済手段の収集をキャンセルできます。
顧客によるキャンセル
取引の enable_
を true に設定すると、スマートリーダーのユーザーにキャンセルボタンが表示されます。
キャンセルボタンをタップすると、現在の取引がキャンセルされます。
terminal.collectPaymentMethod( clientSecret, { config_override: { enable_customer_cancellation: true } } )
イベントを処理する
注
JavaScript SDK は、ディスプレイが内蔵されている Verifone P400、BBPOS WisePOS E、Stripe Reader S700 のみをサポートします。リーダーがイベントを表示するため、決済手段の収集プロセスのイベントをアプリケーションからユーザーに表示する必要はありません。取引で決済手段を消去するには、レジ担当者が赤色の X キーを押します。
支払いを確定するクライアント側
顧客から決済手段を収集したら、次のステップに進み、SDK で支払いを処理します。支払いを続行する準備ができたら、ステップ 2 の更新後の PaymentIntent
を使用して processPayment
を呼び出します。
- 支払いの手動キャプチャーでは、
processPayment
コールが成功すると、PaymentIntent
のステータスがrequires_
になります。capture - 支払いの自動キャプチャーでは、
PaymentIntent
はsucceeded
状態に移行します。
注
クライアント側で必ず Terminal SDK を使用して PaymentIntents を確定してください。サーバー側での確定では PIN プロンプトなどの重要なメッセージが無視されるため、取引の失敗につながる可能性があります。
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 日以内に PaymentIntent を手動でキャプチャーする必要があり、キャプチャーしなければオーソリは期限切れになり、売上は顧客にリリースされます。
失敗に対処する
支払いの処理に失敗した場合、SDK は、更新された PaymentIntent
を含むエラーを返します。アプリケーションでは、PaymentIntent
を確認してエラーの対処方法を決定する必要があります。
PaymentIntent のステータス | 意味 | 解決策 |
---|---|---|
requires_ | 支払い方法が拒否されました | 同じ PaymentIntent を使用して collectPaymentMethod を再度呼び出し、別の決済手段の収集を試みます。 |
requires_ | 一時的な接続の問題 | 同じ PaymentIntent を指定して processPayment を再度呼び出し、リクエストを再試行します。 |
PaymentIntent が nil です | Stripe へのリクエストがタイムアウトし、PaymentIntent のステータスが不明です | 元の PaymentIntent の処理を再試行します。新しい PaymentIntent を作成しないでください。新しく作成すると、カード保有者にとって複数のオーソリとなる可能性があります。 |
タイムアウトが複数回、連続して発生する場合、接続に問題がある可能性があります。アプリがインターネットと通信できることを確認してください。
二重支払いの防止
PaymentIntent
オブジェクトは、Stripe での資金移動を可能にします。1 つの取引を表すには、PaymentIntent
を 1 つ使用します。
カードが (残高不足などのために) 拒否された後、同じ PaymentIntent
を再利用して、顧客が別のカードで再試行できるようにします。
PaymentIntent
を編集する場合は、collectPaymentMethod
を呼び出して、リーダーの支払い情報を更新する必要があります。
Stripe が処理する前に、PaymentIntent
が requires_
ステータスである必要があります。オーソリ済み、キャプチャー済み、キャンセル済みのPaymentIntent
をリーダーで処理することはできません。
支払いをキャプチャーするサーバー側
ステップ 1 の PaymentIntent
の作成時に capture_
を manual
として定義した場合、SDK はオーソリ済みでキャプチャーはされていない PaymentIntent
をアプリケーションに返します。オーソリとキャプチャーの違いについて、詳細を確認してください。
アプリが SDK から確定済みの PaymentIntent
を受信したら、その支払いをキャプチャーするようにアプリからバックエンドに対して通知するようにしてください。バックエンドにエンドポイントを作成し、PaymentIntent
ID を受け付け、それをキャプチャーするように Stripe API にリクエストを送信します。
capture
コールが成功すると、PaymentIntent
のステータスは succeeded
になります。
注
キャプチャーされたプラットフォーム手数料が連結アカウントに対して正確であることを確認するために、支払いを手動でキャプチャーする前にそれぞれの PaymentIntent
を調べ、必要に応じてプラットフォーム手数料を修正します。
支払いを照合する
ビジネスの支払いアクティビティを監視するため、毎日の最後の作業としてサーバで PaymentIntent と内部注文システムを照合することをお勧めします。
PaymentIntent
のステータスが requires_
のままの場合には、以下の 2 つの可能性があります。
顧客のカード明細上の不要なオーソリ
- 原因: ユーザーが取引の途中でアプリの決済フローを中止した
- 解決策:キャプチャーされていない
PaymentIntent
が、サーバーにある完了済みの注文に関連付けられていない場合には、キャンセルできます。キャンセルされたPaymentIntent
を使用して支払いを実行することはできません。
顧客からの売上回収が未完了
- 原因: 支払いをキャプチャーするようにバックエンドに通知する、アプリからのリクエストのエラー
- 解決策:キャプチャーされていない
PaymentIntent
が、サーバにある完了済みの注文に関連付けられており、その注文について他の支払い (現金による支払いなど) を受けていない場合には、この PaymentIntent をキャプチャーできます。
チップを徴収する アメリカのみ
アメリカでは、対象ユーザーは支払いのキャプチャー時にチップを徴収できます。