カード支払いを回収する

支払いを回収する最初のステップは、支払いフローを開始することです。顧客がチェックアウトを開始するとき、アプリケーションは PaymentIntent オブジェクトを作成する必要があります。これは、Stripe での新しい支払いセッションを表します。

クライアント側またはサーバー側で PaymentIntent を作成できます。

テスト金額を使用して、さまざまな結果を生成してみてください。00 で終わる金額では、支払いが承認されます。

クライアント側

クライアントから PaymentIntent を作成します。

val params = PaymentIntentParameters.Builder()
    .setAmount(1000)
    .setCurrency("usd")
    .build()
Terminal.getInstance().createPaymentIntent(
    params,
    object : PaymentIntentCallback {
        override fun onSuccess(paymentIntent: PaymentIntent) {
            // Placeholder for handling successful operation
        }

        override fun onFailure(e: TerminalException) {
            // Placeholder for handling exception
        }
    }
)

サーバー側

支払いの開始に必要な情報がアプリですぐに利用できない場合は、サーバで PaymentIntent を作成することができます。

次の例は、サーバで PaymentIntent を作成する方法を示しています。

curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "amount"=1000 \
  -d "currency"="usd" \
  -d "payment_method_types[]"="card_present" \
  -d "capture_method"="manual"

Terminal の支払いでは、payment_method_types パラメータに card_present が含まれている必要があります。

以下のように決済フローを制御できます。

• card_present 支払いの支払いフローを完全に制御するには、capture_method を manual に設定します。これにより、支払いを確定する前に照合ステップを追加できます。
• 1 ステップで支払いのオーソリとキャプチャーを行うには、capture_method を automatic に設定します。

オーストラリアで決済を受け付けるには、capture_method を automatic または manual_preferred に設定する必要があります。詳細については、オーストラリア向けのドキュメントをご覧ください。カナダで Interac の支払いを受け付けるには payment_method_types に interac_present も含める必要があります。詳細については、カナダ向けのドキュメントをご覧ください。

PaymentIntent には、個々の PaymentIntent に固有のキーである client secret が含まれています。client secret を使用するには、これをサーバーで PaymentIntent から取得し、クライアント側に渡す必要があります。

post '/create_payment_intent' do
  intent = # ... Create or retrieve the PaymentIntent
  {client_secret: intent.client_secret}.to_json
end

PaymentIntent を取得するには、client secret を使用して retrievePaymentIntent を呼び出します。

PaymentIntent を取得したら、それを使用して collectPaymentMethod を呼び出します。

Terminal.getInstance().retrievePaymentIntent(
    clientSecret,
    object : PaymentIntentCallback {
        override fun onSuccess(paymentIntent: PaymentIntent) {
            // Placeholder for handling successful operation
        }

        override fun onFailure(e: TerminalException) {
            // Placeholder for handling exception
        }
    }
)

PaymentIntent を作成したら、次のステップは SDK で決済手段を収集することです。

決済手段を収集するには、アプリをリーダーに接続する必要があります。アプリが collectPaymentMethod を呼び出した後、接続されたリーダーはカードの提示を待ち受けます。

val cancelable = Terminal.getInstance().collectPaymentMethod(
    paymentIntent,
    object : PaymentIntentCallback {
        override fun onSuccess(paymentIntent: PaymentIntent) {
            // Placeholder for handling successful operation
        }

        override fun onFailure(e: TerminalException) {
            // Placeholder for handling exception
        }
    }
)

この方法では、接続されたカードリーダーを使用して暗号化された決済手段のデータを収集し、その暗号化されたデータをローカルの PaymentIntent に関連付けます。

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

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

CollectConfiguration で updatePaymentIntent パラメーターを使用し、PaymentMethod をサーバー側の PaymentIntent に関連付けます。このデータは、collectPaymentMethod レスポンスで返されます。

val collectConfig = CollectConfiguration.Builder()
    .updatePaymentIntent(true)
    .build()

val cancelable = Terminal.getInstance().collectPaymentMethod(paymentIntent,
    object : PaymentIntentCallback {
        override fun onSuccess(paymentIntent: PaymentIntent) {
            val pm = paymentIntent.paymentMethod
            val card = pm?.cardPresentDetails ?: pm?.interacPresentDetails

            // Placeholder for business logic on card before confirming paymentIntent
        }

        override fun onFailure(e: TerminalException) {
            // Placeholder for handling exception
        }
    }
)

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

収集をキャンセルする

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

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

顧客によるキャンセル

取引の setEnableCustomerCancellation を true に設定すると、スマートリーダーのユーザーにキャンセルボタンが表示されます。

キャンセルボタンをタップすると、現在の取引がキャンセルされます。

Terminal.getInstance().collectPaymentMethod(
    paymentIntent,
    object : PaymentIntentCallback {
        override fun onSuccess(paymentIntent: PaymentIntent) {
            // Placeholder for handling successful operation
        }

        override fun onFailure(e: TerminalException) {
            // Placeholder for handling exception
        }
    },
    CollectConfiguration.Builder()
        .setEnableCustomerCancellation(true)
        .build(),
)

イベントを処理する

内蔵ディスプレイのない Stripe M2 などのリーダーを使用して決済手段を収集するときは、アプリが決済手段の収集プロセスのイベントをユーザーに表示できるようにする必要があります。これらのイベントは、ユーザーが支払いを正常に回収するのに役立ちます (カードを再試行する、別のカードを試す、別の読み取り方法を使用するなど)。

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

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

class ReaderActivity : AppCompatActivity(), MobileReaderListener {
    // ...

    override fun onRequestReaderInput(options: ReaderInputOptions) {
        Toast.makeText(activity, options.toString(), Toast.LENGTH_SHORT).show()
    }

    override fun onRequestReaderDisplayMessage(message: ReaderDisplayMessage) {
        Toast.makeText(activity, message.toString(), Toast.LENGTH_SHORT).show()
    }

    // ...
}

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

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

支払いの回収

顧客から決済手段を収集したら、次のステップに進み、SDK で支払いを確定します。支払いを続行する準備ができたら、ステップ 2 の更新後の PaymentIntent を使用して confirmPaymentIntent を呼び出します。

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

val cancelable = Terminal.getInstance().confirmPaymentIntent(
    paymentIntent,
    object : PaymentIntentCallback {
        override fun onSuccess(paymentIntent: PaymentIntent) {
            // Placeholder handling successful operation
        }

        override fun onFailure(e: TerminalException) {
            // Placeholder for handling exception
        }
    }
)

失敗に対処する

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

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

二重支払いの防止

PaymentIntent オブジェクトは、Stripe での資金移動を可能にします。1 つの取引を表すには、PaymentIntent を 1 つ使用します。

カードが (残高不足などのために) 拒否された後、同じ PaymentIntent を再利用して、顧客が別のカードで再試行できるようにします。

PaymentIntent を編集する場合は、collectPaymentMethod を呼び出して、リーダーの支払い情報を更新する必要があります。

Stripe が確定する前に、PaymentIntent が requires_payment_methodステータスである必要があります。オーソリ済み、キャプチャー済み、キャンセル済みのPaymentIntent をリーダーで確定することはできません。

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

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

curl -X POST https://api.stripe.com/v1/payment_intents/{{PAYMENT_INTENT_ID}}/capture \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

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

支払いを照合する

ビジネスの支払いアクティビティを監視するため、毎日の最後の作業としてサーバで PaymentIntent と内部注文システムを照合することをお勧めします。

PaymentIntent のステータスが requires_capture のままの場合には、以下の 2 つの可能性があります。

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

• 原因: ユーザーが取引の途中でアプリの決済フローを中止した
• 解決策:キャプチャーされていない PaymentIntent が、サーバーにある完了済みの注文に関連付けられていない場合には、キャンセルできます。キャンセルされた PaymentIntent を使用して支払いを実行することはできません。

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

• 原因: 支払いをキャプチャーするようにバックエンドに通知する、アプリからのリクエストのエラー
• 解決策:キャプチャーされていない PaymentIntent が、サーバにある完了済みの注文に関連付けられており、その注文について他の支払い (現金による支払いなど) を受けていない場合には、この PaymentIntent をキャプチャーできます。

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

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