Save directly without charging

Create or retrieve a customer

To charge a card saved with Stripe, you must attach it to a Customer.

When you include a customer in your SetupIntent before confirming, Stripe automatically attaches the generated card payment method to the Customer object you provide.

Include the following code on your server to create a new Customer.

curl -X POST https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

Create a SetupIntent

A SetupIntent is an object that represents your intent to set up a customer’s payment method for future payments. The SetupIntent tracks the steps of this setup process. For Terminal, this includes collecting and recording cardholder consent.

You can create a SetupIntent providing the customer, onBehalfOf (Connect only), and usage parameters.

val params = SetupIntentParameters.Builder()
    .setCustomer(
"{{CUSTOMER_ID}}")
    .build()

Terminal.getInstance().createSetupIntent(
    params, object : SetupIntentCallback {
        override fun onSuccess(setupIntent: SetupIntent) {
            // Placeholder for handling successful operation
        }

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

If the information required to start a payment isn’t readily available in your app, you can create the SetupIntent on your server. Use the client secret to call retrieveSetupIntent, and, then use the retrieved SetupIntent to call collectSetupIntentPaymentMethod.

Collect a payment method for saving

After you create a SetupIntent, you need to collect a payment method using the SDK and collect customer consent. Pass allowRedisplay as always or limited, indicating the degree to which a payment method can be shown in a customer checkout flow.

After you create a SetupIntent, you need to collect a payment method with the SDK and collect customer consent. If the customer provides the required form of agreement or consent, set the customerConsentCollected Boolean to true.

To collect a payment method, make sure that you’re connected to a reader. The connected reader waits for a card after your app calls collectSetupIntentPaymentMethod .

val cancelable = Terminal.getInstance().collectSetupIntentPaymentMethod(
    setupIntent,
    AllowRedisplay.ALWAYS,
    callback = object : SetupIntentCallback {
        override fun onSuccess(setupIntent: SetupIntent) {
            // 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 SetupIntent.

Cancel collection

Programmatic cancellation

You can cancel collecting a payment method by using the Cancelable object returned by the SDK.

Customer-initiated cancellation

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().collectSetupIntentPaymentMethod(
    setupIntent,
    AllowRedisplay.ALWAYS,
    SetupIntentConfiguration.Builder()
        .setEnableCustomerCancellation(true)
        .build(),
    object : SetupIntentCallback {
        override fun onSuccess(setupIntent: SetupIntent) {
            // Placeholder for handling successful operation
        }

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

Submit the payment method details to Stripe

Use confirmSetupIntent to complete the setup.

A successful setup returns a succeeded value for the SetupIntent’s status property, along with a SetupAttempt.payment_method_details.card_present.generated_card, which is a reusable card payment method you can use for online payments.

The generated_card payment method automatically attaches to the customer you provided during SetupIntent creation. You can retrieve the generated_card payment method by expanding the SetupIntent’s latest_attempt property. Always check for a generated_card value, because for payment methods that don’t allow generated cards, the value is empty.

curl -G https://api.stripe.com/v1/setup_intents/
{{SETUP_INTENT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "expand[]"=latest_attempt

Alternatively, you can retrieve the attached payment method by fetching the list of payment methods that gets attached to the customer.

curl -G https://api.stripe.com/v1/customers/
{{CUSTOMER_ID}}
/payment_methods \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d type=card

If you didn’t provide a customer during SetupIntent creation, you can attach the generated_card to a Customer object in a separate call.

curl https://api.stripe.com/v1/payment_methods/
{{PAYMENT_METHOD_ID}}
/attach \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}}

If the setup isn’t successful, inspect the returned error to determine the cause. For example, failing to collect and notify Stripe of customer consent results in an error.

val cancelable = Terminal.getInstance().confirmSetupIntent(setupIntent,
    object : SetupIntentCallback {
        override fun onSuccess(setupIntent: SetupIntent) {
            // Placeholder for handling successful operation
        }

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

Mobile wallets considerations

Saved mobile wallets is only for off_session payments such as future subscription or other payments you initiate on behalf of your customer. When you save a digital wallet payment method, the generated_card has allow_redisplay=limited, to indicate its specific usage considerations.

When you attempt to charge a mobile wallet, make sure to pass off_session=true during PaymentIntent confirmation. If the customer is present in your checkout flow, you will need to instead use the Apple Pay and Google Pay integrations to re-prompt for payment method presentment.

Compliance

You’re responsible for your compliance with all applicable laws, regulations, and network rules when saving a customer’s payment details. For example, the European Data Protection Board has issued guidance regarding saving payment details. These requirements generally apply if you want to save your customer’s payment method for future use, such as presenting a customer’s payment method to them in the checkout flow for a future purchase or charging them when they’re not actively using your website or app.

Add terms to your website or app that state how you plan to save payment method details and allow customers to opt in. If you plan to charge the customer while they’re offline, then at a minimum, make sure that your terms also cover the following:

• The customer’s agreement to your initiating a payment or a series of payments on their behalf for specified transactions.
• The anticipated timing and frequency of payments (for instance, whether charges are for scheduled installment or subscription payments, or for unscheduled top-ups).
• How the payment amount is determined.
• Your cancellation policy, if you’re setting up the payment method for a subscription service.

Make sure you keep a record of your customer’s written agreement to these terms.

When you save a payment method, it can only be used for the specific usage that you included in your terms. If you want to charge customers when they’re offline and also save the customer’s payment method to present to them as a saved payment method for future purchases, you must explicitly collect consent from the customer. One way to do so is with a “Save my payment method for future use” checkbox.