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



3699
3700
3701
 
# File 'lib/stripe/resources/checkout/session.rb', line 3699

def adaptive_pricing
  @adaptive_pricing
end

#after_expiration ⇒ Object (readonly)

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



3701
3702
3703
 
# File 'lib/stripe/resources/checkout/session.rb', line 3701

def after_expiration
  @after_expiration
end

#allow_promotion_codes ⇒ Object (readonly)

Enables user redeemable promotion codes.



3703
3704
3705
 
# File 'lib/stripe/resources/checkout/session.rb', line 3703

def allow_promotion_codes
  @allow_promotion_codes
end

#amount_subtotal ⇒ Object (readonly)

Total of all items before discounts or taxes are applied.



3705
3706
3707
 
# File 'lib/stripe/resources/checkout/session.rb', line 3705

def amount_subtotal
  @amount_subtotal
end

#amount_total ⇒ Object (readonly)

Total of all items after discounts and taxes are applied.



3707
3708
3709
 
# File 'lib/stripe/resources/checkout/session.rb', line 3707

def amount_total
  @amount_total
end

#automatic_tax ⇒ Object (readonly)

Attribute for field automatic_tax



3709
3710
3711
 
# File 'lib/stripe/resources/checkout/session.rb', line 3709

def automatic_tax
  @automatic_tax
end

#billing_address_collection ⇒ Object (readonly)

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



3711
3712
3713
 
# File 'lib/stripe/resources/checkout/session.rb', line 3711

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.



3713
3714
3715
 
# File 'lib/stripe/resources/checkout/session.rb', line 3713

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.



3717
3718
3719
 
# File 'lib/stripe/resources/checkout/session.rb', line 3717

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.



3720
3721
3722
 
# File 'lib/stripe/resources/checkout/session.rb', line 3720

def client_secret
  @client_secret
end

#collected_information ⇒ Object (readonly)

Information about the customer collected within the Checkout Session.



3722
3723
3724
 
# File 'lib/stripe/resources/checkout/session.rb', line 3722

def collected_information
  @collected_information
end

#consent ⇒ Object (readonly)

Results of ‘consent_collection` for this session.



3724
3725
3726
 
# File 'lib/stripe/resources/checkout/session.rb', line 3724

def consent
  @consent
end

#consent_collection ⇒ Object (readonly)

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



3726
3727
3728
 
# File 'lib/stripe/resources/checkout/session.rb', line 3726

def consent_collection
  @consent_collection
end

#created ⇒ Object (readonly)

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



3728
3729
3730
 
# File 'lib/stripe/resources/checkout/session.rb', line 3728

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



3730
3731
3732
 
# File 'lib/stripe/resources/checkout/session.rb', line 3730

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.



3732
3733
3734
 
# File 'lib/stripe/resources/checkout/session.rb', line 3732

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.



3734
3735
3736
 
# File 'lib/stripe/resources/checkout/session.rb', line 3734

def custom_fields
  @custom_fields
end

#custom_text ⇒ Object (readonly)

Attribute for field custom_text



3736
3737
3738
 
# File 'lib/stripe/resources/checkout/session.rb', line 3736

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.



3742
3743
3744
 
# File 'lib/stripe/resources/checkout/session.rb', line 3742

def customer
  @customer
end

#customer_account ⇒ Object (readonly)

The ID of the account for this Session.



3744
3745
3746
 
# File 'lib/stripe/resources/checkout/session.rb', line 3744

def 
  @customer_account
end

#customer_creation ⇒ Object (readonly)

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



3746
3747
3748
 
# File 'lib/stripe/resources/checkout/session.rb', line 3746

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.



3748
3749
3750
 
# File 'lib/stripe/resources/checkout/session.rb', line 3748

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.



3754
3755
3756
 
# File 'lib/stripe/resources/checkout/session.rb', line 3754

def customer_email
  @customer_email
end

#discounts ⇒ Object (readonly)

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



3756
3757
3758
 
# File 'lib/stripe/resources/checkout/session.rb', line 3756

def discounts
  @discounts
end

#expires_at ⇒ Object (readonly)

The timestamp at which the Checkout Session will expire.



3758
3759
3760
 
# File 'lib/stripe/resources/checkout/session.rb', line 3758

def expires_at
  @expires_at
end

#id ⇒ Object (readonly)

Unique identifier for the object.



3760
3761
3762
 
# File 'lib/stripe/resources/checkout/session.rb', line 3760

def id
  @id
end

#invoice ⇒ Object (readonly)

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



3762
3763
3764
 
# File 'lib/stripe/resources/checkout/session.rb', line 3762

def invoice
  @invoice
end

#invoice_creation ⇒ Object (readonly)

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



3764
3765
3766
 
# File 'lib/stripe/resources/checkout/session.rb', line 3764

def invoice_creation
  @invoice_creation
end

#line_items ⇒ Object (readonly)

The line items purchased by the customer.



3766
3767
3768
 
# File 'lib/stripe/resources/checkout/session.rb', line 3766

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.



3768
3769
3770
 
# File 'lib/stripe/resources/checkout/session.rb', line 3768

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.



3770
3771
3772
 
# File 'lib/stripe/resources/checkout/session.rb', line 3770

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.



3772
3773
3774
 
# File 'lib/stripe/resources/checkout/session.rb', line 3772

def metadata
  @metadata
end

#mode ⇒ Object (readonly)

The mode of the Checkout Session.



3774
3775
3776
 
# File 'lib/stripe/resources/checkout/session.rb', line 3774

def mode
  @mode
end

#object ⇒ Object (readonly)

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



3776
3777
3778
 
# File 'lib/stripe/resources/checkout/session.rb', line 3776

def object
  @object
end

#optional_items ⇒ Object (readonly)

The optional items presented to the customer at checkout.



3778
3779
3780
 
# File 'lib/stripe/resources/checkout/session.rb', line 3778

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.



3780
3781
3782
 
# File 'lib/stripe/resources/checkout/session.rb', line 3780

def payment_intent
  @payment_intent
end

#payment_link ⇒ Object (readonly)

The ID of the Payment Link that created this Session.



3782
3783
3784
 
# File 'lib/stripe/resources/checkout/session.rb', line 3782

def payment_link
  @payment_link
end

#payment_method_collection ⇒ Object (readonly)

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



3784
3785
3786
 
# File 'lib/stripe/resources/checkout/session.rb', line 3784

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.



3786
3787
3788
 
# File 'lib/stripe/resources/checkout/session.rb', line 3786

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.



3788
3789
3790
 
# File 'lib/stripe/resources/checkout/session.rb', line 3788

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.



3791
3792
3793
 
# File 'lib/stripe/resources/checkout/session.rb', line 3791

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.



3794
3795
3796
 
# File 'lib/stripe/resources/checkout/session.rb', line 3794

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



3798
3799
3800
 
# File 'lib/stripe/resources/checkout/session.rb', line 3798

def permissions
  @permissions
end

#phone_number_collection ⇒ Object (readonly)

Attribute for field phone_number_collection



3800
3801
3802
 
# File 'lib/stripe/resources/checkout/session.rb', line 3800

def phone_number_collection
  @phone_number_collection
end

#presentment_details ⇒ Object (readonly)

Attribute for field presentment_details



3802
3803
3804
 
# File 'lib/stripe/resources/checkout/session.rb', line 3802

def presentment_details
  @presentment_details
end

#recovered_from ⇒ Object (readonly)

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



3804
3805
3806
 
# File 'lib/stripe/resources/checkout/session.rb', line 3804

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



3806
3807
3808
 
# File 'lib/stripe/resources/checkout/session.rb', line 3806

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.



3808
3809
3810
 
# File 'lib/stripe/resources/checkout/session.rb', line 3808

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.



3810
3811
3812
 
# File 'lib/stripe/resources/checkout/session.rb', line 3810

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.



3812
3813
3814
 
# File 'lib/stripe/resources/checkout/session.rb', line 3812

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.



3814
3815
3816
 
# File 'lib/stripe/resources/checkout/session.rb', line 3814

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.



3816
3817
3818
 
# File 'lib/stripe/resources/checkout/session.rb', line 3816

def shipping_cost
  @shipping_cost
end

#shipping_options ⇒ Object (readonly)

The shipping rate options applied to this Session.



3818
3819
3820
 
# File 'lib/stripe/resources/checkout/session.rb', line 3818

def shipping_options
  @shipping_options
end

#status ⇒ Object (readonly)

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



3820
3821
3822
 
# File 'lib/stripe/resources/checkout/session.rb', line 3820

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.



3824
3825
3826
 
# File 'lib/stripe/resources/checkout/session.rb', line 3824

def submit_type
  @submit_type
end

#subscription ⇒ Object (readonly)

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



3826
3827
3828
 
# File 'lib/stripe/resources/checkout/session.rb', line 3826

def subscription
  @subscription
end

#success_url ⇒ Object (readonly)

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



3829
3830
3831
 
# File 'lib/stripe/resources/checkout/session.rb', line 3829

def success_url
  @success_url
end

#tax_id_collection ⇒ Object (readonly)

Attribute for field tax_id_collection



3831
3832
3833
 
# File 'lib/stripe/resources/checkout/session.rb', line 3831

def tax_id_collection
  @tax_id_collection
end

#total_details ⇒ Object (readonly)

Tax and discount details for the computed total amount.



3833
3834
3835
 
# File 'lib/stripe/resources/checkout/session.rb', line 3833

def total_details
  @total_details
end

#ui_mode ⇒ Object (readonly)

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



3835
3836
3837
 
# File 'lib/stripe/resources/checkout/session.rb', line 3835

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.



3838
3839
3840
 
# File 'lib/stripe/resources/checkout/session.rb', line 3838

def url
  @url
end

#wallet_options ⇒ Object (readonly)

Wallet-specific configuration for this Checkout Session.



3840
3841
3842
 
# File 'lib/stripe/resources/checkout/session.rb', line 3840

def wallet_options
  @wallet_options
end

Class Method Details

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

Creates a Checkout Session object.



3843
3844
3845
3846
3847
3848
3849
3850
 
# File 'lib/stripe/resources/checkout/session.rb', line 3843

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.



3867
3868
3869
3870
3871
3872
3873
3874
 
# File 'lib/stripe/resources/checkout/session.rb', line 3867

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.



3877
3878
3879
3880
3881
3882
3883
3884
 
# File 'lib/stripe/resources/checkout/session.rb', line 3877

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.



3897
3898
3899
3900
3901
3902
3903
3904
 
# File 'lib/stripe/resources/checkout/session.rb', line 3897

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.



3907
3908
3909
3910
3911
3912
3913
3914
 
# File 'lib/stripe/resources/checkout/session.rb', line 3907

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.



3855
3856
3857
3858
3859
3860
3861
3862
 
# File 'lib/stripe/resources/checkout/session.rb', line 3855

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.



3887
3888
3889
3890
3891
3892
3893
3894
 
# File 'lib/stripe/resources/checkout/session.rb', line 3887

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