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, and a list of details that can be collected from the customer, such as shipping address, billing address, email, and phone number.

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 with Transfers

Speed now provides you with the option to split the payments you receive from your customers among several other existing Speed accounts. This eliminates the need to manually transfer funds to other accounts upon payment, and it also helps to simplify financial management. You need to define the following fields while creating a checkout session to do so:

Destination account: Enter the ID of the existing speed account to which you want to transfer the defined percentage of the payment received. Make sure it is not your own account ID.
Percentage: Enter the percentage of the received payment for the checkout session that you want to send to the destination account. It should be greater than 0 and less than 100%.
- The total of percentage of all the accounts (in case of multiple accounts) must be less than or equal to 100%
- System to initiate the transfer after deducting Speed and other fees (as applicable, for example, affiliate partner fees).

📝
Consider the following example:

Checkout session is created for 10,000 SATS. There are 2 transfers associated with the checkout session, with percentages of 10% and 25%.

Payment is made of 10,000 SATS. Consider the speed fee to be 1%. Hence, the transfers generated in both accounts will be of the remaining amount of 10,000 - 1% of 10,000 = 9,900 SATS.

The system initiates transfer - 1 of 10% on 9,900 = 990 SATS

The system then initiates transfer - 2 of 25% on 9,900 = 2,475 SATS.

Hence, the account that has received payment for the checkout session of 10,000 SATS will be credited with (10000 - 100 - 990 - 2475) = 6435 SATS

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.

💡
For a checkout session created with payment_method = onchain, when a payment is marked as paid (i.e., payment received for the same or any amount) and later another payment is received on the same on-chain address, the system will inherit the transfer properties of the original/earlier payment and initiate transfers when further payments are received.

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.

Retrieving a checkout session

Additionally, you may always retrieve a checkout session. The checkout session can be obtained via the API after it has been formed.

Retrieve a checkout session by payment ID

You can retrieve checkout session details through this API using its payment ID. These details include the email, phone number, billing address, and shipping address that your customers submitted on the payment page.

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 and deactivating, updating, retrieving and retrieving the checkout session by payment ID. Additionally, subscribe to webhook events to receive instant notifications.

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.