The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Net-API-Stripe-v2.0.4
River stage one • 1 direct dependent • 1 total dependent
3 ++
/ Net::API::Stripe::Checkout::Session

NAME

Net::API::Stripe::Checkout::Session - A Stripe Checkout Session Object

SYNOPSIS

    my $session = $stripe->session({
        # This easy to implement with Net::API::REST
        cancel_url => 'https://api.example.com/v1/stripe/cancel',
        success_url => 'https://api.example.com/v1/stripe/success',
        client_reference_id => '1F7F749C-D9C9-46EB-B692-986628BD7302',
        customer => $customer_object,
        customer_email => 'john.doe@example.com',
        # Japanese please
        locale => 'ja',
        mode => 'subscription',
        payment_intent => $payment_intent_object,
        submit_type => 'pay',
        subscription => $subscription_object,
    });

VERSION

    v0.102.0

DESCRIPTION

A Checkout Session represents your customer's session as they pay for one-time purchases or subscriptions through Checkout (https://stripe.com/docs/payments/checkout). Stripe recommends 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 (Net::API::Stripe::Customer / https://stripe.com/docs/api/customers), and either the successful PaymentIntent (Net::API::Stripe::Payment::Intent / https://stripe.com/docs/api/payment_intents) or an active Subscription (Net::API::Stripe::Billing::Subscription / https://stripe.com/docs/api/subscriptions).

You can create a Checkout Session on your server and pass its ID to the client to begin Checkout.

CONSTRUCTOR

new

Creates a new Net::API::Stripe::Checkout::Session object.

METHODS

id string

Unique identifier for the object. Used to pass to redirectToCheckout in Stripe.js.

object string, value is "checkout.session"

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

after_expiration hash

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

recovery
allow_promotion_codes boolean

Enables user redeemable promotion codes on the recovered Checkout Sessions. Defaults to false

enabled boolean

If true, a recovery url will be generated to recover this Checkout Session if it expires before a transaction is completed. It will be attached to the Checkout Session object upon expiration.

expires_at timestamp

The timestamp at which the recovery URL will expire.

url string

URL that creates a new Checkout Session when clicked that is a copy of this expired Checkout Session

allow_promotion_codes boolean

Enables user redeemable promotion codes.

amount_subtotal integer

Total of all items before discounts or taxes are applied.

amount_total integer

Total of all items after discounts and taxes are applied.

automatic_tax hash

Details on the state of automatic tax for the session, including the status of the latest tax calculation.

enabled boolean

Indicates whether automatic tax is enabled for the session

status enum

The status of the most recent automated tax calculation for this session.

Possible enum values

requires_location_inputs

The location details entered by the customer aren’t valid or don’t provide enough location information to accurately determine tax rates.

complete

Stripe successfully calculated tax automatically for this session.

failed

The Stripe Tax service failed.

billing_address_collection string

The value (auto or required) for whether Checkout collected the customer’s billing address.

cancel_url string

The URL the customer will be directed to if they decide to cancel payment and return to your website.

This is a URI object.

client_reference_id string

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.

Results of consent_collection for this session.

promotions string

If opt_in, the customer consents to receiving promotional communications from the merchant about this Checkout Session.

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

promotions string

If set to auto, enables the collection of customer consent for promotional communications. The Checkout Session will determine whether to display an option to opt into promotional communication from the merchant depending on the customer’s locale. Only available to US merchants.

currency currency

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

customer string (expandable)

The ID of the customer for this session. For Checkout Sessions in payment or subscription mode, Checkout will create a new customer object based on information provided during the session unless an existing customer was provided when the session was created.

When expanded, this is a Net::API::Stripe::Customer object.

customer_creation enum

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

if_required

The Checkout Session will only create a Customer if it is required for Session confirmation. Currently, only subscription mode Sessions require a Customer.

always

The Checkout Session will always create a Customer when a Session confirmation is attempted.

customer_details object

The customer details including the customer's tax exempt status and the customer's tax IDs. Only the customer's email is present on Sessions in setup mode.

This is a Net::API::Stripe::Customer object.

customer_email string

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 a session is complete, use the customer field.

display_items array of hashes

The line items, plans, or SKUs purchased by the customer.

This is an array of Net::API::Stripe::Checkout::Item objects.

expires_at timestamp

The timestamp at which the Checkout Session will expire.

interval string

One of day, week, month or year. The frequency with which a subscription should be billed.

interval_count positive integer

The number of intervals (specified in the interval property) between subscription billings. For example, interval=month and interval_count=3 bills every 3 months.

livemode boolean

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

locale string

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

metadata hash

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.

mode string

The mode of the Checkout Session, one of payment, setup, or subscription.

payment_intent string (expandable)

The ID of the PaymentIntent for Checkout Sessions in payment mode. If it is expanded, it contains a Net::API::Stripe::Payment::Intent object.

payment_intent_data object

A subset of parameters to be passed to PaymentIntent creation for Checkout Sessions in payment mode.

This is a Net::API::Stripe::Payment::Intent object and used to create a checkout session.

The ID of the Payment Link that created this Session.

When expanded, it contains a Net::API::Stripe::Payment::Link object.

payment_method_collection string

Configure whether a Checkout Session should collect a payment method.

payment_method_options hash

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

acss_debit hash

If the Checkout Session’s payment_method_types includes acss_debit, this hash contains the configurations that will be applied to each payment attempt of that type.

currency enum

Currency supported by the bank account. Returned when the Session is in setup mode.

cad

Canadian dollars

usd

US dollars

mandate_options hash

Additional fields for Mandate creation

custom_mandate_url string

A URL for custom mandate text

default_for array of enum values

List of Stripe products where this mandate can be selected automatically. Returned when the Session is in setup mode.

Possible enum values

invoice

Enables payments for Stripe Invoices. subscription must also be provided.

subscription

Enables payments for Stripe Subscriptions. invoice must also be provided.

interval_description string

Description of the interval. Only required if the payment_schedule parameter is interval or combined.

payment_schedule enum

Payment schedule for the mandate.

Possible enum values

interval

Payments are initiated at a regular pre-defined interval

sporadic

Payments are initiated sporadically

combined

Payments can be initiated at a pre-defined interval or sporadically

transaction_type enum

Transaction type of the mandate.

Possible enum values

personal

Transactions are made for personal reasons

business

Transactions are made for business reasons

verification_method enum

Bank account verification method.

automatic

Instant verification with fallback to microdeposits.

instant

Instant verification.

microdeposits

Verification using microdeposits.

boleto hash

If the Checkout Session’s payment_method_types includes boleto, this hash contains the configurations that will be applied to each payment attempt of that type.

expires_after_days integer

The number of calendar days before a Boleto voucher expires. For example, if you create a Boleto voucher on Monday and you set expires_after_days to 2, the Boleto voucher will expire on Wednesday at 23:59 America/Sao_Paulo time.

oxxo hash

If the Checkout Session’s payment_method_types includes oxxo, this hash contains the configurations that will be applied to each payment attempt of that type.

expires_after_days integer

The number of calendar days before an OXXO invoice expires. For example, if you create an OXXO invoice on Monday and you set expires_after_days to 2, the OXXO invoice will expire on Wednesday at 23:59 America/Mexico_City time.

payment_method_types array containing strings

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

payment_status string

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.

phone_number_collection hash

Details on the state of phone number collection for the session.

enabled boolean

Indicates whether phone number collection is enabled for the session

recovered_from string

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

setup_intent string (expandable)

The ID of the SetupIntent for Checkout Sessions in setup mode.

When expanded, this is a Net::API::Stripe::Payment::Intent object.

setup_intent_data object

A subset of parameters to be passed to SetupIntent creation for Checkout Sessions in setup mode.

This is a Net::API::Stripe::Payment::Intent object and used to create a checkout session.

shipping object

Shipping information for this Checkout Session.

This is a Net::API::Stripe::Shipping object.

It has the following properties:

address object

Shipping address.

This is a Net::API::Stripe::Address object.

name string

Recipient name.

shipping_address_collection hash

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

It has the following properties:

allowed_countries array

An array of two-letter ISO country codes representing which countries Checkout should provide as options for shipping locations. Unsupported country codes: AS, CX, CC, CU, HM, IR, KP, MH, FM, NF, MP, PW, SD, SY, UM, VI.

shipping_cost object

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

This is a Net::API::Stripe::Checkout::Session object.

shipping_details object

Shipping information for this Checkout Session.

This is a Net::API::Stripe::Billing::Details object.

shipping_options array of hashes

The shipping rate options applied to this Session.

shipping_amount integer

A non-negative integer in cents representing how much to charge.

shipping_rate string expandable

The shipping rate.

shipping_rate string expandable

The ID of the ShippingRate for Checkout Sessions in payment mode.

status enum

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

Possible enum values

open

The checkout session is still in progress. Payment processing has not started

complete

The checkout session is complete. Payment processing may still be in progress

expired

The checkout session has expired. No further processing will occur

submit_type string

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, but not Checkout Sessions in subscription or setup mode. Supported values are auto, book, donate, or pay.

subscription string (expandable)

The ID of the subscription for Checkout Sessions in subscription mode. If it is expanded, this is the Net::API::Stripe::Billing::Subscription object.

subscription_data object

A subset of parameters to be passed to subscription creation for Checkout Sessions in subscription mode.

This is a Net::API::Stripe::Billing::Subscription object and used to create a checkout session.

success_url string

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

tax_id_collection hash

Details on the state of tax ID collection for the session.

Hide child attributes

enabled boolean

Indicates whether tax ID collection is enabled for the session

total_details hash

Tax and discount details for the computed total amount.

It has the following properties:

amount_discount integer

This is the sum of all the line item discounts.

amount_shipping integer

This is the sum of all the line item shipping amounts.

amount_tax integer

This is the sum of all the line item tax amounts.

breakdown hash

Breakdown of individual tax and discount amounts that add up to the totals.

discounts array

The aggregated line item discounts.

amount integer

The amount discounted.

discount hash

The discount applied.

taxes array

The aggregated line item tax amounts by rate.

amount integer

Amount of tax applied for this rate.

rate hash

The tax rate applied.

When expanded, this is a Net::API::Stripe::Tax::Rate object.

url string

The URL to the Checkout Session.

API SAMPLE

    {
      "id": "cs_test_ksjfkjfkljslfkjlfkflsfklskflskflskfs",
      "object": "checkout.session",
      "billing_address_collection": null,
      "cancel_url": "https://example.com/cancel",
      "client_reference_id": null,
      "customer": null,
      "customer_email": null,
      "display_items": [
        {
          "amount": 1500,
          "currency": "usd",
          "custom": {
            "description": "Comfortable cotton t-shirt",
            "images": null,
            "name": "T-shirt"
          },
          "quantity": 2,
          "type": "custom"
        }
      ],
      "livemode": false,
      "locale": null,
      "mode": null,
      "payment_intent": "pi_fake123456789",
      "payment_method_types": [
        "card"
      ],
      "setup_intent": null,
      "submit_type": null,
      "subscription": null,
      "success_url": "https://example.com/success"
    }

HISTORY

v0.1

Initial version

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

Stripe API documentation:

https://stripe.com/docs/api/checkout/sessions, https://stripe.com/docs/payments/checkout/api

COPYRIGHT & LICENSE

Copyright (c) 2019-2020 DEGUEST Pte. Ltd.

You can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself.