Checkout Session

Checkout session for processing payments

  • id
    Type: string
    required

    Unique identifier for the checkout session

  • livemode
    Type: boolean
    required

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

  • mode
    Type: stringenum
    required

    The mode of the Checkout Session.

    values
    • payment

      Standard one-time payment.

    • setup

      Set up a payment method for future use.

    • subscription

      Coming soon. Not available yet.

  • payment_status
    Type: stringenum
    required

    The payment status of the Checkout Session, one of paid, unpaid, or no_payment_required.

    values
    • no_payment_required
    • processing
    • paid
    • unpaid
  • status
    Type: stringenum
    required

    The status of the Checkout Session.

    values
    • complete
    • expired
    • open
  • url
    Type: stringFormat: uri
    required

    URL where the customer can complete the payment.

  • after_completion
    Type: object

    After completion behavior for the Checkout Session.

    • hosted
      Type: object

      After completion behavior for the Checkout Session.

    • redirect
      Type: object

      After completion behavior for the Checkout Session.

    • type
      Type: stringenum

      After completion behavior for the Checkout Session.

      values
      • redirect
      • hosted_confirmation
  • amount_total
    Type: integerFormat: int64

    Total of all items after discounts and taxes are applied.

  • billing_address_collection
    Type: stringenum

    Specify whether Checkout should collect the customer's billing address. Defaults to auto.

    values
    • auto

      Checkout will only collect the billing address when necessary.

    • required

      Checkout will always collect the customer's billing address.

  • cancel_url
    Type: string | null

    URL customers can return to if they cancel payment.

  • client_customer_id
    Type: string | null

    An identifier of the customer in the merchant's system.

  • client_reference_id
    Type: string | null

    A free-form reference from the merchant's system.

  • currency
    Type: object

    Three-letter ISO currency code

    • iso
      Type: string
      required

      Three-letter ISO currency code

    • scale
      Type: integer
      required

      Number of decimal places for this currency

  • customer
    nullable

    Customer associated with the Checkout Session, if one exists.

    • Type: string · Customer ID
      max length:  
      100

      Customer associated with the Checkout Session, if one exists.

  • customer_creation
    Type: string | nullenum

    Customer creation behavior used during Session confirmation.

    values
    • always
    • if_required
  • customer_email
    Type: string | null

    Email address associated with the Checkout Session.

  • description
    Type: string | null

    A free-form reference that describes the checkout.

  • expires_at
    Type: string | nullFormat: date-time

    Expiry time for the checkout.

  • line_items
    Type: array object[] · LineItem[]

    Details about the products sold or services provided.

    • quantity
      Type: integerFormat: int64
      min:  
      1
      max:  
      10000000000
      required

      Quantity of the item

    • metadata

      Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

      Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

      • propertyName
        Type: string
    • price_data

      Prices define the unit cost, currency, and (optional) billing cycle for both recurring and one-time purchases of products. Products help you track inventory or provisioning, and prices help you track payment terms. Different physical goods or levels of service should be represented by products, and pricing options should be represented by prices. This approach lets you change prices without having to change your provisioning scheme. For example, you might have a single "gold" product that has prices for $10/month, $100/year, and €9 once.

      • active
        Type: boolean

        Whether the price can be used for new purchases.

      • billing_scheme
        Type: stringenum

        Describes how to compute the price per period. Either per_unit or tiered. per_unit indicates that the fixed amount (specified in unit_amount or unit_amount_decimal) will be charged per unit in quantity (for prices with usage_type=licensed), or per unit of total usage (for prices with usage_type=metered). tiered indicates that the unit pricing will be computed using a tiering strategy as defined using the tiers and tiers_mode attributes.

        values
        • per_unit
        • tiered
      • created
        Type: integerFormat: date-time nullable

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

      • currency
        Type: stringFormat: currency

        Three-letter ISO currency code, in lowercase. Must be a supported currency.

      • id
        Type: string
        max length:  
        5000

        Unique identifier for the object.

      • livemode
        Type: boolean

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

      • lookup_key
        Type: string | null
        max length:  
        5000

        A lookup key used to retrieve prices dynamically from a static string. This may be up to 200 characters.

      • product

        The ID of the product this price is associated with.

      • product_data
      • recurring
        Type: object · Recurring nullable

        The recurring components of a price such as interval and usage_type.

      • type
        Type: stringenum

        One of one_time or recurring depending on whether the price is for a one-time purchase or a recurring (subscription) purchase.

        values
        • one_time
        • recurring
      • unit_amount
        Type: integer | null

        The unit amount in cents (or local equivalent) to be charged, represented as a whole integer if possible. Only set if billing_scheme=per_unit.

      • unit_amount_decimal
        Type: string | nullFormat: decimal

        The unit amount in cents (or local equivalent) to be charged, represented as a decimal string with at most 12 decimal places. Only set if billing_scheme=per_unit.

  • locale
    Type: string | null

    The IETF language tag of the locale Checkout is displayed in.

  • metadata

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

    • propertyName
      Type: string
  • next_action
    Type: object · PaymentIntentNextAction
    • type
      Type: string
      max length:  
      100
      required

      Type of the next action to perform. Refer to the other child attributes under next_action for available values. Examples include: redirect_to_url or three_d_secure.

    • redirect_to_url
      Type: object · PaymentIntentNextActionRedirectToUrl
    • three_d_secure

      Provider-agnostic Three-D Secure next action. The flow field indicates whether no UI is needed (frictionless), a hidden device fingerprint (3DS Method) must run, or a visible challenge must be presented. All URLs are on your domain.

      • Type: object · PaymentIntentNextActionThreeDSecureFrictionless

        Provider-agnostic Three-D Secure next action. The flow field indicates whether no UI is needed (frictionless), a hidden device fingerprint (3DS Method) must run, or a visible challenge must be presented. All URLs are on your domain.

        • flow
          Discriminator
          Type: stringenum
          required

          Which 3DS flow to execute.

          values
          • frictionless
          • method
          • challenge
        • idempotency_key
          Type: string
          required

          Optional key to correlate retries/refreshes on the same 3DS attempt.

        • status_url
          Type: stringFormat: uri
          required

          Poll this URL (your API) until the PaymentIntent leaves requires_action/processing.

        • hint
          Type: object
        • message
          Type: object
        • return_url
          Type: string | nullFormat: uri

          Merchant's return URL (echoed back). Your 3DS return page should 302 here.

  • payment_intent
    nullable

    The PaymentIntent for Checkout Sessions in payment mode. It may be returned as an ID unless expanded.

    • Type: string · IntentId
      max length:  
      100

      The PaymentIntent for Checkout Sessions in payment mode. It may be returned as an ID unless expanded.

  • payment_link
    nullable

    The Payment Link that created this Session, if applicable.

    • Type: string · PaymentLinkId
      max length:  
      100

      The Payment Link that created this Session, if applicable.

  • payment_method_types
    Type: array string[]

    Payment method types this Checkout Session can accept.

  • return_url
    Type: string | null

    URL customers return to after redirect-based authentication.

  • saved_payment_method_options
    Type: object · SavedPaymentMethodOptions
    • payment_method_save
      Type: stringenum

      Controls whether the Payment Element displays a checkbox offering to save a new payment method. This parameter defaults to disabled.

      values
      • disabled
      • enabled
  • setup_intent
    nullable

    The SetupIntent for Checkout Sessions in setup mode.

    • Type: string · IntentId
      max length:  
      100

      The SetupIntent for Checkout Sessions in setup mode.

  • submit_type
    Type: string | nullenum

    Submit button text behavior used for Checkout Sessions in payment mode.

    values
    • auto
    • book
    • donate
    • pay
    • subscribe
  • success_url
    Type: string | null

    URL customers are sent to when payment or setup is complete.

  • ui_mode
    Type: stringenum

    The UI mode of the Session.

    values
    • custom
    • embedded
    • hosted
  • wallet_options
    Type: object
    • apple_pay
      Type: object
    • google_pay
      Type: object