Checkout session

The checkout/ payment link URL takes a customer to a payment page by creating a checkout session in the background. And this payment page, which contains information such as; a payment request (QR code) and branding details.

Each checkout session represents your customer's session while they pay. It has an associated payment, which can be used to track payments (full payment or multiple partial payments) made by a customer.

Creating a checkout session

A new checkout session is automatically created when a customer clicks on a checkout/payment link. Additionally, you can create a checkout session directly through the checkout sessions APIs. Once created, it will make an internal call to the payment API and obtain the payment request.

Please refer to create a checkout session for a step-by-step guide on implementing this.

Checkout session statuses

The checkout session is initially created with an active status and a payment request (QR code). Your customer can pay by scanning this QR code. When any amount of funds is transferred by the customer, the status of the checkout session’s payment changes to paid. Even if the payment made is partial, the status will change to paid. However, the checkout session’s status changes to paid only when full payment with tolerance is received.

The checkout session has an active status that will remain until it is deactivated or paid. As a result, the checkout session can have the following statuses, as shown below.

     active

          The checkout session is active after its generation until it is paid.

     paid

          The checkout session is marked paid once the full payment with tolerance is received.

     deactivated

           One can manually deactivate the checkout session if it is not required.

Updating a checkout session

You can also update a checkout session at any point. The metadata, description, success_url, cancel_url and success_message of a checkout session can be updated.

Deactivating a checkout session

A checkout session can be marked as “deactivate” in multiple ways, just like you can create a checkout session in various ways. If you want to deactivate a checkout session, you must do so before it is paid.

As of now, you can deactivate a checkout session associated with the checkout link or payment link by deactivating respective link through APIs or the Speed web application.

You can also deactivate a checkout session through the checkout session APIs; check this out. Once you deactivate a checkout session, the associated payment’s status changes to cancel.

The following are the checkout sessions API endpoints for creating, deactivating and updating checkout sessions. Additionally, subscribe to webhook events to receive instant notifications.

1. /checkout-session-create
2. /checkout-session-deactivate
3. /checkout-session-update

Use-cases it solves

The majority of the tasks of accepting payments on-chain or via the lightning network are completed by the checkout session. The API response for the payment resource varies depending on the payment method(s) that have been selected within the Speed web application. Some other additional use cases, listed below, are also dependent on the checkout session.

• Foundation of checkout and payment link:
  The checkout session is the reason behind the no-code options (checkout link and payment link), where you can generate a payment page with the web application.
  It handles multiple on-chain payments, exchange rates, and the expiration time for the checkout/payment link.
• Foundation of Plugins and Speed.js:
  Speed plugins like Woocommerce or Speed.js help you get paid in bitcoins directly from your website or application. These plugins and Speed.js use checkout sessions to generate payment pages and receive payment for your orders.