A checkout session shows your customer's session while they pay via a one-time payment -- checkout link URL or a multi-time payment -- payment link URL. Each checkout link will generate only one checkout session, which will be marked as paid once its respective full payment with tolerance is received.
Speed provides the mechanism by which the merchant can choose to collect the shipping address, billing address, email, or phone number from the customer. Merchant can also collect specific details through customizable "custom_fields" where you can add "custom_fields" specifying any of the input types, i.e., text, number, or options. If so, the customer needs to provide them in order for the QR to be shown to them before the payment is processed. Merchant can set the preference to “true” while creating the checkout session. Whatever options the merchant chooses will become mandatory for the customer to add before processing the payment.
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).
A new checkout session is created when a customer clicks on a checkout/payment link. You can generate or create a checkout session in a variety of ways. Once created, it will make an internal call to the payment API to generate the QR payload and obtain the payment/checkout link URL. Upon successful creation of the session, the customer will be directed to the payment page. The checkout session status changes to paid when the full payment with tolerance is received.
{
"id": "cs_xxxxxxxxxxxx",
"object": "checkout_session",
"livemode": false,
"status": "active",
"default_url": "https://checkout.tryspeed.com/pay/cs_xxxxxxxxxxxx",
"url": "https://checkout.tryspeed.com/pay/cs_xxxxxxxxxxxx",
"currency": "SATS",
"amount": 100,
"target_currency": "SATS",
"ttl": 300,
"payment_methods": [
"onchain",
"lightning"
],
"type": "fixed",
"statement_descriptor": "cancel url test",
"description": null,
"success_message": null,
"success_url": null,
"cancel_url": null,
"amount_paid": null,
"target_amount_paid": null,
"payments": [],
"source": null,
"source_id": null,
"metadata": null,
"cashback": null,
"title": null,
"title_description": null,
"title_image": null,
"amount_paid_tolerance": 5,
"customer_collections_status": {
"is_phone_enabled": true,
"is_email_enabled": true,
"is_billing_address_enabled": true,
"is_shipping_address_enabled": false
},
"transfers": [
{
"destination_account": "acct_xxxxxxxxxxxx",
"percentage": 50.0,
"description": "tr-1"
},
{
"destination_account": "acct_xxxxxxxxxxxx",
"percentage": 50.0,
"description": "tr-1"
}
],
"custom_fields": [
{
"id": "cscf_xxxxxxxxxxxx",
"type": "dropdown",
"label": "state",
"options": [
"California",
"Texas",
"Florida"
],
"is_optional": false
},
{
"id": "cscf_xxxxxxxxxxxx",
"type": "number",
"label": "zip code",
"is_optional": false
},
{
"id": "cscf_xxxxxxxxxxxx",
"type": "text",
"label": "Will you by our product again?",
"is_optional": true
}
],
"created": 1697606132081,
"modified": 1697606132081
}
Attributes
id string
Unique identifier for the object.
object string
The type of the object indicates to which entity this response belongs.
livemode boolean
If the object is in live mode, it has the value true; otherwise, it has the value false.
status string
A checkout session can have 3 statuses as mentioned 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.
default_url string
The public URL with the Speed domain. This can be shared with customers to receive payments.
url string
The public URL with the default custom domain that you have set. This too can be shared with customers to receive payments. If you have not set a custom domain, URL with the Speed domain will be returned.
currency string
The base currency in which you prefer to work.
amount BigDecimal
The total amount for which the checkout session was created.
target_currency string
The cryptocurrency in which you want to receive payment from your customer. As of now, Speed only supports SATS.
type string
This attribute specifies the preferred payment method for customers. It can be one of the following, “fixed” (set by system), "options" or "preset".
preset object
This attribute specifies min_amount and max_amount for your customers, ensuring that the payment falls within the limits you've defined.
options array of strings
This allows the customers to choose from a predefined list of payment values, making the process convenient and efficient.
ttl integer
Represents the time duration until which the checkout session’s payment has not expired. (Specified in seconds)
payment_methods array of strings
Both on-chain and lightning network methods can be used to receive funds. This indicates whether the payment method available to make payment is lightning or on-chain. To ensure that you can receive both on-chain and lightning payments, remember to keep the “BTC On-chain” payment method enabled in payment methods in Speed web application.
statement_descriptor string
Additional information about a payment made to an account via this checkout session.
description string
Additional information about this checkout session.
success_url string
If the payment is successful, the customer will be redirected to this URL.
cancel_url string
If the customer decides to not pay, they will be redirected to this URL.
payments array of objects
This contains all payment objects and all associated information about each payment made through this checkout session. It is an array of either partial payment objects or a single full payment object.
- id
- Unique identifier for the payment object.
- module
- There are two types of module available: `pay request` and `payment`. This indicates whether the payment made was using a payment module or a pay request module.
- created Time at which this payment was created.
- modified
- Time at which the last modification was made.
- amount_paid There is a high possibility of receiving partial payments if the payment is made on-chain. Once any amount of funds are transferred, this returns the exact amount received in the base_currency.
- exchange_rate
- The exchange rate used to convert the currency(base currency) for this payment into target_currency.
- target_amount_paid
- Once any amount of funds are transferred, this returns the exact amount received in the target_currency.
source string
The source from which the checkout session is created is specified here. When it is not created by a plugin, this value is null.
source_id string
Unique identifier for the source object.
metadata object
You can use this to store additional information about the object in a structured format.
cashback object
You can use this parameter to associate an active cashback with a checkout session.
- id string
- Unique identifier for the cashback object.
amount_paid_tolerance BigDecimal
This is the tolerance level in percentage that you would like to set for your checkout session when partial on-chain payments are made. The default percentage for all Speed accounts is set at 1%, but you can specify a value between 0 and 5, with decimal precision of up to 2 digits. A checkout session will be marked as "PAID" once the payment received is greater than or equal to the due difference amount.
Due difference amount = checkout_session_amount - (checkout_session_amount _ (amount_paid_tolerance_0.01))
title string
This attribute represents the header or title of the payment page.
title_description string
This attribute represents additional information about your payment page.
title_image string
Represents a public URL consisting of an image illustrating the purpose of a payment page along with the title and description.
Users won't see the image on payment page if the image path is removed or deleted after the checkout session is created.
customer_collections_status object
This object represents the options that need to be filled by the customer before processing the payment. These options can be email, phone number, billing address, or shipping address.
- is_phone_enabled
- If true customer needs to provide a phone number before processing the payment.
- is_email_enabled
- If true customer needs to provide an email address before processing the payment.
- is_billing_address_enabled
- If true customer needs to provide a billing address before processing the payment.
- is_shipping_address_enabled
- If true customer needs to provide a shipping address before processing the payment.
transfers list
You may use this to trigger a transfer of funds to one or more existing Speed accounts when your customers pay you.
custom_fields array of objects
This attribute represents whether customize information from your customer needed or not during the payment process. Whether you need textual input, numerical data, or selections from a dropdown menu, this object empowers you to tailor the payment experience as per your unique requirement.
created timestamp
Time at which the checkout session was created.
modified timestamp
Time at which the last modification was made.