カード支払いを回収する

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:

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
        }
    }
)

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:

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

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.

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

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

After you retrieve the PaymentIntent, use it to call 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
        }
    }
)

After you’ve created a PaymentIntent, the next step is to collect a payment method with the 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
        }
    }
)

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

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

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

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

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 オブジェクトを使用して、支払い方法の収集をキャンセルできます。

顧客によるキャンセル

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

Tapping the cancel button cancels the active transaction.

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(),
)

イベントを処理する

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

取引が開始されると、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 ベースのモバイルウォレットを提示するように求めます。カードの読み取りエラーが発生した場合は、再試行を求めるメッセージが表示されます。提示に成功すると、成功のメッセージが表示され、アプリケーションに制御が返されて支払いが確定されます。

支払いの回収

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 状態に移行します。

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 を確認してエラーの対処方法を決定する必要があります。

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

二重支払いの防止

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 にリクエストを送信します。

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

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

支払いを照合する

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.

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

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