Collecting payment details with Checkout

    Learn how to collect payment details without immediately collecting a payment.

    Collecting payment details using Checkout’s setup mode is useful for updating a subscription payment method or for setting up a payment method on file for future payments. Setup mode uses the Setup Intents API to create Payment Methods.

    Use the following steps to create a Checkout page that collects your customer’s payment details and returns a Payment Method:

    1. Create a Checkout setup mode Session on your server
    2. Add Checkout to your website
    3. Retrieve the Session object on your server
    4. Retrieve the SetupIntent object on your server
    5. Use the PaymentMethod object on your server

    Step 1: Create a Checkout setup mode Session on your server

    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. You will use this ID in step 3.

    curl https://api.stripe.com/v1/checkout/sessions \
      -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
      -d "payment_method_types[]"=card \
      -d mode=setup \
      -d success_url="https://example.com/success?session_id={CHECKOUT_SESSION_ID}" \
      -d cancel_url="https://example.com/cancel"
    
    # Set your secret key: remember to change this to your live secret key in production
    # See your keys here: https://dashboard.stripe.com/account/apikeys
    Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'
    
    session = Stripe::Checkout::Session.create(
      payment_method_types: ['card'],
      mode: 'setup',
      success_url: 'https://example.com/success?session_id={CHECKOUT_SESSION_ID}',
      cancel_url: 'https://example.com/cancel',
    )
    
    # Set your secret key: remember to change this to your live secret key in production
    # See your keys here: https://dashboard.stripe.com/account/apikeys
    stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'
    
    session = stripe.checkout.Session.create(
      payment_method_types=['card'],
      mode='setup',
      success_url='https://example.com/success?session_id={CHECKOUT_SESSION_ID}',
      cancel_url='https://example.com/cancel',
    )
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    \Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');
    
    $session = \Stripe\Checkout\Session::create([
      'payment_method_types' => ['card'],
      'mode' => 'setup',
      'success_url' => 'https://example.com/success?session_id={CHECKOUT_SESSION_ID}',
      'cancel_url' => 'https://example.com/cancel',
    ]);
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";
    
    Map<String, Object> params = new HashMap<String, Object>();
    
    ArrayList<String> paymentMethodTypes = new ArrayList<>();
    paymentMethodTypes.add("card");
    params.put("payment_method_types", paymentMethodTypes);
    params.put("mode", "setup");
    params.put("success_url", "https://example.com/success?session_id={CHECKOUT_SESSION_ID}");
    params.put("cancel_url", "https://example.com/cancel");
    
    Session session = Session.create(params);
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');
    
    (async () => {
      const session = await stripe.checkout.sessions.create({
        payment_method_types: ['card'],
        mode: 'setup',
        success_url: 'https://example.com/success?session_id={CHECKOUT_SESSION_ID}',
        cancel_url: 'https://example.com/cancel',
      });
    })();
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"
    
    params := &stripe.CheckoutSessionParams{
        PaymentMethodTypes: stripe.StringSlice([]string{
            "card",
        }),
        Mode: stripe.String(string(stripe.CheckoutSessionModeSetup)),
        SuccessURL: stripe.String("https://example.com/success?session_id={CHECKOUT_SESSION_ID}"),
        CancelURL: stripe.String("https://example.com/cancel"),
    }
    
    session, err := session.New(params)
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";
    
    var options = new SessionCreateOptions {
        PaymentMethodTypes = new List<string> {
            "card",
        },
        Mode = "setup",
        SuccessUrl = "https://example.com/success?session_id={CHECKOUT_SESSION_ID}",
        CancelUrl = "https://example.com/cancel",
    };
    
    var service = new SessionService();
    var session = service.Create(options);
    

    Your Stripe.js integration needs the id field from the Session creation API response, so be sure to make it available to the JavaScript or HTML file you call redirectToCheckout from.

    Step 2: Add Checkout to your website

    To use Checkout on your website, you must add a snippet of code that includes the id field from the session that you created in the previous step.

    Checkout relies on Stripe.js. To get started, include the following script tag on your website—always load it directly from https://js.stripe.com:

    <script src="https://js.stripe.com/v3/"></script>
    

    Next, create an instance of the Stripe object by providing your publishable API key as the first parameter:

    var stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
    
    const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
    

    When your customer is ready to save or update their payment method, call redirectToCheckout to begin the setup process. This is where you provide the id from session creation as a parameter to Checkout.

    stripe.redirectToCheckout({
      // Make the id field from the Checkout Session creation API response
      // available to this file, so you can provide it as parameter here
      // instead of the {{CHECKOUT_SESSION_ID}} placeholder.
      sessionId: '{{CHECKOUT_SESSION_ID}}'
    }).then(function (result) {
      // If `redirectToCheckout` fails due to a browser or network
      // error, display the localized error message to your customer
      // using `result.error.message`.
    });
    const {error} = await stripe.redirectToCheckout({
      // Make the id field from the Checkout Session creation API response
      // available to this file, so you can provide it as parameter here
      // instead of the {{CHECKOUT_SESSION_ID}} placeholder.
      sessionId: '{{CHECKOUT_SESSION_ID}}'
    })
    // If `redirectToCheckout` fails due to a browser or network
    // error, display the localized error message to your customer
    // using `error.message`.

    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 setup button.

    When testing your integration with your test API key, use a test card number to ensure that it works correctly.

    Step 3: Retrieve the Session object on your server

    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 sessionId from the URL when a user redirects back to your site (appended to the success_url in step 1). Retrieve the Session object from /v1/checkout/session/:id.
    curl https://api.stripe.com/v1/checkout/sessions/cs_test_MlZAaTXUMHjWZ7DcXjusJnDU4MxPalbtL5eYrmS2GKxqscDtpJq8QM0k \
      -u sk_test_4eC39HqLyjWDarjtT1zdp7dc:
    
    # Set your secret key: remember to change this to your live secret key in production
    # See your keys here: https://dashboard.stripe.com/account/apikeys
    Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'
    
    Stripe::Checkout::Session.retrieve('cs_test_MlZAaTXUMHjWZ7DcXjusJnDU4MxPalbtL5eYrmS2GKxqscDtpJq8QM0k')
    
    # Set your secret key: remember to change this to your live secret key in production
    # See your keys here: https://dashboard.stripe.com/account/apikeys
    stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'
    
    stripe.checkout.Session.retrieve('cs_test_MlZAaTXUMHjWZ7DcXjusJnDU4MxPalbtL5eYrmS2GKxqscDtpJq8QM0k')
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    \Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');
    
    \Stripe\Checkout\Session::retrieve('cs_test_MlZAaTXUMHjWZ7DcXjusJnDU4MxPalbtL5eYrmS2GKxqscDtpJq8QM0k');
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";
    
    Stripe.Session.retrieve("cs_test_MlZAaTXUMHjWZ7DcXjusJnDU4MxPalbtL5eYrmS2GKxqscDtpJq8QM0k");
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');
    
    stripe.checkout.sessions.retrieve(
      'cs_test_MlZAaTXUMHjWZ7DcXjusJnDU4MxPalbtL5eYrmS2GKxqscDtpJq8QM0k',
      function(err, session) {
        // asynchronously called
      }
    );
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"
    
    session, _ := session.Get("cs_test_MlZAaTXUMHjWZ7DcXjusJnDU4MxPalbtL5eYrmS2GKxqscDtpJq8QM0k", nil)
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";
    
    var service = new SessionService();
    var session = service.Get("cs_test_MlZAaTXUMHjWZ7DcXjusJnDU4MxPalbtL5eYrmS2GKxqscDtpJq8QM0k");
    

    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.

    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,
          "cancel_url": "https://example.com/cancel",
          "client_reference_id": null,
          "customer": null,
          "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.

    Step 4: Retrieve the SetupIntent on your server

    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_4eC39HqLyjWDarjtT1zdp7dc:
    
    # Set your secret key: remember to change this to your live secret key in production
    # See your keys here: https://dashboard.stripe.com/account/apikeys
    Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'
    
    Stripe::SetupIntent.retrieve('seti_1EzVO3HssDVaQm2PJjXHmLlM')
    
    # Set your secret key: remember to change this to your live secret key in production
    # See your keys here: https://dashboard.stripe.com/account/apikeys
    stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'
    
    stripe.SetupIntent.retrieve('seti_1EzVO3HssDVaQm2PJjXHmLlM')
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    \Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');
    
    \Stripe\SetupIntent::retrieve('seti_1EzVO3HssDVaQm2PJjXHmLlM');
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";
    
    Stripe.SetupIntent.retrieve("seti_1EzVO3HssDVaQm2PJjXHmLlM");
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');
    
    stripe.setupIntents.retrieve(
      'seti_1EzVO3HssDVaQm2PJjXHmLlM',
      function(err, setupIntent) {
        // asynchronously called
      }
    );
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"
    
    s, _ := setupintent.Get("seti_1EzVO3HssDVaQm2PJjXHmLlM", nil)
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";
    
    var service = new SetupIntentService();
    var setupIntent = service.Get("seti_1EzVO3HssDVaQm2PJjXHmLlM");
    

    Note the payment_method ID returned for the next step.

    Step 5: Use the PaymentMethod on your server

    After you retrieve the PaymentMethod ID, you can take several actions including:

    Next steps

    Congrats! You now have a Checkout integration that can save payment details.

    Was this page helpful?

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    On this page