Create a checkout session
You can create a checkout session through the checkout sessions API. This API will return an object with a payment page URL and many other associated details, using which you can receive funds from your customer.
Speed allows you to collect certain additional details about your customers on the payment page, like their email, phone number, billing, and shipping address. If so, the customer needs to provide them in order for the QR to be shown to them before the payment is processed. You can set the preference to “true” while creating the checkout session.
Speed also provides you with the option to split the payments you receive from your customers among several other existing Speed accounts using transfers. The payment amount is transferred to numerous accounts based on the percentage indicated for each account while creating the checkout session. This eliminates the need to manually transfer funds to other accounts upon receiving a payment and helps to simplify financial management.
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 with 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
Let's learn how to use the checkout sessions API.
Case : 1 You choose the amount for your customer to pay
As per our existing functionality, you can make a POST /checkout session request specifying the following mandatory parameters:
amount
,currency
You can also include other optional parameters like statement descriptor
, title
, title_description
, title_image
,customer_collections_status
and transfers
of the resource to make it more informative and engaging for customers.
In this example below, we'll show you how you can create a checkout session for your customer on a purchase of 200 USD.
Request
{
"amount": 200,
"currency": "USD",
"title": "Donation",
"title_description": "Joy of giving",
"title_image": "https://234778.fs1.hubspotusercontent.net/hubfs/277/office-600x400.jpg",
"transfers": [
{
"destination_account": "acct_xxxxxxxxxxxx",
"percentage": 50.00,
"description": "tr-1"
},
{
"destination_account": "acct_xxxxxxxxxxxx",
"percentage": 50.00,
"description": "tr-2"
}
],
"customer_collections_status":
{
"is_phone_enabled": true,
"is_email_enabled": false,
"is_billing_address_enabled":true,
"is_shipping_address_enabled":true
}
}
Case : 2 Your customer chooses what amount to pay
Let's look at how to utilize the checkout sessions API when you want your consumers to choose how much they wish to spend.
There are further three unique types you may pick from under the "customers choose what to pay" option,
-
Any amount: This type gives your customers full freedom to decide how much they want to pay. The initial amount specified for this option by you will be always set to zero, giving customers the flexibility to decide the payment value that suits them best.
Note:
- While specifying this parameter, there is no need to specify the type explicitly, as it by default system to set required type on its own.
- It doesn’t matter which currency you have selected for this case.
{
"amount": 0,
"currency": "USD",
"title": "Choose any amount to pay",
"title_description": "Looking for donation of any amount from you",
"title_image": "https://xyz.com/images/sampleimage.jpg"
}
-
Options: If you’ve set the “type = options," you can offer your customers a selection of up to maximum three payment amount options. Later this will allow your customers to choose from a predefined list of payment values, making the process convenient and efficient.
Note:
- The field "amount" must have any one value from the predefined values listed in the "options" parameter. It will serve as the default amount displayed on the customer's payment page and then your customer can choose any different value.
{
"amount": 50,
"currency": "USD",
"type": "options",
"options": [10,50,100], //mutually exclusive with preset
"title": "Donation",
"title_description": "Joy of giving",
"title_image": "https://xyz.com/images/sampleimage.jpg"
}
- Preset: When the “type = preset," you need to specify a value in “amount” field as a default value to be shown to your customer on payment page to pay. You can provide a range also by providing a minimum and maximum amount under “preset” field.
Initially, the default amount shown on the payment page will be the amount you've defined, later your customers can change it and pay any amount that falls within the specified range.
It means your customers will pay within this range, giving them a bit more flexibility while still ensuring that the payment falls within the limits you've defined.
{
"amount": 50,
"currency": "USD",
"type": "preset",
"preset":
{
"min_amount":10,
"max_amount":100
}, //mutually exclusive with options
"title": "Donation",
"title_description": "Joy of giving",
"title_image": "https://xyz.com/images/sampleimage.jpg"
}
Request parameters
Provide the basic information outlined in the table below:
Parameter | Required | Type | Description |
---|---|---|---|
Amount | ✅ | BigDecimal | The total amount you intend to collect from the customer via the checkout session. 1. If you specify the amount, your customer is expected to pay, the amount value should be greater than zero. 2. If you allow your customer to choose what they would like to pay, then you need to set the type to either preset or options. |
Currency | ✅ | String | The currency your prefer (fiat or cryptocurrency) to create a checkout session. |
Target_currency | String | The cryptocurrency in which you want to receive funds from your customer. As of now, Speed only supports SATS. | |
Statement descriptor | String | It describes the purpose of payment. Keep this text brief and to the point. | |
Payment_methods | Enum | Version 2022-10-15 supports both on-chain and lightning payment methods. Use this parameter to mention which payment method you want; lightning or on-chain. Additionally, you can also create a checkout session for both. The API response for the payment resource varies depending on the payment method(s) that have been selected within the Speed web application. | |
Ttl | Integer | Represents the time duration to which the checkout session’s payment has not expired. (Specified in seconds). You can manually add the expiration time in seconds. The minimum time limit is 5 minutes, and the maximum is 1 year. The default is 600 seconds for fiat currencies and 1 year for cryptocurrency. (SATS) | |
type | String | This parameter allows the user to specify the preferred payment method for customers. 1. If you want your customer to make payment of a fixed amount, no need to specify the type explicitly, you just need to specify the “amount”. 2. If you want your customer to choose what to pay then you need to set the type to either "options" or "preset". | |
options | Array of integers | If you’ve set the "type=options" you must provide this field wherein you can offer your customers a selection of up to three payment amount options. | |
preset | decimal | If you’ve set the "type=preset" you can specify a minimum and maximum payment amount for your customers in this field and then they'll pay only within this range.min_amount : The customer must pay an amount equal to or greater than the value specified in this parameter.max_amount : This parameter prevents payments greater than the specified value. | |
Success_url | String | When the payment is successfully done, you can use this parameter to redirect the customer to your hosted page. | |
Cancel_url | String | When a payment is cancelled, you can use this parameter to redirect the customer to any page you want. | |
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)) | |
transfers | List | To associate a transfer with checkout session, you need to pass below parameters: • Destination account - This can be any existing Speed account ID that would receive the transferred amount upon payment. • Percentage - This represents the proportion of the payment that the destination account will receive. • Description - This is the additional information about the transfer. It is an optional field. | |
customer_collections_status | Object | You can use this object to decide if either email, phone number , shipping or billing address is required before processing the payment. You have to pass these options as true if you wish to collect them from the customer. The options goes as- 1. is_phone_enabled - If you wish to collect customer’s phone number. 2. is_email_enabled - If you wish to collect customer’s email. 3. is_billing_address_enabled - If you wish to collect customer’s billing address. 4. is_shipping_address_enabled - If you wish to collect customer’s shipping address. | |
Title | String | You can use this parameter to add the header or title to your payment page. | |
Tiltle_description | String | You can use this parameter to provide a brief description of your payment page. | |
Title_image | String | You can include a related image illustrating the purpose of a payment page along with the title and description. Image size must not be more than 2 MB. | |
Metadata | Object | You can use this object to store additional information in key value pairs about the checkout link object in a structured format. You can add up to 50 key-value pairs in a raw JSON format. | |
Cashback | Object | You can use this parameter to associate an active cashback with a checkout session. |
If optional parameters are not specified, then the checkout session object will be generated without them.
Request headers
Parameter | Required | Type | Description |
---|---|---|---|
speed-version | string | As of now, there are two versions (2022-04-15 and 2022-10-15). Version 2022-10-15 supports both on-chain and lightning payment methods. Whereas the 2022-04-15 version only supports lightning payments. In the parameter speed-version, you can specify any version you want. |
More information can be found in our API reference.
Response
{
"id": "cs_xxxxxxxxxxxxxxxxxx",
"object": "checkout_session",
"livemode": false,
"status": "active",
"default_url": null,
"url": null,
"currency": "USD",
"amount": 50,
"target_currency": "SATS",
"ttl": 600,
"payment_methods": [
"onchain",
"lightning"
],
"type": "options",
"options":[10,50,100],
"preset":
{
"min_amount":null,
"max_amount":null
},
"statement_descriptor": null,
"description": null,
"success_url": null,
"cancel_url": null,
"amount_paid": null,
"target_amount_paid": null,
"payments": [],
"title": "Donation",
"title_description": "Joy of giving",
"title_image": "https://23477318.fs1.hubspotusercontent-na1.net/hubfs/23477/office-600x400.jpg",
"source": null,
"source_id": null,
"amount_paid_tolerance": 1.0,
"customer_collections_status":
{
"is_phone_enabled": true,
"is_email_enabled": false,
"is_billing_address_enabled": true,
"is_shipping_address_enabled": true
},
"transfers": [
{
"destination_account": "acct_l2g0gpa4Rly3UA",
"percentage": 50.0,
"description": "tr-1"
},
{
"destination_account": "acct_lmgf36es242v5f",
"percentage": 50.0,
"description": "tr-1"
}
],
"created": 1677145114654,
"modified": 1677145114654
}
Your 2022-10-15
response contains the following attributes:
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. Values up to 32 digits can be handled by the amount param, which can have a decimal precision up to 16 digits.
target_currency string
The cryptocurrency in which you want to receive payment from your customer. As of now, Speed only supports SATS.
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.
type string
This attribute specifies the preferred payment method for customers. It can be anyone of “fixed” (set by system), "options" or "preset".
- preset
- This attribute specifies min_amount and max_amount for your customers, ensuring that the payment falls within the limits you've defined.
- options
- This allows the customers to choose from a predefined list of payment values, making the process convenient and efficient.
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))
customer_collections_status object
This object represents whether you have chosen to collect the email, phone number, billing, and shipping address. Set it as “true” if you wish to collect it from the customer.
transfers list
You may use this to trigger a transfer of funds to one or more Speed accounts when your customers pay you.
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.
created timestamp
Time at which the checkout session was created.
modified timestamp
Time at which the last modification was made.
Updated 23 days ago