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, CheckoutItem, 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, WalletOptions

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).



4161
4162
4163
 
# File 'lib/stripe/resources/checkout/session.rb', line 4161

def adaptive_pricing
  @adaptive_pricing
end

#after_expiration ⇒ Object (readonly)

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



4163
4164
4165
 
# File 'lib/stripe/resources/checkout/session.rb', line 4163

def after_expiration
  @after_expiration
end

#allow_promotion_codes ⇒ Object (readonly)

Enables user redeemable promotion codes.



4165
4166
4167
 
# File 'lib/stripe/resources/checkout/session.rb', line 4165

def allow_promotion_codes
  @allow_promotion_codes
end

#amount_subtotal ⇒ Object (readonly)

Total of all items before discounts or taxes are applied.



4167
4168
4169
 
# File 'lib/stripe/resources/checkout/session.rb', line 4167

def amount_subtotal
  @amount_subtotal
end

#amount_total ⇒ Object (readonly)

Total of all items after discounts and taxes are applied.



4169
4170
4171
 
# File 'lib/stripe/resources/checkout/session.rb', line 4169

def amount_total
  @amount_total
end

#automatic_tax ⇒ Object (readonly)

Attribute for field automatic_tax



4171
4172
4173
 
# File 'lib/stripe/resources/checkout/session.rb', line 4171

def automatic_tax
  @automatic_tax
end

#billing_address_collection ⇒ Object (readonly)

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



4173
4174
4175
 
# File 'lib/stripe/resources/checkout/session.rb', line 4173

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.



4175
4176
4177
 
# File 'lib/stripe/resources/checkout/session.rb', line 4175

def cancel_url
  @cancel_url
end

#checkout_items ⇒ Object (readonly)

Attribute for field checkout_items



4306
4307
4308
 
# File 'lib/stripe/resources/checkout/session.rb', line 4306

def checkout_items
  @checkout_items
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.



4179
4180
4181
 
# File 'lib/stripe/resources/checkout/session.rb', line 4179

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` or `ui_mode: custom`. For `ui_mode: embedded`, the client secret is to be used when initializing Stripe.js embedded checkout.

For `ui_mode: custom`, use the client secret with [initCheckout](https://stripe.com/docs/js/custom_checkout/init) on your front end.



4182
4183
4184
 
# File 'lib/stripe/resources/checkout/session.rb', line 4182

def client_secret
  @client_secret
end

#collected_information ⇒ Object (readonly)

Information about the customer collected within the Checkout Session.



4184
4185
4186
 
# File 'lib/stripe/resources/checkout/session.rb', line 4184

def collected_information
  @collected_information
end

#consent ⇒ Object (readonly)

Results of ‘consent_collection` for this session.



4186
4187
4188
 
# File 'lib/stripe/resources/checkout/session.rb', line 4186

def consent
  @consent
end

#consent_collection ⇒ Object (readonly)

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



4188
4189
4190
 
# File 'lib/stripe/resources/checkout/session.rb', line 4188

def consent_collection
  @consent_collection
end

#created ⇒ Object (readonly)

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



4190
4191
4192
 
# File 'lib/stripe/resources/checkout/session.rb', line 4190

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).



4192
4193
4194
 
# File 'lib/stripe/resources/checkout/session.rb', line 4192

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.



4194
4195
4196
 
# File 'lib/stripe/resources/checkout/session.rb', line 4194

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.



4196
4197
4198
 
# File 'lib/stripe/resources/checkout/session.rb', line 4196

def custom_fields
  @custom_fields
end

#custom_text ⇒ Object (readonly)

Attribute for field custom_text



4198
4199
4200
 
# File 'lib/stripe/resources/checkout/session.rb', line 4198

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.



4204
4205
4206
 
# File 'lib/stripe/resources/checkout/session.rb', line 4204

def customer
  @customer
end

#customer_account ⇒ Object (readonly)

The ID of the account for this Session.



4206
4207
4208
 
# File 'lib/stripe/resources/checkout/session.rb', line 4206

def 
  @customer_account
end

#customer_creation ⇒ Object (readonly)

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



4208
4209
4210
 
# File 'lib/stripe/resources/checkout/session.rb', line 4208

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.



4210
4211
4212
 
# File 'lib/stripe/resources/checkout/session.rb', line 4210

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.



4216
4217
4218
 
# File 'lib/stripe/resources/checkout/session.rb', line 4216

def customer_email
  @customer_email
end

#discounts ⇒ Object (readonly)

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



4218
4219
4220
 
# File 'lib/stripe/resources/checkout/session.rb', line 4218

def discounts
  @discounts
end

#expires_at ⇒ Object (readonly)

The timestamp at which the Checkout Session will expire.



4220
4221
4222
 
# File 'lib/stripe/resources/checkout/session.rb', line 4220

def expires_at
  @expires_at
end

#id ⇒ Object (readonly)

Unique identifier for the object.



4222
4223
4224
 
# File 'lib/stripe/resources/checkout/session.rb', line 4222

def id
  @id
end

#invoice ⇒ Object (readonly)

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



4224
4225
4226
 
# File 'lib/stripe/resources/checkout/session.rb', line 4224

def invoice
  @invoice
end

#invoice_creation ⇒ Object (readonly)

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



4226
4227
4228
 
# File 'lib/stripe/resources/checkout/session.rb', line 4226

def invoice_creation
  @invoice_creation
end

#line_items ⇒ Object (readonly)

The line items purchased by the customer.



4228
4229
4230
 
# File 'lib/stripe/resources/checkout/session.rb', line 4228

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.



4230
4231
4232
 
# File 'lib/stripe/resources/checkout/session.rb', line 4230

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.



4232
4233
4234
 
# File 'lib/stripe/resources/checkout/session.rb', line 4232

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.



4234
4235
4236
 
# File 'lib/stripe/resources/checkout/session.rb', line 4234

def metadata
  @metadata
end

#mode ⇒ Object (readonly)

The mode of the Checkout Session.



4236
4237
4238
 
# File 'lib/stripe/resources/checkout/session.rb', line 4236

def mode
  @mode
end

#object ⇒ Object (readonly)

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



4238
4239
4240
 
# File 'lib/stripe/resources/checkout/session.rb', line 4238

def object
  @object
end

#optional_items ⇒ Object (readonly)

The optional items presented to the customer at checkout.



4240
4241
4242
 
# File 'lib/stripe/resources/checkout/session.rb', line 4240

def optional_items
  @optional_items
end

#origin_context ⇒ Object (readonly)

Where the user is coming from. This informs the optimizations that are applied to the session.



4242
4243
4244
 
# File 'lib/stripe/resources/checkout/session.rb', line 4242

def origin_context
  @origin_context
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.



4244
4245
4246
 
# File 'lib/stripe/resources/checkout/session.rb', line 4244

def payment_intent
  @payment_intent
end

#payment_link ⇒ Object (readonly)

The ID of the Payment Link that created this Session.



4246
4247
4248
 
# File 'lib/stripe/resources/checkout/session.rb', line 4246

def payment_link
  @payment_link
end

#payment_method_collection ⇒ Object (readonly)

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



4248
4249
4250
 
# File 'lib/stripe/resources/checkout/session.rb', line 4248

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.



4250
4251
4252
 
# File 'lib/stripe/resources/checkout/session.rb', line 4250

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.



4252
4253
4254
 
# File 'lib/stripe/resources/checkout/session.rb', line 4252

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.



4255
4256
4257
 
# File 'lib/stripe/resources/checkout/session.rb', line 4255

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.



4258
4259
4260
 
# File 'lib/stripe/resources/checkout/session.rb', line 4258

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`.



4262
4263
4264
 
# File 'lib/stripe/resources/checkout/session.rb', line 4262

def permissions
  @permissions
end

#phone_number_collection ⇒ Object (readonly)

Attribute for field phone_number_collection



4264
4265
4266
 
# File 'lib/stripe/resources/checkout/session.rb', line 4264

def phone_number_collection
  @phone_number_collection
end

#presentment_details ⇒ Object (readonly)

Attribute for field presentment_details



4266
4267
4268
 
# File 'lib/stripe/resources/checkout/session.rb', line 4266

def presentment_details
  @presentment_details
end

#recovered_from ⇒ Object (readonly)

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



4268
4269
4270
 
# File 'lib/stripe/resources/checkout/session.rb', line 4268

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`.



4270
4271
4272
 
# File 'lib/stripe/resources/checkout/session.rb', line 4270

def redirect_on_completion
  @redirect_on_completion
end

#return_url ⇒ Object (readonly)

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



4272
4273
4274
 
# File 'lib/stripe/resources/checkout/session.rb', line 4272

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.



4274
4275
4276
 
# File 'lib/stripe/resources/checkout/session.rb', line 4274

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.



4276
4277
4278
 
# File 'lib/stripe/resources/checkout/session.rb', line 4276

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.



4278
4279
4280
 
# File 'lib/stripe/resources/checkout/session.rb', line 4278

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.



4280
4281
4282
 
# File 'lib/stripe/resources/checkout/session.rb', line 4280

def shipping_cost
  @shipping_cost
end

#shipping_options ⇒ Object (readonly)

The shipping rate options applied to this Session.



4282
4283
4284
 
# File 'lib/stripe/resources/checkout/session.rb', line 4282

def shipping_options
  @shipping_options
end

#status ⇒ Object (readonly)

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



4284
4285
4286
 
# File 'lib/stripe/resources/checkout/session.rb', line 4284

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.



4288
4289
4290
 
# File 'lib/stripe/resources/checkout/session.rb', line 4288

def submit_type
  @submit_type
end

#subscription ⇒ Object (readonly)

The ID of the [Subscription](stripe.com/docs/api/subscriptions) for Checkout Sessions in ‘subscription` mode.



4290
4291
4292
 
# File 'lib/stripe/resources/checkout/session.rb', line 4290

def subscription
  @subscription
end

#success_url ⇒ Object (readonly)

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



4293
4294
4295
 
# File 'lib/stripe/resources/checkout/session.rb', line 4293

def success_url
  @success_url
end

#tax_id_collection ⇒ Object (readonly)

Attribute for field tax_id_collection



4295
4296
4297
 
# File 'lib/stripe/resources/checkout/session.rb', line 4295

def tax_id_collection
  @tax_id_collection
end

#total_details ⇒ Object (readonly)

Tax and discount details for the computed total amount.



4297
4298
4299
 
# File 'lib/stripe/resources/checkout/session.rb', line 4297

def total_details
  @total_details
end

#ui_mode ⇒ Object (readonly)

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



4299
4300
4301
 
# File 'lib/stripe/resources/checkout/session.rb', line 4299

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.



4302
4303
4304
 
# File 'lib/stripe/resources/checkout/session.rb', line 4302

def url
  @url
end

#wallet_options ⇒ Object (readonly)

Wallet-specific configuration for this Checkout Session.



4304
4305
4306
 
# File 'lib/stripe/resources/checkout/session.rb', line 4304

def wallet_options
  @wallet_options
end

Class Method Details

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

Creates a Checkout Session object.



4309
4310
4311
4312
4313
4314
4315
4316
 
# File 'lib/stripe/resources/checkout/session.rb', line 4309

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.



4333
4334
4335
4336
4337
4338
4339
4340
 
# File 'lib/stripe/resources/checkout/session.rb', line 4333

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.



4343
4344
4345
4346
4347
4348
4349
4350
 
# File 'lib/stripe/resources/checkout/session.rb', line 4343

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.



4363
4364
4365
4366
4367
4368
4369
4370
 
# File 'lib/stripe/resources/checkout/session.rb', line 4363

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.

Related guide: [Dynamically update Checkout](docs.stripe.com/payments/checkout/dynamic-updates)



4375
4376
4377
4378
4379
4380
4381
4382
 
# File 'lib/stripe/resources/checkout/session.rb', line 4375

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.



4321
4322
4323
4324
4325
4326
4327
4328
 
# File 'lib/stripe/resources/checkout/session.rb', line 4321

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.



4353
4354
4355
4356
4357
4358
4359
4360
 
# File 'lib/stripe/resources/checkout/session.rb', line 4353

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