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, CurrencyConversion, CustomField, CustomText, CustomerDetails, InvoiceCreation, PaymentMethodConfigurationDetails, PaymentMethodOptions, Permissions, PhoneNumberCollection, SavedPaymentMethodOptions, ShippingAddressCollection, ShippingCost, ShippingDetails, ShippingOption, TaxIdCollection, TotalDetails

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



392
393
394
 
# File 'lib/stripe/resources/checkout/session.rb', line 392

def adaptive_pricing
  @adaptive_pricing
end

#after_expiration ⇒ Object (readonly)

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



394
395
396
 
# File 'lib/stripe/resources/checkout/session.rb', line 394

def after_expiration
  @after_expiration
end

#allow_promotion_codes ⇒ Object (readonly)

Enables user redeemable promotion codes.



396
397
398
 
# File 'lib/stripe/resources/checkout/session.rb', line 396

def allow_promotion_codes
  @allow_promotion_codes
end

#amount_subtotal ⇒ Object (readonly)

Total of all items before discounts or taxes are applied.



398
399
400
 
# File 'lib/stripe/resources/checkout/session.rb', line 398

def amount_subtotal
  @amount_subtotal
end

#amount_total ⇒ Object (readonly)

Total of all items after discounts and taxes are applied.



400
401
402
 
# File 'lib/stripe/resources/checkout/session.rb', line 400

def amount_total
  @amount_total
end

#automatic_tax ⇒ Object (readonly)

Attribute for field automatic_tax



402
403
404
 
# File 'lib/stripe/resources/checkout/session.rb', line 402

def automatic_tax
  @automatic_tax
end

#billing_address_collection ⇒ Object (readonly)

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



404
405
406
 
# File 'lib/stripe/resources/checkout/session.rb', line 404

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.



406
407
408
 
# File 'lib/stripe/resources/checkout/session.rb', line 406

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.



410
411
412
 
# File 'lib/stripe/resources/checkout/session.rb', line 410

def client_reference_id
  @client_reference_id
end

#client_secret ⇒ Object (readonly)

The client secret of the Session. Use this with [initCheckout](stripe.com/docs/js/custom_checkout/init) on your front end.



412
413
414
 
# File 'lib/stripe/resources/checkout/session.rb', line 412

def client_secret
  @client_secret
end

#collected_information ⇒ Object (readonly)

Information about the customer collected within the Checkout Session.



414
415
416
 
# File 'lib/stripe/resources/checkout/session.rb', line 414

def collected_information
  @collected_information
end

#consent ⇒ Object (readonly)

Results of ‘consent_collection` for this session.



416
417
418
 
# File 'lib/stripe/resources/checkout/session.rb', line 416

def consent
  @consent
end

#consent_collection ⇒ Object (readonly)

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



418
419
420
 
# File 'lib/stripe/resources/checkout/session.rb', line 418

def consent_collection
  @consent_collection
end

#created ⇒ Object (readonly)

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



420
421
422
 
# File 'lib/stripe/resources/checkout/session.rb', line 420

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



422
423
424
 
# File 'lib/stripe/resources/checkout/session.rb', line 422

def currency
  @currency
end

#currency_conversion ⇒ Object (readonly)

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



424
425
426
 
# File 'lib/stripe/resources/checkout/session.rb', line 424

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.



426
427
428
 
# File 'lib/stripe/resources/checkout/session.rb', line 426

def custom_fields
  @custom_fields
end

#custom_text ⇒ Object (readonly)

Attribute for field custom_text



428
429
430
 
# File 'lib/stripe/resources/checkout/session.rb', line 428

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.



434
435
436
 
# File 'lib/stripe/resources/checkout/session.rb', line 434

def customer
  @customer
end

#customer_creation ⇒ Object (readonly)

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



436
437
438
 
# File 'lib/stripe/resources/checkout/session.rb', line 436

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.



438
439
440
 
# File 'lib/stripe/resources/checkout/session.rb', line 438

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.



444
445
446
 
# File 'lib/stripe/resources/checkout/session.rb', line 444

def customer_email
  @customer_email
end

#expires_at ⇒ Object (readonly)

The timestamp at which the Checkout Session will expire.



446
447
448
 
# File 'lib/stripe/resources/checkout/session.rb', line 446

def expires_at
  @expires_at
end

#id ⇒ Object (readonly)

Unique identifier for the object.



448
449
450
 
# File 'lib/stripe/resources/checkout/session.rb', line 448

def id
  @id
end

#invoice ⇒ Object (readonly)

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



450
451
452
 
# File 'lib/stripe/resources/checkout/session.rb', line 450

def invoice
  @invoice
end

#invoice_creation ⇒ Object (readonly)

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



452
453
454
 
# File 'lib/stripe/resources/checkout/session.rb', line 452

def invoice_creation
  @invoice_creation
end

#line_items ⇒ Object (readonly)

The line items purchased by the customer.



454
455
456
 
# File 'lib/stripe/resources/checkout/session.rb', line 454

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.



456
457
458
 
# File 'lib/stripe/resources/checkout/session.rb', line 456

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.



458
459
460
 
# File 'lib/stripe/resources/checkout/session.rb', line 458

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.



460
461
462
 
# File 'lib/stripe/resources/checkout/session.rb', line 460

def metadata
  @metadata
end

#mode ⇒ Object (readonly)

The mode of the Checkout Session.



462
463
464
 
# File 'lib/stripe/resources/checkout/session.rb', line 462

def mode
  @mode
end

#object ⇒ Object (readonly)

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



464
465
466
 
# File 'lib/stripe/resources/checkout/session.rb', line 464

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



466
467
468
 
# File 'lib/stripe/resources/checkout/session.rb', line 466

def payment_intent
  @payment_intent
end

#payment_link ⇒ Object (readonly)

The ID of the Payment Link that created this Session.



468
469
470
 
# File 'lib/stripe/resources/checkout/session.rb', line 468

def payment_link
  @payment_link
end

#payment_method_collection ⇒ Object (readonly)

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



470
471
472
 
# File 'lib/stripe/resources/checkout/session.rb', line 470

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.



472
473
474
 
# File 'lib/stripe/resources/checkout/session.rb', line 472

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.



474
475
476
 
# File 'lib/stripe/resources/checkout/session.rb', line 474

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.



477
478
479
 
# File 'lib/stripe/resources/checkout/session.rb', line 477

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.



480
481
482
 
# File 'lib/stripe/resources/checkout/session.rb', line 480

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



484
485
486
 
# File 'lib/stripe/resources/checkout/session.rb', line 484

def permissions
  @permissions
end

#phone_number_collection ⇒ Object (readonly)

Attribute for field phone_number_collection



486
487
488
 
# File 'lib/stripe/resources/checkout/session.rb', line 486

def phone_number_collection
  @phone_number_collection
end

#recovered_from ⇒ Object (readonly)

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



488
489
490
 
# File 'lib/stripe/resources/checkout/session.rb', line 488

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



490
491
492
 
# File 'lib/stripe/resources/checkout/session.rb', line 490

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.



492
493
494
 
# File 'lib/stripe/resources/checkout/session.rb', line 492

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.



494
495
496
 
# File 'lib/stripe/resources/checkout/session.rb', line 494

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.



496
497
498
 
# File 'lib/stripe/resources/checkout/session.rb', line 496

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.



498
499
500
 
# File 'lib/stripe/resources/checkout/session.rb', line 498

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.



500
501
502
 
# File 'lib/stripe/resources/checkout/session.rb', line 500

def shipping_cost
  @shipping_cost
end

#shipping_details ⇒ Object (readonly)

Shipping information for this Checkout Session.



502
503
504
 
# File 'lib/stripe/resources/checkout/session.rb', line 502

def shipping_details
  @shipping_details
end

#shipping_options ⇒ Object (readonly)

The shipping rate options applied to this Session.



504
505
506
 
# File 'lib/stripe/resources/checkout/session.rb', line 504

def shipping_options
  @shipping_options
end

#status ⇒ Object (readonly)

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



506
507
508
 
# File 'lib/stripe/resources/checkout/session.rb', line 506

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.



510
511
512
 
# File 'lib/stripe/resources/checkout/session.rb', line 510

def submit_type
  @submit_type
end

#subscription ⇒ Object (readonly)

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



512
513
514
 
# File 'lib/stripe/resources/checkout/session.rb', line 512

def subscription
  @subscription
end

#success_url ⇒ Object (readonly)

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



515
516
517
 
# File 'lib/stripe/resources/checkout/session.rb', line 515

def success_url
  @success_url
end

#tax_id_collection ⇒ Object (readonly)

Attribute for field tax_id_collection



517
518
519
 
# File 'lib/stripe/resources/checkout/session.rb', line 517

def tax_id_collection
  @tax_id_collection
end

#total_details ⇒ Object (readonly)

Tax and discount details for the computed total amount.



519
520
521
 
# File 'lib/stripe/resources/checkout/session.rb', line 519

def total_details
  @total_details
end

#ui_mode ⇒ Object (readonly)

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



521
522
523
 
# File 'lib/stripe/resources/checkout/session.rb', line 521

def ui_mode
  @ui_mode
end

#url ⇒ Object (readonly)

The URL to the Checkout Session. 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.



524
525
526
 
# File 'lib/stripe/resources/checkout/session.rb', line 524

def url
  @url
end

Class Method Details

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

Creates a Session object.



527
528
529
530
531
532
533
534
 
# File 'lib/stripe/resources/checkout/session.rb', line 527

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 Session can be expired when it is in one of these statuses: open

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



551
552
553
554
555
556
557
558
 
# File 'lib/stripe/resources/checkout/session.rb', line 551

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(filters = {}, opts = {}) ⇒ Object

Returns a list of Checkout Sessions.



561
562
563
564
565
566
567
568
 
# File 'lib/stripe/resources/checkout/session.rb', line 561

def self.list(filters = {}, opts = {})
  request_stripe_object(
    method: :get,
    path: "/v1/checkout/sessions",
    params: filters,
    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.



581
582
583
584
585
586
587
588
 
# File 'lib/stripe/resources/checkout/session.rb', line 581

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(id, params = {}, opts = {}) ⇒ Object

Updates a Session object.



591
592
593
594
595
596
597
598
 
# File 'lib/stripe/resources/checkout/session.rb', line 591

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

Instance Method Details

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

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

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



539
540
541
542
543
544
545
546
 
# File 'lib/stripe/resources/checkout/session.rb', line 539

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.



571
572
573
574
575
576
577
578
 
# File 'lib/stripe/resources/checkout/session.rb', line 571

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