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

#==, #[], #[]=, #_get_inner_class_type, 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_pricingObject (readonly)

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



5076
5077
5078
# File 'lib/stripe/resources/checkout/session.rb', line 5076

def adaptive_pricing
  @adaptive_pricing
end

#after_expirationObject (readonly)

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



5078
5079
5080
# File 'lib/stripe/resources/checkout/session.rb', line 5078

def after_expiration
  @after_expiration
end

#allow_promotion_codesObject (readonly)

Enables user redeemable promotion codes.



5080
5081
5082
# File 'lib/stripe/resources/checkout/session.rb', line 5080

def allow_promotion_codes
  @allow_promotion_codes
end

#amount_subtotalObject (readonly)

Total of all items before discounts or taxes are applied.



5082
5083
5084
# File 'lib/stripe/resources/checkout/session.rb', line 5082

def amount_subtotal
  @amount_subtotal
end

#amount_totalObject (readonly)

Total of all items after discounts and taxes are applied.



5084
5085
5086
# File 'lib/stripe/resources/checkout/session.rb', line 5084

def amount_total
  @amount_total
end

#automatic_taxObject (readonly)

Attribute for field automatic_tax



5086
5087
5088
# File 'lib/stripe/resources/checkout/session.rb', line 5086

def automatic_tax
  @automatic_tax
end

#billing_address_collectionObject (readonly)

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



5088
5089
5090
# File 'lib/stripe/resources/checkout/session.rb', line 5088

def billing_address_collection
  @billing_address_collection
end

#cancel_urlObject (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.



5090
5091
5092
# File 'lib/stripe/resources/checkout/session.rb', line 5090

def cancel_url
  @cancel_url
end

#checkout_itemsObject (readonly)

Attribute for field checkout_items



5221
5222
5223
# File 'lib/stripe/resources/checkout/session.rb', line 5221

def checkout_items
  @checkout_items
end

#client_reference_idObject (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.



5094
5095
5096
# File 'lib/stripe/resources/checkout/session.rb', line 5094

def client_reference_id
  @client_reference_id
end

#client_secretObject (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.


5097
5098
5099
# File 'lib/stripe/resources/checkout/session.rb', line 5097

def client_secret
  @client_secret
end

#collected_informationObject (readonly)

Information about the customer collected within the Checkout Session.



5099
5100
5101
# File 'lib/stripe/resources/checkout/session.rb', line 5099

def collected_information
  @collected_information
end

Results of ‘consent_collection` for this session.



5101
5102
5103
# File 'lib/stripe/resources/checkout/session.rb', line 5101

def consent
  @consent
end

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



5103
5104
5105
# File 'lib/stripe/resources/checkout/session.rb', line 5103

def consent_collection
  @consent_collection
end

#createdObject (readonly)

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



5105
5106
5107
# File 'lib/stripe/resources/checkout/session.rb', line 5105

def created
  @created
end

#currencyObject (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).



5107
5108
5109
# File 'lib/stripe/resources/checkout/session.rb', line 5107

def currency
  @currency
end

#currency_conversionObject (readonly)

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



5109
5110
5111
# File 'lib/stripe/resources/checkout/session.rb', line 5109

def currency_conversion
  @currency_conversion
end

#custom_fieldsObject (readonly)

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



5111
5112
5113
# File 'lib/stripe/resources/checkout/session.rb', line 5111

def custom_fields
  @custom_fields
end

#custom_textObject (readonly)

Attribute for field custom_text



5113
5114
5115
# File 'lib/stripe/resources/checkout/session.rb', line 5113

def custom_text
  @custom_text
end

#customerObject (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.



5119
5120
5121
# File 'lib/stripe/resources/checkout/session.rb', line 5119

def customer
  @customer
end

#customer_accountObject (readonly)

The ID of the account for this Session.



5121
5122
5123
# File 'lib/stripe/resources/checkout/session.rb', line 5121

def 
  @customer_account
end

#customer_creationObject (readonly)

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



5123
5124
5125
# File 'lib/stripe/resources/checkout/session.rb', line 5123

def customer_creation
  @customer_creation
end

#customer_detailsObject (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.



5125
5126
5127
# File 'lib/stripe/resources/checkout/session.rb', line 5125

def customer_details
  @customer_details
end

#customer_emailObject (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.



5131
5132
5133
# File 'lib/stripe/resources/checkout/session.rb', line 5131

def customer_email
  @customer_email
end

#discountsObject (readonly)

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



5133
5134
5135
# File 'lib/stripe/resources/checkout/session.rb', line 5133

def discounts
  @discounts
end

#expires_atObject (readonly)

The timestamp at which the Checkout Session will expire.



5135
5136
5137
# File 'lib/stripe/resources/checkout/session.rb', line 5135

def expires_at
  @expires_at
end

#idObject (readonly)

Unique identifier for the object.



5137
5138
5139
# File 'lib/stripe/resources/checkout/session.rb', line 5137

def id
  @id
end

#invoiceObject (readonly)

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



5139
5140
5141
# File 'lib/stripe/resources/checkout/session.rb', line 5139

def invoice
  @invoice
end

#invoice_creationObject (readonly)

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



5141
5142
5143
# File 'lib/stripe/resources/checkout/session.rb', line 5141

def invoice_creation
  @invoice_creation
end

#line_itemsObject (readonly)

The line items purchased by the customer.



5143
5144
5145
# File 'lib/stripe/resources/checkout/session.rb', line 5143

def line_items
  @line_items
end

#livemodeObject (readonly)

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



5145
5146
5147
# File 'lib/stripe/resources/checkout/session.rb', line 5145

def livemode
  @livemode
end

#localeObject (readonly)

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



5147
5148
5149
# File 'lib/stripe/resources/checkout/session.rb', line 5147

def locale
  @locale
end

#metadataObject (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.



5149
5150
5151
# File 'lib/stripe/resources/checkout/session.rb', line 5149

def 
  @metadata
end

#modeObject (readonly)

The mode of the Checkout Session.



5151
5152
5153
# File 'lib/stripe/resources/checkout/session.rb', line 5151

def mode
  @mode
end

#objectObject (readonly)

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



5153
5154
5155
# File 'lib/stripe/resources/checkout/session.rb', line 5153

def object
  @object
end

#optional_itemsObject (readonly)

The optional items presented to the customer at checkout.



5155
5156
5157
# File 'lib/stripe/resources/checkout/session.rb', line 5155

def optional_items
  @optional_items
end

#origin_contextObject (readonly)

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



5157
5158
5159
# File 'lib/stripe/resources/checkout/session.rb', line 5157

def origin_context
  @origin_context
end

#payment_intentObject (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.



5159
5160
5161
# File 'lib/stripe/resources/checkout/session.rb', line 5159

def payment_intent
  @payment_intent
end

The ID of the Payment Link that created this Session.



5161
5162
5163
# File 'lib/stripe/resources/checkout/session.rb', line 5161

def payment_link
  @payment_link
end

#payment_method_collectionObject (readonly)

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



5163
5164
5165
# File 'lib/stripe/resources/checkout/session.rb', line 5163

def payment_method_collection
  @payment_method_collection
end

#payment_method_configuration_detailsObject (readonly)

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



5165
5166
5167
# File 'lib/stripe/resources/checkout/session.rb', line 5165

def payment_method_configuration_details
  @payment_method_configuration_details
end

#payment_method_optionsObject (readonly)

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



5167
5168
5169
# File 'lib/stripe/resources/checkout/session.rb', line 5167

def payment_method_options
  @payment_method_options
end

#payment_method_typesObject (readonly)

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



5170
5171
5172
# File 'lib/stripe/resources/checkout/session.rb', line 5170

def payment_method_types
  @payment_method_types
end

#payment_statusObject (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.



5173
5174
5175
# File 'lib/stripe/resources/checkout/session.rb', line 5173

def payment_status
  @payment_status
end

#permissionsObject (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`.



5177
5178
5179
# File 'lib/stripe/resources/checkout/session.rb', line 5177

def permissions
  @permissions
end

#phone_number_collectionObject (readonly)

Attribute for field phone_number_collection



5179
5180
5181
# File 'lib/stripe/resources/checkout/session.rb', line 5179

def phone_number_collection
  @phone_number_collection
end

#presentment_detailsObject (readonly)

Attribute for field presentment_details



5181
5182
5183
# File 'lib/stripe/resources/checkout/session.rb', line 5181

def presentment_details
  @presentment_details
end

#recovered_fromObject (readonly)

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



5183
5184
5185
# File 'lib/stripe/resources/checkout/session.rb', line 5183

def recovered_from
  @recovered_from
end

#redirect_on_completionObject (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`.



5185
5186
5187
# File 'lib/stripe/resources/checkout/session.rb', line 5185

def redirect_on_completion
  @redirect_on_completion
end

#return_urlObject (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.



5187
5188
5189
# File 'lib/stripe/resources/checkout/session.rb', line 5187

def return_url
  @return_url
end

#saved_payment_method_optionsObject (readonly)

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



5189
5190
5191
# File 'lib/stripe/resources/checkout/session.rb', line 5189

def saved_payment_method_options
  @saved_payment_method_options
end

#setup_intentObject (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.



5191
5192
5193
# File 'lib/stripe/resources/checkout/session.rb', line 5191

def setup_intent
  @setup_intent
end

#shipping_address_collectionObject (readonly)

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



5193
5194
5195
# File 'lib/stripe/resources/checkout/session.rb', line 5193

def shipping_address_collection
  @shipping_address_collection
end

#shipping_costObject (readonly)

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



5195
5196
5197
# File 'lib/stripe/resources/checkout/session.rb', line 5195

def shipping_cost
  @shipping_cost
end

#shipping_optionsObject (readonly)

The shipping rate options applied to this Session.



5197
5198
5199
# File 'lib/stripe/resources/checkout/session.rb', line 5197

def shipping_options
  @shipping_options
end

#statusObject (readonly)

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



5199
5200
5201
# File 'lib/stripe/resources/checkout/session.rb', line 5199

def status
  @status
end

#submit_typeObject (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.



5203
5204
5205
# File 'lib/stripe/resources/checkout/session.rb', line 5203

def submit_type
  @submit_type
end

#subscriptionObject (readonly)

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



5205
5206
5207
# File 'lib/stripe/resources/checkout/session.rb', line 5205

def subscription
  @subscription
end

#success_urlObject (readonly)

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



5208
5209
5210
# File 'lib/stripe/resources/checkout/session.rb', line 5208

def success_url
  @success_url
end

#tax_id_collectionObject (readonly)

Attribute for field tax_id_collection



5210
5211
5212
# File 'lib/stripe/resources/checkout/session.rb', line 5210

def tax_id_collection
  @tax_id_collection
end

#total_detailsObject (readonly)

Tax and discount details for the computed total amount.



5212
5213
5214
# File 'lib/stripe/resources/checkout/session.rb', line 5212

def total_details
  @total_details
end

#ui_modeObject (readonly)

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



5214
5215
5216
# File 'lib/stripe/resources/checkout/session.rb', line 5214

def ui_mode
  @ui_mode
end

#urlObject (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.



5217
5218
5219
# File 'lib/stripe/resources/checkout/session.rb', line 5217

def url
  @url
end

#wallet_optionsObject (readonly)

Wallet-specific configuration for this Checkout Session.



5219
5220
5221
# File 'lib/stripe/resources/checkout/session.rb', line 5219

def wallet_options
  @wallet_options
end

Class Method Details

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

Creates a Checkout Session object.



5224
5225
5226
5227
5228
5229
5230
5231
# File 'lib/stripe/resources/checkout/session.rb', line 5224

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.



5248
5249
5250
5251
5252
5253
5254
5255
# File 'lib/stripe/resources/checkout/session.rb', line 5248

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

.field_remappingsObject



5330
5331
5332
# File 'lib/stripe/resources/checkout/session.rb', line 5330

def self.field_remappings
  @field_remappings = {}
end

.inner_class_typesObject



5299
5300
5301
5302
5303
5304
5305
5306
5307
5308
5309
5310
5311
5312
5313
5314
5315
5316
5317
5318
5319
5320
5321
5322
5323
5324
5325
5326
5327
5328
# File 'lib/stripe/resources/checkout/session.rb', line 5299

def self.inner_class_types
  @inner_class_types = {
    adaptive_pricing: AdaptivePricing,
    after_expiration: AfterExpiration,
    automatic_tax: AutomaticTax,
    collected_information: CollectedInformation,
    consent: Consent,
    consent_collection: ConsentCollection,
    currency_conversion: CurrencyConversion,
    custom_fields: CustomField,
    custom_text: CustomText,
    customer_details: CustomerDetails,
    discounts: Discount,
    invoice_creation: InvoiceCreation,
    optional_items: OptionalItem,
    payment_method_configuration_details: PaymentMethodConfigurationDetails,
    payment_method_options: PaymentMethodOptions,
    permissions: Permissions,
    phone_number_collection: PhoneNumberCollection,
    presentment_details: PresentmentDetails,
    saved_payment_method_options: SavedPaymentMethodOptions,
    shipping_address_collection: ShippingAddressCollection,
    shipping_cost: ShippingCost,
    shipping_options: ShippingOption,
    tax_id_collection: TaxIdCollection,
    total_details: TotalDetails,
    wallet_options: WalletOptions,
    checkout_items: CheckoutItem,
  }
end

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

Returns a list of Checkout Sessions.



5258
5259
5260
5261
5262
5263
5264
5265
# File 'lib/stripe/resources/checkout/session.rb', line 5258

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.



5278
5279
5280
5281
5282
5283
5284
5285
# File 'lib/stripe/resources/checkout/session.rb', line 5278

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_nameObject



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)



5290
5291
5292
5293
5294
5295
5296
5297
# File 'lib/stripe/resources/checkout/session.rb', line 5290

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.



5236
5237
5238
5239
5240
5241
5242
5243
# File 'lib/stripe/resources/checkout/session.rb', line 5236

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.



5268
5269
5270
5271
5272
5273
5274
5275
# File 'lib/stripe/resources/checkout/session.rb', line 5268

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