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



3932
3933
3934
 
# File 'lib/stripe/resources/checkout/session.rb', line 3932

def adaptive_pricing
  @adaptive_pricing
end

#after_expiration ⇒ Object (readonly)

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



3934
3935
3936
 
# File 'lib/stripe/resources/checkout/session.rb', line 3934

def after_expiration
  @after_expiration
end

#allow_promotion_codes ⇒ Object (readonly)

Enables user redeemable promotion codes.



3936
3937
3938
 
# File 'lib/stripe/resources/checkout/session.rb', line 3936

def allow_promotion_codes
  @allow_promotion_codes
end

#amount_subtotal ⇒ Object (readonly)

Total of all items before discounts or taxes are applied.



3938
3939
3940
 
# File 'lib/stripe/resources/checkout/session.rb', line 3938

def amount_subtotal
  @amount_subtotal
end

#amount_total ⇒ Object (readonly)

Total of all items after discounts and taxes are applied.



3940
3941
3942
 
# File 'lib/stripe/resources/checkout/session.rb', line 3940

def amount_total
  @amount_total
end

#automatic_tax ⇒ Object (readonly)

Attribute for field automatic_tax



3942
3943
3944
 
# File 'lib/stripe/resources/checkout/session.rb', line 3942

def automatic_tax
  @automatic_tax
end

#billing_address_collection ⇒ Object (readonly)

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



3944
3945
3946
 
# File 'lib/stripe/resources/checkout/session.rb', line 3944

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.



3946
3947
3948
 
# File 'lib/stripe/resources/checkout/session.rb', line 3946

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.



3950
3951
3952
 
# File 'lib/stripe/resources/checkout/session.rb', line 3950

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.



3953
3954
3955
 
# File 'lib/stripe/resources/checkout/session.rb', line 3953

def client_secret
  @client_secret
end

#collected_information ⇒ Object (readonly)

Information about the customer collected within the Checkout Session.



3955
3956
3957
 
# File 'lib/stripe/resources/checkout/session.rb', line 3955

def collected_information
  @collected_information
end

#consent ⇒ Object (readonly)

Results of ‘consent_collection` for this session.



3957
3958
3959
 
# File 'lib/stripe/resources/checkout/session.rb', line 3957

def consent
  @consent
end

#consent_collection ⇒ Object (readonly)

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



3959
3960
3961
 
# File 'lib/stripe/resources/checkout/session.rb', line 3959

def consent_collection
  @consent_collection
end

#created ⇒ Object (readonly)

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



3961
3962
3963
 
# File 'lib/stripe/resources/checkout/session.rb', line 3961

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



3963
3964
3965
 
# File 'lib/stripe/resources/checkout/session.rb', line 3963

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.



3965
3966
3967
 
# File 'lib/stripe/resources/checkout/session.rb', line 3965

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.



3967
3968
3969
 
# File 'lib/stripe/resources/checkout/session.rb', line 3967

def custom_fields
  @custom_fields
end

#custom_text ⇒ Object (readonly)

Attribute for field custom_text



3969
3970
3971
 
# File 'lib/stripe/resources/checkout/session.rb', line 3969

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.



3975
3976
3977
 
# File 'lib/stripe/resources/checkout/session.rb', line 3975

def customer
  @customer
end

#customer_account ⇒ Object (readonly)

The ID of the account for this Session.



3977
3978
3979
 
# File 'lib/stripe/resources/checkout/session.rb', line 3977

def 
  @customer_account
end

#customer_creation ⇒ Object (readonly)

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



3979
3980
3981
 
# File 'lib/stripe/resources/checkout/session.rb', line 3979

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.



3981
3982
3983
 
# File 'lib/stripe/resources/checkout/session.rb', line 3981

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.



3987
3988
3989
 
# File 'lib/stripe/resources/checkout/session.rb', line 3987

def customer_email
  @customer_email
end

#discounts ⇒ Object (readonly)

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



3989
3990
3991
 
# File 'lib/stripe/resources/checkout/session.rb', line 3989

def discounts
  @discounts
end

#expires_at ⇒ Object (readonly)

The timestamp at which the Checkout Session will expire.



3991
3992
3993
 
# File 'lib/stripe/resources/checkout/session.rb', line 3991

def expires_at
  @expires_at
end

#id ⇒ Object (readonly)

Unique identifier for the object.



3993
3994
3995
 
# File 'lib/stripe/resources/checkout/session.rb', line 3993

def id
  @id
end

#invoice ⇒ Object (readonly)

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



3995
3996
3997
 
# File 'lib/stripe/resources/checkout/session.rb', line 3995

def invoice
  @invoice
end

#invoice_creation ⇒ Object (readonly)

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



3997
3998
3999
 
# File 'lib/stripe/resources/checkout/session.rb', line 3997

def invoice_creation
  @invoice_creation
end

#line_items ⇒ Object (readonly)

The line items purchased by the customer.



3999
4000
4001
 
# File 'lib/stripe/resources/checkout/session.rb', line 3999

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.



4001
4002
4003
 
# File 'lib/stripe/resources/checkout/session.rb', line 4001

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.



4003
4004
4005
 
# File 'lib/stripe/resources/checkout/session.rb', line 4003

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.



4005
4006
4007
 
# File 'lib/stripe/resources/checkout/session.rb', line 4005

def metadata
  @metadata
end

#mode ⇒ Object (readonly)

The mode of the Checkout Session.



4007
4008
4009
 
# File 'lib/stripe/resources/checkout/session.rb', line 4007

def mode
  @mode
end

#object ⇒ Object (readonly)

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



4009
4010
4011
 
# File 'lib/stripe/resources/checkout/session.rb', line 4009

def object
  @object
end

#optional_items ⇒ Object (readonly)

The optional items presented to the customer at checkout.



4011
4012
4013
 
# File 'lib/stripe/resources/checkout/session.rb', line 4011

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.



4013
4014
4015
 
# File 'lib/stripe/resources/checkout/session.rb', line 4013

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.



4015
4016
4017
 
# File 'lib/stripe/resources/checkout/session.rb', line 4015

def payment_intent
  @payment_intent
end

#payment_link ⇒ Object (readonly)

The ID of the Payment Link that created this Session.



4017
4018
4019
 
# File 'lib/stripe/resources/checkout/session.rb', line 4017

def payment_link
  @payment_link
end

#payment_method_collection ⇒ Object (readonly)

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



4019
4020
4021
 
# File 'lib/stripe/resources/checkout/session.rb', line 4019

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.



4021
4022
4023
 
# File 'lib/stripe/resources/checkout/session.rb', line 4021

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.



4023
4024
4025
 
# File 'lib/stripe/resources/checkout/session.rb', line 4023

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.



4026
4027
4028
 
# File 'lib/stripe/resources/checkout/session.rb', line 4026

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.



4029
4030
4031
 
# File 'lib/stripe/resources/checkout/session.rb', line 4029

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



4033
4034
4035
 
# File 'lib/stripe/resources/checkout/session.rb', line 4033

def permissions
  @permissions
end

#phone_number_collection ⇒ Object (readonly)

Attribute for field phone_number_collection



4035
4036
4037
 
# File 'lib/stripe/resources/checkout/session.rb', line 4035

def phone_number_collection
  @phone_number_collection
end

#presentment_details ⇒ Object (readonly)

Attribute for field presentment_details



4037
4038
4039
 
# File 'lib/stripe/resources/checkout/session.rb', line 4037

def presentment_details
  @presentment_details
end

#recovered_from ⇒ Object (readonly)

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



4039
4040
4041
 
# File 'lib/stripe/resources/checkout/session.rb', line 4039

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



4041
4042
4043
 
# File 'lib/stripe/resources/checkout/session.rb', line 4041

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.



4043
4044
4045
 
# File 'lib/stripe/resources/checkout/session.rb', line 4043

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.



4045
4046
4047
 
# File 'lib/stripe/resources/checkout/session.rb', line 4045

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.



4047
4048
4049
 
# File 'lib/stripe/resources/checkout/session.rb', line 4047

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.



4049
4050
4051
 
# File 'lib/stripe/resources/checkout/session.rb', line 4049

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.



4051
4052
4053
 
# File 'lib/stripe/resources/checkout/session.rb', line 4051

def shipping_cost
  @shipping_cost
end

#shipping_options ⇒ Object (readonly)

The shipping rate options applied to this Session.



4053
4054
4055
 
# File 'lib/stripe/resources/checkout/session.rb', line 4053

def shipping_options
  @shipping_options
end

#status ⇒ Object (readonly)

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



4055
4056
4057
 
# File 'lib/stripe/resources/checkout/session.rb', line 4055

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.



4059
4060
4061
 
# File 'lib/stripe/resources/checkout/session.rb', line 4059

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.



4061
4062
4063
 
# File 'lib/stripe/resources/checkout/session.rb', line 4061

def subscription
  @subscription
end

#success_url ⇒ Object (readonly)

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



4064
4065
4066
 
# File 'lib/stripe/resources/checkout/session.rb', line 4064

def success_url
  @success_url
end

#tax_id_collection ⇒ Object (readonly)

Attribute for field tax_id_collection



4066
4067
4068
 
# File 'lib/stripe/resources/checkout/session.rb', line 4066

def tax_id_collection
  @tax_id_collection
end

#total_details ⇒ Object (readonly)

Tax and discount details for the computed total amount.



4068
4069
4070
 
# File 'lib/stripe/resources/checkout/session.rb', line 4068

def total_details
  @total_details
end

#ui_mode ⇒ Object (readonly)

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



4070
4071
4072
 
# File 'lib/stripe/resources/checkout/session.rb', line 4070

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.



4073
4074
4075
 
# File 'lib/stripe/resources/checkout/session.rb', line 4073

def url
  @url
end

#wallet_options ⇒ Object (readonly)

Wallet-specific configuration for this Checkout Session.



4075
4076
4077
 
# File 'lib/stripe/resources/checkout/session.rb', line 4075

def wallet_options
  @wallet_options
end

Class Method Details

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

Creates a Checkout Session object.



4078
4079
4080
4081
4082
4083
4084
4085
 
# File 'lib/stripe/resources/checkout/session.rb', line 4078

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.



4102
4103
4104
4105
4106
4107
4108
4109
 
# File 'lib/stripe/resources/checkout/session.rb', line 4102

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.



4112
4113
4114
4115
4116
4117
4118
4119
 
# File 'lib/stripe/resources/checkout/session.rb', line 4112

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.



4132
4133
4134
4135
4136
4137
4138
4139
 
# File 'lib/stripe/resources/checkout/session.rb', line 4132

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)



4144
4145
4146
4147
4148
4149
4150
4151
 
# File 'lib/stripe/resources/checkout/session.rb', line 4144

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.



4090
4091
4092
4093
4094
4095
4096
4097
 
# File 'lib/stripe/resources/checkout/session.rb', line 4090

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.



4122
4123
4124
4125
4126
4127
4128
4129
 
# File 'lib/stripe/resources/checkout/session.rb', line 4122

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