Checkout Server Quickstart

    Use the Checkout server integration to collect dynamic one-time payments and initiate subscriptions.

    Use the following steps to create a Checkout page that lets a customer make a one-time payment or subscribe to recurring payment plans:

    1. Create a Checkout Session on your server
    2. Add Checkout to your website

    Unlike with the client integration, the Checkout server integration does not require using the Dashboard to pre-define payment options or domains. Using the server integration, you can also enable advanced configuration such as supplying arbitrary payment or subscription metadata.

    Step 1: Create a Checkout Session on your server

    When creating a Session, you can either tell Checkout to create one-time payments or subscriptions.

    To create one-time payments, use the line_items parameter when creating a Session. See the API reference for a complete list of parameters that can be used for session creation.

    curl https://api.stripe.com/v1/checkout/sessions \
      -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
      -d success_url="https://www.example.com/success" \
      -d cancel_url="https://www.example.com/cancel" \
      -d payment_method_types[]=card \
      -d line_items[][amount]=500 \
      -d line_items[][currency]=usd \
      -d line_items[][name]=T-shirt \
      -d line_items[][description]="Comfortable cotton T-shirt" \
      -d line_items[][images][]="https://www.example.com/t-shirt.png" \
      -d line_items[][quantity=1
    
    # 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.create(
      success_url: 'https://www.example.com/success',
      cancel_url: 'https://www.example.com/cancel',
      payment_method_types: ['card'],
      line_items: [{
        amount: 500,
        currency: 'usd',
        name: 'T-shirt',
        description: 'Comfortable cotton t-shirt',
        images: ['https://www.example.com/t-shirt.png'],
        quantity: 1,
      }],
    )
    
    # 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.create(
      success_url='https://www.example.com/success',
      cancel_url='https://www.example.com/cancel',
      payment_method_types=['card'],
      line_items=[
        {
          'amount': 500,
          'currency': 'usd',
          'name': 'T-shirt',
          'description': 'Comfortable cotton t-shirt',
          'images': ['https://www.example.com/t-shirt.png'],
          'quantity': 1,
        }
      ]
    )
    
    // 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
    var stripe = require("stripe")("sk_test_4eC39HqLyjWDarjtT1zdp7dc");
    
    (async () => {
      const session = await stripe.checkout.sessions.create({
        success_url: 'https://www.example.com/success',
        cancel_url: 'https://www.example.com/cancel',
        payment_method_types: ['card'],
        line_items: [{
          amount: 500,
          currency: 'usd',
          name: 'T-shirt',
          description: 'Comfortable cotton t-shirt',
          images: ['https://www.example.com/t-shirt.png'],
          quantity: 1,
        }]
      });
    })();
    
    // 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::create([
      'success_url' => 'https://www.example.com/success',
      'cancel_url' => 'https://www.example.com/cancel',
      'payment_method_types' => ['card'],
      'line_items' => [[
        'amount' => 500,
        'currency' => 'usd',
        'name' => 'T-shirt',
        'description' => 'Comfortable cotton t-shirt',
        'images' => ['https://www.example.com/t-shirt.png'],
        'quantity' => 1,
      ]]
    ]);
    

    To create subscriptions, use the subscription_data parameter when creating a Session. See the API reference for a complete list of parameters that can be used for session creation.

    A Subscription’s details are first dictated by the underlying PlanPlans represent subscription billing options, like price, cadence, and currency., which determines the unit cost, billing interval and currency. You can create a Plan either via the Plans API or through the Dashboard.

    curl https://api.stripe.com/v1/checkout/sessions \
      -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
      -d success_url="https://www.example.com/success" \
      -d cancel_url="https://www.example.com/cancel" \
      -d payment_method_types[]=card \
      -d subscription_data[items][][plan]=plan_xyz
    
    # 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.create(
      success_url: 'https://www.example.com/success',
      cancel_url: 'https://www.example.com/cancel',
      payment_method_types: ['card'],
      subscription_data: {
        items: [{
          plan: 'plan_xyz',
        }],
      }
    )
    
    # 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.create(
      success_url='https://www.example.com/success',
      cancel_url='https://www.example.com/cancel',
      payment_method_types=['card'],
      subscription_data={
        'items': [
          {
            'plan': 'plan_xyz',
          },
        ],
      },
    )
    
    // 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
    var stripe = require("stripe")("sk_test_4eC39HqLyjWDarjtT1zdp7dc");
    
    (async () => {
      const session = await stripe.checkout.sessions.create({
        success_url: 'https://www.example.com/success',
        cancel_url: 'https://www.example.com/cancel',
        payment_method_types: ['card'],
        subscription_data: {
          items: [
            {
              plan: 'plan_xyz',
            },
          ],
        },
      });
    })();
    
    // 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::create([
      'success_url' => 'https://www.example.com/success',
      'cancel_url' => 'https://www.example.com/cancel',
      'payment_method_types' => ['card'],
      'subscription_data' => [
        'items' => [
          [
            'plan' => 'plan_xyz',
          ],
        ],
      ],
    ]);
    

    Your Stripe.js integration needs the id field from the session creation API response, so be sure to make that 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—it should always be loaded 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');

    When your customer is ready to pay, call redirectToCheckout to begin the checkout process. This is where you provide the id from session creation as a parameter to Checkout.

    stripe.redirectToCheckout({
      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`.
    });

    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.

    Once payment is successful, you should fulfillFulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected. the customer’s purchase. You can use webhooks to fulfill the purchase when the checkout.session.completed event triggers. For more details about handling purchase fulfillment with Checkout, refer to the documentation.

    Optional: prefilling customer data

    You may already have collected information about your customer that you want to prefill in the Checkout page to avoid your customers needing to enter their payment information twice. You can prefill the customer email on the Checkout page by providing customer_email when creating a Checkout Session.

    curl https://api.stripe.com/v1/checkout/sessions \
      -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
      -d customer_email="customer@example.com" \
      -d success_url="https://www.example.com/success" \
      -d cancel_url="https://www.example.com/cancel" \
      -d payment_method_types[]=card \
      -d line_items[][amount]=500 \
      -d line_items[][currency]=usd \
      -d line_items[][name]=T-shirt \
      -d line_items[][description]="Comfortable cotton T-shirt" \
      -d line_items[][images][]="https://www.example.com/t-shirt.png" \
      -d line_items[][quantity=1
    
    Stripe::Checkout::Session.create({
      customer_email: 'customer@example.com'
      success_url: 'https://www.example.com/success',
      cancel_url: 'https://www.example.com/cancel',
      payment_method_types: ['card'],
      line_items: [
        {
          amount: 500,
          currency: 'usd',
          name: 'T-shirt',
          description: 'Comfortable cotton t-shirt',
          images: ['https://www.example.com/t-shirt.png'],
          quantity: 1,
        },
      ],
    })
    
    stripe.checkout.Session.create(
      customer_email='customer@example.com',
      success_url='https://www.example.com/success',
      cancel_url='https://www.example.com/cancel',
      payment_method_types=['card'],
      line_items=[
        {
          'amount': 500,
          'currency': 'usd',
          'name': 'T-shirt',
          'description': 'Comfortable cotton t-shirt',
          'images': ['https://www.example.com/t-shirt.png'],
          'quantity': 1,
        },
      ],
    )
    
    (async () => {
      const session = await stripe.checkout.sessions.create({
        customer_email: 'customer@example.com',
        success_url: 'https://www.example.com/success',
        cancel_url: 'https://www.example.com/cancel',
        payment_method_types: ['card'],
        line_items: [
          {
            amount: 500,
            currency: 'usd',
            name: 'T-shirt',
            description: 'Comfortable cotton t-shirt',
            images: ['https://www.example.com/t-shirt.png'],
            quantity: 1,
          },
        ],
      });
    })();
    
    \\Stripe\\Checkout\\Session::create([
      'customer_email' => 'customer@example.com',
      'success_url' => 'https://www.example.com/success',
      'cancel_url' => 'https://www.example.com/cancel',
      'payment_method_types' => ['card'],
      'line_items' => [
        [
          'amount' => 500,
          'currency' => 'usd'
          'name' => 'T-shirt',
          'description' => 'Comfortable cotton t-shirt',
          'quantity' => 1,
        ],
      ],
    ]);
    

    Optional: using existing customers

    You may specify an existing Customer object for Checkout to use when making one-time payments (this does not yet work with plans and subscriptions). If you do so, any Stripe objects that Checkout creates are associated with that Customer. When you specify a Customer, Stripe also uses the email stored on the customer to prefill the email field on the Checkout page. If the customer changes their email on the Checkout page, it will be updated on the Customer object after a successful payment.

    curl https://api.stripe.com/v1/checkout/sessions \
      -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
      -d customer=cus_123 \
      -d success_url="https://www.example.com/success" \
      -d cancel_url="https://www.example.com/cancel" \
      -d payment_method_types[]=card \
      -d line_items[][amount]=500 \
      -d line_items[][currency]=usd \
      -d line_items[][name]=T-shirt \
      -d line_items[][description]="Comfortable cotton T-shirt" \
      -d line_items[][images][]="https://www.example.com/t-shirt.png" \
      -d line_items[][quantity=1
    
    Stripe::Checkout::Session.create({
      customer: 'cus_123',
      success_url: 'https://www.example.com/success',
      cancel_url: 'https://www.example.com/cancel',
      payment_method_types: ['card'],
      line_items: [
        {
          amount: 500,
          currency: 'usd',
          name: 'T-shirt',
          description: 'Comfortable cotton t-shirt',
          images: ['https://www.example.com/t-shirt.png'],
          quantity: 1,
        },
      ],
    })
    
    stripe.checkout.Session.create(
      customer='cus_123',
      success_url='https://www.example.com/success',
      cancel_url='https://www.example.com/cancel',
      payment_method_types=['card'],
      line_items=[
        {
          'amount': 500,
          'currency': 'usd',
          'name': 'T-shirt',
          'description': 'Comfortable cotton t-shirt',
          'images': ['https://www.example.com/t-shirt.png'],
          'quantity': 1,
        },
      ],
    )
    
    (async () => {
      const session = await stripe.checkout.sessions.create({
        customer: 'cus_123',
        success_url: 'https://www.example.com/success',
        cancel_url: 'https://www.example.com/cancel',
        payment_method_types: ['card'],
        line_items: [
          {
            amount: 500,
            currency: 'usd',
            name: 'T-shirt',
            description: 'Comfortable cotton t-shirt',
            quantity: 1,
          },
        ],
      });
    })();
    
    \\Stripe\\Checkout\\Session::create([
      'customer' => 'cus_123',
      'success_url' => 'https://www.example.com/success',
      'cancel_url' => 'https://www.example.com/cancel',
      'payment_method_types' => ['card'],
      'line_items' => [
        [
          'amount' => 500,
          'currency' => 'usd'
          'name' => 'T-shirt',
          'description' => 'Comfortable cotton t-shirt',
          'images' => ['https://www.example.com/t-shirt.png'],
          'quantity' => 1,
        ],
      ],
    ]);
    

    Optional: separate authorization and capture

    Stripe supports two-step card payments so you can first authorize the card, then wait to capture funds later. When a payment is authorized, the funds are guaranteed by the card issuer and the amount held on the customer’s card for up to seven days. If the payment is not captured within this time, the payment is canceled and funds released.

    To indicate that you want separate authorization and capture, you must set the value of payment_intent_data.capture_method option to manual when creating the Checkout Session. This instructs Stripe to only authorize the amount on the customer’s card.

    curl https://api.stripe.com/v1/checkout/sessions \
      -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
      -d success_url="https://www.example.com/success" \
      -d cancel_url="https://www.example.com/cancel" \
      -d payment_method_types[]=card \
      -d line_items[][amount]=500 \
      -d line_items[][currency]=usd \
      -d line_items[][name]=T-shirt \
      -d line_items[][description]="Comfortable cotton T-shirt" \
      -d line_items[][images][]="https://www.example.com/t-shirt.png" \
      -d line_items[][quantity=1 \
      -d payment_intent_data[capture_method=manual
    
    Stripe::Checkout::Session.create(
      success_url: 'https://www.example.com/success',
      cancel_url: 'https://www.example.com/cancel',
      payment_method_types: ['card'],
      line_items: [{
        amount: 500,
        currency: 'usd',
        name: 'T-shirt',
        description: 'Comfortable cotton t-shirt',
        images: ['https://www.example.com/t-shirt.png'],
        quantity: 1,
      }],
      payment_intent_data: {
        capture_method: 'manual',
      }
    )
    
    stripe.checkout.Session.create(
      success_url='https://www.example.com/success',
      cancel_url='https://www.example.com/cancel',
      payment_method_types=['card'],
      line_items=[
        {
          'amount': 500,
          'name': 'T-shirt',
          'description': 'Comfortable cotton t-shirt',
          'images': ['https://www.example.com/t-shirt.png']
          'quantity': 1,
        }
      ],
      payment_intent_data={
        'capture_method': 'manual',
      }
    )
    
    (async () => {
      const session = await stripe.checkout.sessions.create({
        success_url: 'https://www.example.com/success',
        cancel_url: 'https://www.example.com/cancel',
        payment_method_types: ['card'],
        line_items: [
          {
            amount: 500,
            currency: 'usd',
            name: 'T-shirt',
            description: 'Comfortable cotton t-shirt',
            images: ['https://www.example.com/t-shirt.png'],
            quantity: 1,
          },
        ],
        payment_intent_data: {
          'capture_method': 'manual',
        },
      });
    })();
    
    \\Stripe\\Checkout\\Session::create([
      'success_url' => 'https://www.example.com/success',
      'cancel_url' => 'https://www.example.com/cancel',
      'payment_method_types' => ['card'],
      'line_items' => [
        [
          'amount' => 500,
          'currency' => 'usd'
          'name' => 'T-shirt',
          'description' => 'Comfortable cotton t-shirt',
          'images' => ['https://www.example.com/t-shirt.png'],
          'quantity' => 1,
        ],
      ],
      'payment_intent_data' => {
        'capture_method' => 'manual',
      }
    ]);
    

    To capture an uncaptured payment, you can use either the Dashboard or the API.

    Next steps

    Congrats! You now have a complete Checkout integration using the Checkout Sessions API. When testing your integration with your test API key, you can use a test card number to ensure that it works correctly.

    Questions?

    We're always happy to help with code or other questions you might have! Search our documentation, contact support, or connect with our sales team. You can also chat live with other developers in #stripe on freenode.

    Was this page helpful? Yes No

    Send

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

    On this page