Update payment details

First, you need a Stripe account. Register now.

Use our official libraries for access to the Stripe API from your application:

# Available as a gem
sudo gem install stripe

# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

To create a setup mode Session, use the mode parameter with a value of setup when creating the Session. See the Checkout Session API reference for a complete list of parameters that you can use for Session creation.

Append the {CHECKOUT_SESSION_ID} template variable to the success_url to get access to the Session ID after your customer successfully completes a Checkout Session.

Finally, use the setup_intent_data.metadata dictionary to pass your customer’s existing Stripe subscription_id to the Checkout Session. Note that there other ways to pass this data to your server, but we’ll use metadata for this guide.

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "payment_method_types[]"="card" \
  -d "mode"="setup" \
  -d "customer"="cus_FOsk5sbh3ZQpAU" \
  -d "setup_intent_data[metadata][subscription_id]"="sub_8epEF0PuRhmltU" \
  -d "success_url"="https://example.com/success?session_id={CHECKOUT_SESSION_ID}"

After creating the Checkout Session on your server, redirect your customer to the URL returned in the response.

<button id="checkout-button">Update payment method</button>

<script>
const checkoutButton = document.getElementById('checkout-button');

checkoutButton.addEventListener('click', async () => {
  // Call your back end to create the Checkout Session and get the session URL.
  const response = await fetch('/create-checkout-session', { method: 'POST' });
  const { url } = await response.json();
  // Redirect to Checkout.
  window.location.href = url;
});
</script>

This code is typically invoked from an event handler that triggers in response to an action taken by your customer, such as clicking on a payment button.

After a customer successfully completes their Checkout Session, you need to retrieve the Session object. There are two ways to do this:

• Asynchronously: Handle checkout.session.completed webhooks, which contain a Session object. Learn more about setting up webhooks.
• Synchronously: Obtain the Session ID from the success_url when a user redirects back to your site. Use the Session ID to retrieve the Session object.

curl https://api.stripe.com/v1/checkout/sessions/cs_test_MlZAaTXUMHjWZ7DcXjusJnDU4MxPalbtL5eYrmS2GKxqscDtpJq8QM0k \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

The right choice depends on your tolerance for dropoff, as customers may not always reach the success_url after a successful payment. It’s possible for them close their browser tab before the redirect occurs. Handling webhooks prevents your integration from being susceptible to this form of dropoff.

After you have retrieved the Session object, get the value of the setup_intent key, which is the ID for the SetupIntent created during the Checkout Session. A SetupIntent is an object used to set up the customer’s bank account information for future payments.

Example checkout.session.completed payload:

{
  "id": "evt_1Ep24XHssDVaQm2PpwS19Yt0",
  "object": "event",
  "api_version": "2019-03-14",
  "created": 1561420781,
  "data": {
    "object": {
      "id": "cs_test_MlZAaTXUMHjWZ7DcXjusJnDU4MxPalbtL5eYrmS2GKxqscDtpJq8QM0k",
      "object": "checkout.session",
      "billing_address_collection": null,
      "client_reference_id": null,
      "customer": "cus_FOsk5sbh3ZQpAU",
      "customer_email": null,
      "display_items": [],
      "mode": "setup",
      "setup_intent": "seti_1EzVO3HssDVaQm2PJjXHmLlM",
      "submit_type": null,
      "subscription": null,
      "success_url": "https://example.com/success"
    }
  },
  "livemode": false,
  "pending_webhooks": 1,
  "request": {
    "id": null,
    "idempotency_key": null
  },
  "type": "checkout.session.completed"
}

Note the setup_intent ID for the next step.

Using the setup_intent ID, retrieve the SetupIntent object using the /v1/setup_intents/:id endpoint.

curl https://api.stripe.com/v1/setup_intents/seti_1EzVO3HssDVaQm2PJjXHmLlM \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

Example response:

{
  "id": "seti_1EzVO3HssDVaQm2PJjXHmLlM",
  "object": "setup_intent",
  "application": null,
  "cancellation_reason": null,
  "client_secret": null,
  "created": 1561420781,
  "customer": "cus_FOsk5sbh3ZQpAU",
  "description": null,
  "last_setup_error": null,
  "livemode": false,
  "metadata": {
    "subscription_id": "sub_8epEF0PuRhmltU"
  },
  "next_action": null,
  "on_behalf_of": null,
  "payment_method": "pm_1F0c9v2eZvKYlo2CJDeTrB4n",
  "payment_method_types": [
    "card"
  ],
  "status": "succeeded",
  "usage": "off_session"
}

Note the customer ID, subscription_id, and payment_method ID for the next steps.

There are two ways to ensure that a payment method is used for future invoices:

• Set it as the Customer’s invoice_settings.default_payment_method
• Set it as the Subscription’s default_payment_method

Setting invoice_settings.default_payment_method on the Customer will cause all future invoices for that customer to be paid with the specified payment method.

Setting default_payment_method on the Subscription will cause all future invoices for that subscription to be paid with the specified payment method, overriding any invoice_settings.default_payment_method set on the associated Customer.

Set invoice_settings.default_payment_method on the Customer

Using the customer ID and the PaymentMethod ID you retrieved, set the invoice_settings.default_payment_method for the Customer using the /v1/customers/:id endpoint.

curl https://api.stripe.com/v1/customers/cus_FOsk5sbh3ZQpAU \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "invoice_settings[default_payment_method]=pm_1F0c9v2eZvKYlo2CJDeTrB4n"

All future invoices for this customer will now charge the new PaymentMethod created with the setup mode Checkout Session.

Set default_payment_method on the Subscription

Using the subscription ID and the PaymentMethod ID you retrieved, set the default_payment_method for the subscription using the /v1/subscriptions/:id endpoint.

curl https://api.stripe.com/v1/subscriptions/sub_8epEF0PuRhmltU \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -X "POST" \
  -d "default_payment_method"="pm_1F0c9v2eZvKYlo2CJDeTrB4n"

All future invoices for this subscription will now charge the new PaymentMethod created with the setup mode Checkout Session, overriding any invoice_settings.default_payment_method set on the associated Customer.