Customer Sheet を導入する

顧客がアプリの設定で保存済みの決済手段を管理できるようにします。

iOS

Android

React Native

注

The Payment Method Settings Sheet is intended for use on an app settings page. For checkout and payments, use the In-app Payments, which also has built-in support for saving and displaying payment methods and supports more payment methods than the Payment Method Settings Sheet.

注

In code, this component is referenced as CustomerSheet for historical reasons. Throughout the documentation, when you see CustomerSheet in code examples, this refers to the Payment Method Settings Sheet.

The Payment Method Settings Sheet is a prebuilt UI component that lets your customers manage their saved payment methods. You can use the Payment Method Settings Sheet UI outside of a checkout flow, and the appearance and styling is customizable to match the appearance and aesthetic of your app. Customers can add and remove payment methods, which get saved to the customer object, and set their default payment method stored locally on the device. Use both the In-app Payments and the Payment Method Settings Sheet to provide customers a consistent end-to-end solution for saved payment methods.

Screenshot of Payment Method Settings Sheet presenting multiple saved payment methods in an Android app.

Stripe を設定する

まず、Stripe アカウントが必要です。今すぐ登録してください。

SDK をインストールするには、app/build.gradle ファイルの dependencies ブロックに stripe-android を追加します。

注

SDK の最新リリースおよび過去バージョンの詳細については、GitHub の Releases ページをご覧ください。新しいリリースの公開時に通知を受け取るには、リポジトリのリリースを確認してください。

Stripe の公開可能キーを使用して SDK を設定し、 Application サブクラスなどで、Stripe API へのリクエストを実行できるようにします。

注

テストおよび開発時にはテストキーを使用し、アプリの公開時には本番環境キーを使用します。

決済手段を有効にする

支払い方法の設定を表示して、サポートする支払い方法を有効にします。SetupIntent を作成するには、少なくとも 1 つは支払い方法を有効にする必要があります。

多くの顧客から決済を受け付けられるよう、Stripe では、カードやその他一般的な決済手段がデフォルトで有効になっていますが、ビジネスや顧客に適した追加の決済手段を有効にすることをお勧めします。プロダクトと決済手段のサポートについては決済手段のサポートを、手数料については料金体系ページをご覧ください。

注

At this time, Payment Method Settings Sheet only supports cards and US bank accounts.

Customer エンドポイントを追加する
サーバー側

サーバー側で、Customer の一時キーを取得するエンドポイントと、新しい決済手段を Customer に保存する SetupIntent を作成するエンドポイントの 2 つのエンドポイントを作成します。

Customer ID と関連する一時キーを返すエンドポイントを作成します。SDK で使用される API バージョンは、こちらで確認できます。

Customer ID を指定して設定された SetupIntent を返すエンドポイントを作成します。

今後の支払いで、顧客が決済フローでオンセッション時にのみ決済手段を使用する場合、usage パラメーターを on_session に設定して、オーソリ率を改善します。

Customer アダプターを作成する
クライアント側

CustomerSheet は StripeCustomerAdapter を使用することで Stripe と通信できます。クライアント側で、CustomerAdapter を設定して、サーバー上のこれらのエンドポイントに対するリクエストを行います。

CheckoutViewModel.kt
import android.app.Application
import androidx.lifecycle.AndroidViewModel
import com.stripe.android.customersheet.CustomerAdapter
import com.stripe.android.customersheet.ExperimentalCustomerSheetApi

@OptIn(ExperimentalCustomerSheetApi::class)
class CheckoutViewModel(
    application: Application
) : AndroidViewModel(application) {
    val customerAdapter = CustomerAdapter.create(
        context = getApplication(),
        customerEphemeralKeyProvider = {
            myBackend.getEphemeralKey().fold(
                onSuccess = { response ->
                    CustomerAdapter.Result.success(
                        CustomerEphemeralKey.create(
                            customerId = response.customerId,
                            ephemeralKey = response.ephemeralKeySecret,
                        )
                    )
                },
                onFailure = { exception ->
                    CustomerAdapter.Result.failure(
                        cause = exception,
                        displayMessage = "We couldn't retrieve your information, please try again.",
                    )
                }
            )
        },
        setupIntentClientSecretProvider = { customerId ->
            myBackend.createSetupIntent(customerId).fold(
                onSuccess = { response ->
                    CustomerAdapter.Result.success(
                        response.setupIntentClientSecret,
                    )
                },
                onFailure = { exception ->
                    CustomerAdapter.Result.failure(
                        cause = exception,
                        displayMessage = "We couldn't retrieve your information, please try again.",
                    )
                }
            )
        }
    )
}

画面を設定する

Next, initialize the Payment Method Settings Sheet using the CustomerSheet class with your CustomerAdapter then call configure with a CustomerSheet.Configuration. Always call configure before calling present and retrievePaymentOptionSelection.

CheckoutActivity.kt
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.viewModels
import com.stripe.android.customersheet.CustomerSheet
import com.stripe.android.customersheet.ExperimentalCustomerSheetApi
import com.stripe.android.customersheet.rememberCustomerSheet

@OptIn(ExperimentalCustomerSheetApi::class)
class CheckoutActivity : ComponentActivity() {
    private val viewModel by viewModels<CheckoutViewModel>()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val configuration = CustomerSheet.Configuration.builder(merchantDisplayName = "{{YOUR BUSINESS NAME}}")
            .build()

        setContent {
            val customerSheet = rememberCustomerSheet(
                customerAdapter = viewModel.customerAdapter,
                callback = viewModel::handleResult // Implemented in next step
            )

            LaunchedEffect(customerSheet) {
                customerSheet.configure(configuration = configuration)
            }
        }
    }
}

画面を表示する

Present the Payment Method Settings Sheet using CustomerSheet. When the customer dismisses the sheet, the CustomerSheet calls the completion block with a CustomerSheetResult.

CheckoutActivity.kt
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.viewModels
import androidx.compose.foundation.Image
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.material.Text
import androidx.compose.material.TextButton
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import com.stripe.android.customersheet.CustomerSheet
import com.stripe.android.customersheet.ExperimentalCustomerSheetApi
import com.stripe.android.customersheet.rememberCustomerSheet
import com.stripe.android.uicore.image.rememberDrawablePainter

@OptIn(ExperimentalCustomerSheetApi::class)
class CheckoutActivity : ComponentActivity() {
    private val viewModel by viewModels<CheckoutViewModel>()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val configuration = CustomerSheet.Configuration.builder(merchantDisplayName = "{{YOUR BUSINESS NAME}}")
            .headerTextForSelectionScreen("Manage your payment method")
            .build()

        setContent {
            val customerSheet = rememberCustomerSheet(
                customerAdapter = viewModel.customerAdapter,
                callback = viewModel::handleResult
            )

            LaunchedEffect(customerSheet) {
                customerSheet.configure(configuration = configuration)
                viewModel.handleResult(customerSheet.retrievePaymentOptionSelection())
            }

            val paymentOption by viewModel.paymentOption.collectAsState()

            Row(
                modifier = Modifier.fillMaxWidth(),
                verticalAlignment = Alignment.CenterVertically,
                horizontalArrangement = Arrangement.SpaceBetween,
            ) {
                val icon = paymentOption?.icon()

                if (icon != null) {
                    Image(
                        painter = rememberDrawablePainter(
                            drawable = icon
                        ),
                        contentDescription = "Payment Method Icon",
                        modifier = Modifier.height(32.dp)
                    )
                }
                TextButton(
                    onClick = {
                        customerSheet.present()
                    }
                ) {
                    Text(
                        text = paymentOption?.label ?: "Select"
                    )
                }
            }
        }
    }
}

CheckoutViewModel.kt
import android.app.Application
import androidx.lifecycle.AndroidViewModel
import com.stripe.android.customersheet.CustomerAdapter
import com.stripe.android.customersheet.CustomerEphemeralKey
import com.stripe.android.customersheet.CustomerSheetResult
import com.stripe.android.customersheet.ExperimentalCustomerSheetApi
import com.stripe.android.paymentsheet.model.PaymentOption
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.update

@OptIn(ExperimentalCustomerSheetApi::class)
class CheckoutViewModel(
    application: Application
) : AndroidViewModel(application) {
    val customerAdapter = // ...

    private val _paymentOption = MutableStateFlow<PaymentOption?>(null)
    val paymentOption: StateFlow<PaymentOption?> = _paymentOption

    fun handleResult(result: CustomerSheetResult) {
        when (result) {
            is CustomerSheetResult.Selected -> {
                // Configure your UI based on the payment option
                _paymentOption.update {
                    result.selection?.paymentOption
                }
            }
            is CustomerSheetResult.Canceled -> {
                // Configure your UI based on the payment option
                _paymentOption.update {
                    result.selection?.paymentOption
                }
            }
            is CustomerSheetResult.Failed -> {
                // Show the error in your UI
            }
        }
    }
}

顧客が支払い方法を選択する場合、その結果は、CustomerSheetResult.Selected になります。関連付けられる値は、選択された PaymentOptionSelection になるか、ユーザーが過去に選択した支払い方法を削除した場合は null になります。支払い方法の詳細は、PaymentOptionSelection の paymentMethod 値で確認できます。
顧客が画面をキャンセルした場合、その結果は CustomerSheetResult.Canceled になります。関連付けられる値は、顧客の元の PaymentOptionSelection であるか、顧客が以前に決済手段を選択していない場合や、最初に選択した決済手段を削除している場合は null になります。
エラーが発生した場合、その結果は CustomerSheetResult.Failed になります。

オプションGoogle Pay を有効にする

実装方法を設定する

Google Pay を使用するには、まず以下を AndroidManifest.xml の <application> に追加し、Google Pay API を有効化します。

AndroidManifest.xml
<application>
  ...
  <meta-data
    android:name="com.google.android.gms.wallet.api.enabled"
    android:value="true" />
</application>

詳細は、Google Pay の Android 向け Google Pay API を設定するを参照してください。

Google Pay を追加する

連携に Google Pay を追加するには、CustomerSheet.Configuration を CustomerSheet.Configuration.Builder で初期化する際に、googlePayEnabled に true を渡します。

オプションACH 決済を有効にする

ACH デビット決済を有効にするには、アプリの依存関係として Financial Connections を指定します。

Stripe Android SDK はオープンソースであり、詳細なドキュメントが提供されています。

SDK をインストールするには、app/build.gradle ファイルの dependencies ブロックに financial-connections を追加します。

注

オプション選択した支払い方法を取得する

To fetch the default payment method without presenting the Payment Method Settings Sheet, call retrievePaymentOptionSelection() on CustomerSheet.

class CheckoutActivity : ComponentActivity() {
    private val viewModel by viewModels<CheckoutViewModel>()
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstance)
        val configuration = ...
        setContent {
            val customerSheet = ...

            LaunchedEffect(Unit) {
                customerSheet.configure(configuration = configuration)
                val result = customerSheet.retrievePaymentOptionSelection()
                viewModel.handleResult(result)
            }

            ...
        }
    }
}

オプション画面をカスタマイズする

デザイン

Appearance API を使用して、アプリのデザインに合わせて色、フォント、その他のデザインの属性をカスタマイズします。

動作

保存された決済手段の関連付け、関連付け解除、一覧表示を行うためのカスタム動作を追加するには、CustomerAdapter を実装した自社構築済みアダプターを実装します。

class MyCustomerAdapter(
   private val adapter: CustomerAdapter
) : CustomerAdapter by adapter {
   override suspend fun retrievePaymentMethods(): CustomerAdapter.Result<List<PaymentMethod>> {
      val result = adapter.retrievePaymentMethods()
        // Only return debit cards
        return when (result) {
            is CustomerAdapter.Result.Success -> {
                CustomerAdapter.Result.success(
                    result.value.filter { it.card?.funding == "debit" }
                )
            }
            else -> CustomerAdapter.Result.success(emptyList())
        }
    }
}

注

retrievePaymentMethods は、保存された決済手段を除外して表示しないようにできますが、追加可能な決済手段のタイプには影響しません。

デフォルトの請求詳細

Customer sheet で収集される請求詳細のデフォルト値を設定するには、defaultBillingDetails プロパティを設定します。CustomerSheet の各フィールドに、指定した値が事前に読み込まれます。

val configuration = CustomerSheet.Configuration.Builder()
    .defaultBillingDetails(
       PaymentSheet.BillingDetails(
         address = PaymentSheet.Address(
           country = "US",
         ),
         email = "foo@bar.com"
      )
    )
    .build()

請求詳細の収集

billingDetailsCollectionConfiguration を使用して、決済画面で請求詳細を収集する方法を指定します。

顧客の名前、メールアドレス、電話番号、住所を収集できます。

CustomerSheet によって収集されない値を関連付けるには、defaultBillingDetails プロパティに値を追加し、billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod を true に設定します。決済手段が必要とする値を収集する予定がない場合は、必ずこの手順を実行してください。

val configuration = CustomerSheet.Configuration.Builder()
    .defaultBillingDetails(
       PaymentSheet.BillingDetails(
           email = "foo@bar.com"
       )
    )
    .billingDetailsCollectionConfiguration(
        PaymentSheet.BillingDetailsCollectionConfiguration(
            name = PaymentSheet.BillingDetailsCollectionConfiguration.AddressCollectionMode.Always,
            email = PaymentSheet.BillingDetailsCollectionConfiguration.AddressCollectionMode.Never,
            address = PaymentSheet.BillingDetailsCollectionConfiguration.AddressCollectionMode.Full,
            attachDefaultsToPaymentMethod = true,
        )
    )
    .build()

注

情報の収集に適用される法律については、法務チームに相談してください。電話番号は、取引に必要な場合にのみ収集してください。

注