Class: Stripe::Checkout::Session

Inherits:
APIResource show all
Extended by:
APIOperations::Create, APIOperations::List
Includes:
APIOperations::Save
Defined in:
lib/stripe/resources/checkout/session.rb

Overview

A Checkout Session represents your customer’s session as they pay for one-time purchases or subscriptions through [Checkout](stripe.com/docs/payments/checkout) or [Payment Links](stripe.com/docs/payments/payment-links). We recommend creating a new Session each time your customer attempts to pay.

Once payment is successful, the Checkout Session will contain a reference to the [Customer](stripe.com/docs/api/customers), and either the successful [PaymentIntent](stripe.com/docs/api/payment_intents) or an active [Subscription](stripe.com/docs/api/subscriptions).

You can create a Checkout Session on your server and redirect to its URL to begin Checkout.

Related guide: [Checkout quickstart](stripe.com/docs/checkout/quickstart)

Defined Under Namespace

Classes: AdaptivePricing, AfterExpiration, AutomaticTax, CollectedInformation, Consent, ConsentCollection, CreateParams, CurrencyConversion, CustomField, CustomText, CustomerDetails, Discount, ExpireParams, InvoiceCreation, ListLineItemsParams, ListParams, OptionalItem, PaymentMethodConfigurationDetails, PaymentMethodOptions, Permissions, PhoneNumberCollection, PresentmentDetails, SavedPaymentMethodOptions, ShippingAddressCollection, ShippingCost, ShippingOption, TaxIdCollection, TotalDetails, UpdateParams

Constant Summary collapse

OBJECT_NAME = 
"checkout.session"

Constants inherited from StripeObject

StripeObject::RESERVED_FIELD_NAMES

Instance Attribute Summary collapse

Attributes inherited from APIResource

#save_with_parent

Attributes inherited from StripeObject

#last_response

Class Method Summary collapse

Instance Method Summary collapse

Methods included from APIOperations::Create

create

Methods included from APIOperations::List

list

Methods included from APIOperations::Save

included, #save

Methods inherited from APIResource

class_name, custom_method, #refresh, #request_stripe_object, resource_url, #resource_url, retrieve, save_nested_resource

Methods included from APIOperations::Request

included

Methods inherited from StripeObject

#==, #[], #[]=, additive_object_param, additive_object_param?, #as_json, construct_from, #deleted?, #dirty!, #each, #eql?, #hash, #initialize, #inspect, #keys, #marshal_dump, #marshal_load, protected_fields, #serialize_params, #to_hash, #to_json, #to_s, #update_attributes, #values

Constructor Details

This class inherits a constructor from Stripe::StripeObject

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Stripe::StripeObject

Instance Attribute Details

#adaptive_pricing ⇒ Object (readonly)

Settings for price localization with [Adaptive Pricing](docs.stripe.com/payments/checkout/adaptive-pricing).



3416
3417
3418
 
# File 'lib/stripe/resources/checkout/session.rb', line 3416

def adaptive_pricing
  @adaptive_pricing
end

#after_expiration ⇒ Object (readonly)

When set, provides configuration for actions to take if this Checkout Session expires.



3418
3419
3420
 
# File 'lib/stripe/resources/checkout/session.rb', line 3418

def after_expiration
  @after_expiration
end

#allow_promotion_codes ⇒ Object (readonly)

Enables user redeemable promotion codes.



3420
3421
3422
 
# File 'lib/stripe/resources/checkout/session.rb', line 3420

def allow_promotion_codes
  @allow_promotion_codes
end

#amount_subtotal ⇒ Object (readonly)

Total of all items before discounts or taxes are applied.



3422
3423
3424
 
# File 'lib/stripe/resources/checkout/session.rb', line 3422

def amount_subtotal
  @amount_subtotal
end

#amount_total ⇒ Object (readonly)

Total of all items after discounts and taxes are applied.



3424
3425
3426
 
# File 'lib/stripe/resources/checkout/session.rb', line 3424

def amount_total
  @amount_total
end

#automatic_tax ⇒ Object (readonly)

Attribute for field automatic_tax



3426
3427
3428
 
# File 'lib/stripe/resources/checkout/session.rb', line 3426

def automatic_tax
  @automatic_tax
end

#billing_address_collection ⇒ Object (readonly)

Describes whether Checkout should collect the customer’s billing address. Defaults to ‘auto`.



3428
3429
3430
 
# File 'lib/stripe/resources/checkout/session.rb', line 3428

def billing_address_collection
  @billing_address_collection
end

#cancel_url ⇒ Object (readonly)

If set, Checkout displays a back button and customers will be directed to this URL if they decide to cancel payment and return to your website.



3430
3431
3432
 
# File 'lib/stripe/resources/checkout/session.rb', line 3430

def cancel_url
  @cancel_url
end

#client_reference_id ⇒ Object (readonly)

A unique string to reference the Checkout Session. This can be a customer ID, a cart ID, or similar, and can be used to reconcile the Session with your internal systems.



3434
3435
3436
 
# File 'lib/stripe/resources/checkout/session.rb', line 3434

def client_reference_id
  @client_reference_id
end

#client_secret ⇒ Object (readonly)

The client secret of your Checkout Session. Applies to Checkout Sessions with ‘ui_mode: embedded`. Client secret to be used when initializing Stripe.js embedded checkout.



3436
3437
3438
 
# File 'lib/stripe/resources/checkout/session.rb', line 3436

def client_secret
  @client_secret
end

#collected_information ⇒ Object (readonly)

Information about the customer collected within the Checkout Session.



3438
3439
3440
 
# File 'lib/stripe/resources/checkout/session.rb', line 3438

def collected_information
  @collected_information
end

#consent ⇒ Object (readonly)

Results of ‘consent_collection` for this session.



3440
3441
3442
 
# File 'lib/stripe/resources/checkout/session.rb', line 3440

def consent
  @consent
end

#consent_collection ⇒ Object (readonly)

When set, provides configuration for the Checkout Session to gather active consent from customers.



3442
3443
3444
 
# File 'lib/stripe/resources/checkout/session.rb', line 3442

def consent_collection
  @consent_collection
end

#created ⇒ Object (readonly)

Time at which the object was created. Measured in seconds since the Unix epoch.



3444
3445
3446
 
# File 'lib/stripe/resources/checkout/session.rb', line 3444

def created
  @created
end

#currency ⇒ Object (readonly)

Three-letter [ISO currency code](www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](stripe.com/docs/currencies).



3446
3447
3448
 
# File 'lib/stripe/resources/checkout/session.rb', line 3446

def currency
  @currency
end

#currency_conversion ⇒ Object (readonly)

Currency conversion details for [Adaptive Pricing](docs.stripe.com/payments/checkout/adaptive-pricing) sessions created before 2025-03-31.



3448
3449
3450
 
# File 'lib/stripe/resources/checkout/session.rb', line 3448

def currency_conversion
  @currency_conversion
end

#custom_fields ⇒ Object (readonly)

Collect additional information from your customer using custom fields. Up to 3 fields are supported.



3450
3451
3452
 
# File 'lib/stripe/resources/checkout/session.rb', line 3450

def custom_fields
  @custom_fields
end

#custom_text ⇒ Object (readonly)

Attribute for field custom_text



3452
3453
3454
 
# File 'lib/stripe/resources/checkout/session.rb', line 3452

def custom_text
  @custom_text
end

#customer ⇒ Object (readonly)

The ID of the customer for this Session. For Checkout Sessions in ‘subscription` mode or Checkout Sessions with `customer_creation` set as `always` in `payment` mode, Checkout will create a new customer object based on information provided during the payment flow unless an existing customer was provided when the Session was created.



3458
3459
3460
 
# File 'lib/stripe/resources/checkout/session.rb', line 3458

def customer
  @customer
end

#customer_creation ⇒ Object (readonly)

Configure whether a Checkout Session creates a Customer when the Checkout Session completes.



3460
3461
3462
 
# File 'lib/stripe/resources/checkout/session.rb', line 3460

def customer_creation
  @customer_creation
end

#customer_details ⇒ Object (readonly)

The customer details including the customer’s tax exempt status and the customer’s tax IDs. Customer’s address details are not present on Sessions in ‘setup` mode.



3462
3463
3464
 
# File 'lib/stripe/resources/checkout/session.rb', line 3462

def customer_details
  @customer_details
end

#customer_email ⇒ Object (readonly)

If provided, this value will be used when the Customer object is created. If not provided, customers will be asked to enter their email address. Use this parameter to prefill customer data if you already have an email on file. To access information about the customer once the payment flow is complete, use the ‘customer` attribute.



3468
3469
3470
 
# File 'lib/stripe/resources/checkout/session.rb', line 3468

def customer_email
  @customer_email
end

#discounts ⇒ Object (readonly)

List of coupons and promotion codes attached to the Checkout Session.



3470
3471
3472
 
# File 'lib/stripe/resources/checkout/session.rb', line 3470

def discounts
  @discounts
end

#expires_at ⇒ Object (readonly)

The timestamp at which the Checkout Session will expire.



3472
3473
3474
 
# File 'lib/stripe/resources/checkout/session.rb', line 3472

def expires_at
  @expires_at
end

#id ⇒ Object (readonly)

Unique identifier for the object.



3474
3475
3476
 
# File 'lib/stripe/resources/checkout/session.rb', line 3474

def id
  @id
end

#invoice ⇒ Object (readonly)

ID of the invoice created by the Checkout Session, if it exists.



3476
3477
3478
 
# File 'lib/stripe/resources/checkout/session.rb', line 3476

def invoice
  @invoice
end

#invoice_creation ⇒ Object (readonly)

Details on the state of invoice creation for the Checkout Session.



3478
3479
3480
 
# File 'lib/stripe/resources/checkout/session.rb', line 3478

def invoice_creation
  @invoice_creation
end

#line_items ⇒ Object (readonly)

The line items purchased by the customer.



3480
3481
3482
 
# File 'lib/stripe/resources/checkout/session.rb', line 3480

def line_items
  @line_items
end

#livemode ⇒ Object (readonly)

Has the value ‘true` if the object exists in live mode or the value `false` if the object exists in test mode.



3482
3483
3484
 
# File 'lib/stripe/resources/checkout/session.rb', line 3482

def livemode
  @livemode
end

#locale ⇒ Object (readonly)

The IETF language tag of the locale Checkout is displayed in. If blank or ‘auto`, the browser’s locale is used.



3484
3485
3486
 
# File 'lib/stripe/resources/checkout/session.rb', line 3484

def locale
  @locale
end

#metadata ⇒ Object (readonly)

Set of [key-value pairs](stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.



3486
3487
3488
 
# File 'lib/stripe/resources/checkout/session.rb', line 3486

def metadata
  @metadata
end

#mode ⇒ Object (readonly)

The mode of the Checkout Session.



3488
3489
3490
 
# File 'lib/stripe/resources/checkout/session.rb', line 3488

def mode
  @mode
end

#object ⇒ Object (readonly)

String representing the object’s type. Objects of the same type share the same value.



3490
3491
3492
 
# File 'lib/stripe/resources/checkout/session.rb', line 3490

def object
  @object
end

#optional_items ⇒ Object (readonly)

The optional items presented to the customer at checkout.



3492
3493
3494
 
# File 'lib/stripe/resources/checkout/session.rb', line 3492

def optional_items
  @optional_items
end

#payment_intent ⇒ Object (readonly)

The ID of the PaymentIntent for Checkout Sessions in ‘payment` mode. You can’t confirm or cancel the PaymentIntent for a Checkout Session. To cancel, [expire the Checkout Session](stripe.com/docs/api/checkout/sessions/expire) instead.



3494
3495
3496
 
# File 'lib/stripe/resources/checkout/session.rb', line 3494

def payment_intent
  @payment_intent
end

#payment_link ⇒ Object (readonly)

The ID of the Payment Link that created this Session.



3496
3497
3498
 
# File 'lib/stripe/resources/checkout/session.rb', line 3496

def payment_link
  @payment_link
end

#payment_method_collection ⇒ Object (readonly)

Configure whether a Checkout Session should collect a payment method. Defaults to ‘always`.



3498
3499
3500
 
# File 'lib/stripe/resources/checkout/session.rb', line 3498

def payment_method_collection
  @payment_method_collection
end

#payment_method_configuration_details ⇒ Object (readonly)

Information about the payment method configuration used for this Checkout session if using dynamic payment methods.



3500
3501
3502
 
# File 'lib/stripe/resources/checkout/session.rb', line 3500

def payment_method_configuration_details
  @payment_method_configuration_details
end

#payment_method_options ⇒ Object (readonly)

Payment-method-specific configuration for the PaymentIntent or SetupIntent of this CheckoutSession.



3502
3503
3504
 
# File 'lib/stripe/resources/checkout/session.rb', line 3502

def payment_method_options
  @payment_method_options
end

#payment_method_types ⇒ Object (readonly)

A list of the types of payment methods (e.g. card) this Checkout Session is allowed to accept.



3505
3506
3507
 
# File 'lib/stripe/resources/checkout/session.rb', line 3505

def payment_method_types
  @payment_method_types
end

#payment_status ⇒ Object (readonly)

The payment status of the Checkout Session, one of ‘paid`, `unpaid`, or `no_payment_required`. You can use this value to decide when to fulfill your customer’s order.



3508
3509
3510
 
# File 'lib/stripe/resources/checkout/session.rb', line 3508

def payment_status
  @payment_status
end

#permissions ⇒ Object (readonly)

This property is used to set up permissions for various actions (e.g., update) on the CheckoutSession object.

For specific permissions, please refer to their dedicated subsections, such as ‘permissions.update.shipping_details`.



3512
3513
3514
 
# File 'lib/stripe/resources/checkout/session.rb', line 3512

def permissions
  @permissions
end

#phone_number_collection ⇒ Object (readonly)

Attribute for field phone_number_collection



3514
3515
3516
 
# File 'lib/stripe/resources/checkout/session.rb', line 3514

def phone_number_collection
  @phone_number_collection
end

#presentment_details ⇒ Object (readonly)

Attribute for field presentment_details



3516
3517
3518
 
# File 'lib/stripe/resources/checkout/session.rb', line 3516

def presentment_details
  @presentment_details
end

#recovered_from ⇒ Object (readonly)

The ID of the original expired Checkout Session that triggered the recovery flow.



3518
3519
3520
 
# File 'lib/stripe/resources/checkout/session.rb', line 3518

def recovered_from
  @recovered_from
end

#redirect_on_completion ⇒ Object (readonly)

This parameter applies to ‘ui_mode: embedded`. Learn more about the [redirect behavior](stripe.com/docs/payments/checkout/custom-success-page?payment-ui=embedded-form) of embedded sessions. Defaults to `always`.



3520
3521
3522
 
# File 'lib/stripe/resources/checkout/session.rb', line 3520

def redirect_on_completion
  @redirect_on_completion
end

#return_url ⇒ Object (readonly)

Applies to Checkout Sessions with ‘ui_mode: embedded`. The URL to redirect your customer back to after they authenticate or cancel their payment on the payment method’s app or site.



3522
3523
3524
 
# File 'lib/stripe/resources/checkout/session.rb', line 3522

def return_url
  @return_url
end

#saved_payment_method_options ⇒ Object (readonly)

Controls saved payment method settings for the session. Only available in ‘payment` and `subscription` mode.



3524
3525
3526
 
# File 'lib/stripe/resources/checkout/session.rb', line 3524

def saved_payment_method_options
  @saved_payment_method_options
end

#setup_intent ⇒ Object (readonly)

The ID of the SetupIntent for Checkout Sessions in ‘setup` mode. You can’t confirm or cancel the SetupIntent for a Checkout Session. To cancel, [expire the Checkout Session](stripe.com/docs/api/checkout/sessions/expire) instead.



3526
3527
3528
 
# File 'lib/stripe/resources/checkout/session.rb', line 3526

def setup_intent
  @setup_intent
end

#shipping_address_collection ⇒ Object (readonly)

When set, provides configuration for Checkout to collect a shipping address from a customer.



3528
3529
3530
 
# File 'lib/stripe/resources/checkout/session.rb', line 3528

def shipping_address_collection
  @shipping_address_collection
end

#shipping_cost ⇒ Object (readonly)

The details of the customer cost of shipping, including the customer chosen ShippingRate.



3530
3531
3532
 
# File 'lib/stripe/resources/checkout/session.rb', line 3530

def shipping_cost
  @shipping_cost
end

#shipping_options ⇒ Object (readonly)

The shipping rate options applied to this Session.



3532
3533
3534
 
# File 'lib/stripe/resources/checkout/session.rb', line 3532

def shipping_options
  @shipping_options
end

#status ⇒ Object (readonly)

The status of the Checkout Session, one of ‘open`, `complete`, or `expired`.



3534
3535
3536
 
# File 'lib/stripe/resources/checkout/session.rb', line 3534

def status
  @status
end

#submit_type ⇒ Object (readonly)

Describes the type of transaction being performed by Checkout in order to customize relevant text on the page, such as the submit button. ‘submit_type` can only be specified on Checkout Sessions in `payment` mode. If blank or `auto`, `pay` is used.



3538
3539
3540
 
# File 'lib/stripe/resources/checkout/session.rb', line 3538

def submit_type
  @submit_type
end

#subscription ⇒ Object (readonly)

The ID of the subscription for Checkout Sessions in ‘subscription` mode.



3540
3541
3542
 
# File 'lib/stripe/resources/checkout/session.rb', line 3540

def subscription
  @subscription
end

#success_url ⇒ Object (readonly)

The URL the customer will be directed to after the payment or subscription creation is successful.



3543
3544
3545
 
# File 'lib/stripe/resources/checkout/session.rb', line 3543

def success_url
  @success_url
end

#tax_id_collection ⇒ Object (readonly)

Attribute for field tax_id_collection



3545
3546
3547
 
# File 'lib/stripe/resources/checkout/session.rb', line 3545

def tax_id_collection
  @tax_id_collection
end

#total_details ⇒ Object (readonly)

Tax and discount details for the computed total amount.



3547
3548
3549
 
# File 'lib/stripe/resources/checkout/session.rb', line 3547

def total_details
  @total_details
end

#ui_mode ⇒ Object (readonly)

The UI mode of the Session. Defaults to ‘hosted`.



3549
3550
3551
 
# File 'lib/stripe/resources/checkout/session.rb', line 3549

def ui_mode
  @ui_mode
end

#url ⇒ Object (readonly)

The URL to the Checkout Session. Applies to Checkout Sessions with ‘ui_mode: hosted`. Redirect customers to this URL to take them to Checkout. If you’re using [Custom Domains](stripe.com/docs/payments/checkout/custom-domains), the URL will use your subdomain. Otherwise, it’ll use `checkout.stripe.com.` This value is only present when the session is active.



3552
3553
3554
 
# File 'lib/stripe/resources/checkout/session.rb', line 3552

def url
  @url
end

Class Method Details

.create(params = {}, opts = {}) ⇒ Object

Creates a Checkout Session object.



3555
3556
3557
3558
3559
3560
3561
3562
 
# File 'lib/stripe/resources/checkout/session.rb', line 3555

def self.create(params = {}, opts = {})
  request_stripe_object(
    method: :post,
    path: "/v1/checkout/sessions",
    params: params,
    opts: opts
  )
end

.expire(session, params = {}, opts = {}) ⇒ Object

A Checkout Session can be expired when it is in one of these statuses: open

After it expires, a customer can’t complete a Checkout Session and customers loading the Checkout Session see a message saying the Checkout Session is expired.



3579
3580
3581
3582
3583
3584
3585
3586
 
# File 'lib/stripe/resources/checkout/session.rb', line 3579

def self.expire(session, params = {}, opts = {})
  request_stripe_object(
    method: :post,
    path: format("/v1/checkout/sessions/%<session>s/expire", { session: CGI.escape(session) }),
    params: params,
    opts: opts
  )
end

.list(params = {}, opts = {}) ⇒ Object

Returns a list of Checkout Sessions.



3589
3590
3591
3592
3593
3594
3595
3596
 
# File 'lib/stripe/resources/checkout/session.rb', line 3589

def self.list(params = {}, opts = {})
  request_stripe_object(
    method: :get,
    path: "/v1/checkout/sessions",
    params: params,
    opts: opts
  )
end

.list_line_items(session, params = {}, opts = {}) ⇒ Object

When retrieving a Checkout Session, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.



3609
3610
3611
3612
3613
3614
3615
3616
 
# File 'lib/stripe/resources/checkout/session.rb', line 3609

def self.list_line_items(session, params = {}, opts = {})
  request_stripe_object(
    method: :get,
    path: format("/v1/checkout/sessions/%<session>s/line_items", { session: CGI.escape(session) }),
    params: params,
    opts: opts
  )
end

.object_name ⇒ Object 



26
27
28
 
# File 'lib/stripe/resources/checkout/session.rb', line 26

def self.object_name
  "checkout.session"
end

.update(session, params = {}, opts = {}) ⇒ Object

Updates a Checkout Session object.



3619
3620
3621
3622
3623
3624
3625
3626
 
# File 'lib/stripe/resources/checkout/session.rb', line 3619

def self.update(session, params = {}, opts = {})
  request_stripe_object(
    method: :post,
    path: format("/v1/checkout/sessions/%<session>s", { session: CGI.escape(session) }),
    params: params,
    opts: opts
  )
end

Instance Method Details

#expire(params = {}, opts = {}) ⇒ Object

A Checkout Session can be expired when it is in one of these statuses: open

After it expires, a customer can’t complete a Checkout Session and customers loading the Checkout Session see a message saying the Checkout Session is expired.



3567
3568
3569
3570
3571
3572
3573
3574
 
# File 'lib/stripe/resources/checkout/session.rb', line 3567

def expire(params = {}, opts = {})
  request_stripe_object(
    method: :post,
    path: format("/v1/checkout/sessions/%<session>s/expire", { session: CGI.escape(self["id"]) }),
    params: params,
    opts: opts
  )
end

#list_line_items(params = {}, opts = {}) ⇒ Object

When retrieving a Checkout Session, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.



3599
3600
3601
3602
3603
3604
3605
3606
 
# File 'lib/stripe/resources/checkout/session.rb', line 3599

def list_line_items(params = {}, opts = {})
  request_stripe_object(
    method: :get,
    path: format("/v1/checkout/sessions/%<session>s/line_items", { session: CGI.escape(self["id"]) }),
    params: params,
    opts: opts
  )
end