カード支払いを回収する

Stripe Terminal を使用したカード支払いの回収ができるように、アプリケーションとバックエンドを準備します。

Stripe Terminal で支払いを回収するには、アプリケーションに決済フローを記述する必要があります。Stripe Terminal SDK を使用して、1 つの支払いセッションを表すオブジェクトである PaymentIntent (支払いインテント) を作成して更新します。

Terminal の組み込みは支払いプロセスにおける失敗に対応できるように設計されており、支払いプロセスを複数のステップに分割し、各ステップを安全に再試行できるようになっています。

Create a PaymentIntent.
Collect a payment method. You can define whether to automatically or manually capture your payments.
Confirm the payment. Authorization on the customer’s card takes place when the SDK confirms the payment.
(オプション) 支払いをキャプチャーする

Create a PaymentIntent
クライアント側
サーバー側

The first step when collecting payments is to start the payment flow. When a customer begins checking out, your application must create a PaymentIntent object. This represents a new payment session on Stripe.

You can create a PaymentIntent on the client or server.

Use test amounts to try producing different results. An amount ending in 00 results in an approved payment.

Client-side

Create a PaymentIntent from your client:

警告

アプリが Verifone P400 に接続されている場合は、iOS SDK から PaymentIntent を作成できません。代わりに、サーバー側で PaymentIntent を作成し、SDK の Terminal.retrievePaymentIntent メソッドを使用して、アプリ内に PaymentIntent を取得する必要があります。

Server-side

You can create the PaymentIntent on your server if the information required to start a payment isn’t readily available in your app.

The following example shows how to create a PaymentIntent on your server:

For Terminal payments, the payment_method_types parameter must include card_present.

You can control the payment flow as follows:

To fully control the payment flow for card_present payments, set the capture_method to manual. This allows you to add a reconciliation step before finalizing the payment.
To authorize and capture payments in one step, set the capture_method to automatic.

To accept payments in Australia, you need to set capture_method to automatic or manual_preferred. For more details, visit our Australia documentation. To accept Interac payments in Canada, you must also include interac_present in payment_method_types. For more details, visit our Canada documentation.

The PaymentIntent contains a client secret, a key that’s unique to the individual PaymentIntent. To use the client secret, you must obtain it from the PaymentIntent on your server and pass it to the client side.

To retrieve a PaymentIntent, use the client secret to call retrievePaymentIntent.

After you retrieve the PaymentIntent, use it to call collectPaymentMethod.

支払い方法を収集する
クライアント側

After you’ve created a PaymentIntent, the next step is to collect a payment method with the SDK.

To collect a payment method, your app needs to be connected to a reader. The connected reader waits for a card to be presented after your app calls collectPaymentMethod.

PaymentViewController.swift
Swift
import UIKit
import StripeTerminal

class PaymentViewController: UIViewController, ReaderDisplayDelegate {


    // Label for displaying messages from the card reader
    let readerMessageLabel = UILabel(frame: .zero)
    var collectCancelable: Cancelable? = nil

    // ...

    // Action for a "Checkout" button
    func checkoutAction() throws {
        let params = try PaymentIntentParametersBuilder(amount: 1000, currency: "usd").build()
        Terminal.shared.createPaymentIntent(params) { createResult, createError in
            if let error = createError {
                print("createPaymentIntent failed: \(error)")
            }
            else if let paymentIntent = createResult {
                print("createPaymentIntent succeeded")
                self.collectCancelable = Terminal.shared.collectPaymentMethod(paymentIntent) { collectResult, collectError in
                    if let error = collectError {
                        print("collectPaymentMethod failed: \(error)")
                    }
                    else if let paymentIntent = collectResult {
                        print("collectPaymentMethod succeeded")
                        // ... Confirm the payment
                    }
                }
            }

        }
    }
 }

 // MARK: MobileReaderDelegate - only needed for mobile readers, this is the delegate set during connectReader

 func reader(_ reader: Reader, didRequestReaderInput inputOptions: ReaderInputOptions = []) {
     readerMessageLabel.text = Terminal.stringFromReaderInputOptions(inputOptions)
 }

 func reader(_ reader: Reader, didRequestReaderDisplayMessage displayMessage: ReaderDisplayMessage) {
     readerMessageLabel.text = Terminal.stringFromReaderDisplayMessage(displayMessage)
 }
 // MARK: ReaderDisplayDelegate

 func terminal(_ terminal: Terminal, didRequestReaderInput inputOptions: ReaderInputOptions = []) {
     readerMessageLabel.text = Terminal.stringFromReaderInputOptions(inputOptions)
 }

 func terminal(_ terminal: Terminal, didRequestReaderDisplayMessage displayMessage: ReaderDisplayMessage) {
     readerMessageLabel.text = Terminal.stringFromReaderDisplayMessage(displayMessage)
 }

This method collects encrypted payment method data using the connected card reader, and associates the encrypted data with the local PaymentIntent.

支払い方法の詳細をオプションで調査する

高度なユースケースでは、提示されたカードの支払い方法の詳細を調査し、オーソリ前に自社のビジネスロジックを実行できます。

Use the initWithUpdatePaymentIntent parameter in CollectConfiguration to attach a PaymentMethod to the server-side PaymentIntent. This data is returned in the collectPaymentMethod response.

注

This method attaches the collected encrypted payment method data with an update to the PaymentIntent object. It requires no authorization until the next step, confirm the payment.

This advanced use case isn’t supported on the Verifone P400.

After payment method collection you must authorize the payment or cancel collection within 30 seconds.

If the SDK is operating offline, the paymentMethod field isn’t present in the PaymentIntent object.

この時点で、カードブランド、口座情報、その他の役立つデータなどの属性にアクセスできます。

注

Stripe は wallet.type 属性で示すとおり、取引でモバイルウォレットが使用されたかどうかを検出するよう試みます。ただし、カード発行会社がモバイルウォレットのリーダーによる識別に対応していない場合、この属性は自動入力されないため、正確な検出は保証されません。確定ステップでオーソリが行われた後に、Stripe はネットワークから最新の情報を取得し、wallet.type を確実に更新します。

収集をキャンセルする

プログラムによるキャンセル

iOS SDK から返される Cancelable オブジェクトを使用して、支払い方法の収集をキャンセルできます。

顧客によるキャンセル

When you set setEnableCustomerCancellation to true for a transaction, smart reader users see a cancel button.

Tapping the cancel button cancels the active transaction.

イベントを処理する

When collecting a payment method using a reader like the Stripe M2, without a built-in display, your app must be able to display events from the payment method collection process to users. These events help users successfully collect payments (for example, retrying a card, trying a different card, or using a different read method).

取引が開始されると、SDK は ReaderInputOptions 値をアプリのリーダー表示ハンドラに渡し、受け入れ可能な入力の種類 (スワイプ、挿入、タップなど) を示します。アプリの決済 UI で、これらのオプションのいずれかを使用してカードを提示することを求める画面をユーザーに表示します。

取引中に、SDK がアプリに対して、アプリのリーダー表示ハンドラに ReaderDisplayMessage 値を渡すことで、ユーザーに追加のメッセージ (「カードを再試行してください」など) を表示するように要求する場合があります。このメッセージが決済 UI でユーザーに表示されることを確認してください。

注

リーダーがイベントを表示するため、支払い方法の収集プロセスのイベントをアプリケーションからユーザーに表示する必要はありません。取引の支払い方法をクリアするには、リクエストをキャンセルします。

iPhone のタッチ決済で支払いを回収する

アプリケーション側で支払い回収の準備ができると、Stripe iOS SDK がその画面を引き継いで回収プロセスを進めます。支払い方法の収集を呼び出した後は、アプリケーションが実行中のままになりますが、iPhone はカード保有者に全画面のメッセージを表示し、カードまたは NFC ベースのモバイルウォレットを提示するように求めます。カードの読み取りエラーが発生した場合は、再試行を求めるメッセージが表示されます。提示に成功すると、成功のメッセージが表示され、アプリケーションに制御が返されて支払いが確定されます。

支払いの回収

支払いを確定する
クライアント側

After successfully collecting a payment method from the customer, the next step is to confirm the payment with the SDK. When you’re ready to proceed with the payment, call confirmPaymentIntent with the updated PaymentIntent from Step 2.

支払いの手動キャプチャーでは、confirmPaymentIntent コールが成功すると、PaymentIntent のステータスが requires_capture になります。
支払いの自動キャプチャーでは、PaymentIntent は succeeded 状態に移行します。

PaymentViewController.swift
Swift
// Action for a "Checkout" button
func checkoutAction() throws {
  let params = try PaymentIntentParametersBuilder(amount: 1000, currency: "usd").build()
  Terminal.shared.createPaymentIntent(params) { createResult, createError in
      if let error = createError {
          print("createPaymentIntent failed: \(error)")
      } else if let paymentIntent = createResult {
          print("createPaymentIntent succeeded")
          self.collectCancelable = Terminal.shared.collectPaymentMethod(paymentIntent) { collectResult, collectError in
              if let error = collectError {
                  print("collectPaymentMethod failed: \(error)")
              } else if let collectPaymentMethodPaymentIntent = collectResult {
                  print("collectPaymentMethod succeeded")
                  // ... Confirm the payment
                  self.confirmCancelable = Terminal.shared.confirmPaymentIntent(collectPaymentMethodPaymentIntent) { confirmResult, confirmError in
                      if let error = confirmError {
                          print("confirmPaymentIntent failed: \(error)")
                      } else if let confirmedPaymentIntent = confirmResult {
                          print("confirmPaymentIntent succeeded")
                          // Notify your backend to capture the PaymentIntent
                          if let stripeId = confirmedPaymentIntent.stripeId {
                              APIClient.shared.capturePaymentIntent(stripeId) { captureError in
                                  if let error = captureError {
                                      print("capture failed: \(error)")
                                  } else {
                                      print("capture succeeded")
                                  }
                              }
                          } else {
                              print("Payment collected offline");
                          }
                      }
                  }
              }
          }
      }
  }

警告

You must manually capture a PaymentIntent within 2 days or the authorization expires and funds are released to the customer.

失敗に対処する

支払いの確定に失敗した場合、SDK は、更新された PaymentIntent を含むエラーを返します。アプリケーションでは、PaymentIntent を確認してエラーの対処方法を決定する必要があります。

PaymentIntent のステータス	意味	解決策
`requires_payment_method`	支払い方法が拒否されました	Try collecting a different payment method by calling `collectPaymentMethod` again with the same `PaymentIntent`.
`requires_confirmation`	一時的な接続の問題	Call `confirmPaymentIntent` again with the same `PaymentIntent` to retry the request.
`PaymentIntent` is `nil`	Request to Stripe timed out, unknown `PaymentIntent` status	Retry confirming the original `PaymentIntent`. Don’t create a new one, because that could result in multiple authorizations for the cardholder.

タイムアウトが複数回、連続して発生する場合、接続に問題がある可能性があります。アプリがインターネットと通信できることを確認してください。

二重支払いの防止

The PaymentIntent object enables money movement at Stripe—use a single PaymentIntent to represent a transaction.

Re-use the same PaymentIntent after a card is declined (for example, if it has insufficient funds), so your customer can try again with a different card.

If you edit the PaymentIntent, you must call collectPaymentMethod to update the payment information on the reader.

A PaymentIntent must be in the requires_payment_method state before Stripe can confirm it. An authorized, captured, or canceled PaymentIntent can’t be confirmed by a reader.

支払いをキャプチャーする
サーバー側

ステップ 1 の PaymentIntent の作成時に capture_method を manual として定義した場合、SDK はオーソリ済みでキャプチャーはされていない PaymentIntent をアプリケーションに返します。オーソリとキャプチャーの違いについて、詳細を確認してください。

アプリが SDK から確定済みの PaymentIntent を受信したら、その支払いをキャプチャーするようにアプリからバックエンドに対して通知するようにしてください。バックエンドにエンドポイントを作成し、PaymentIntent ID を受け付け、それをキャプチャーするように Stripe API にリクエストを送信します。

capture コールが成功すると、PaymentIntent のステータスは succeeded になります。

注

To make sure the application fee captured is correct for connected accounts, inspect each PaymentIntent and modify the application fee, if needed, before manually capturing the payment.

支払いを照合する

To monitor the payments activity of your business, you might want to reconcile PaymentIntents with your internal orders system on your server at the end of a day’s activity.

A PaymentIntent that retains a requires_capture status might represent two things:

顧客のカード明細上の不要なオーソリ

原因: ユーザーが取引の途中でアプリの決済フローを中止した
Solution: If the uncaptured PaymentIntent isn’t associated with a completed order on your server, you can cancel it. You can’t use a canceled PaymentIntent to perform charges.

顧客からの売上回収が未完了

原因: 支払いをキャプチャーするようにバックエンドに通知する、アプリからのリクエストのエラー
Solution: If the uncaptured PaymentIntent is associated with a completed order on your server, and no other payment has been taken for the order (for example, a cash payment), you can capture it.

チップを徴収するアメリカのみ

アメリカでは、対象ユーザーは支払いのキャプチャー時にチップを徴収できます。