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.

Let's learn how to use the checkout sessions API.

Use the /checkout-sessions endpoint and basic details such as amount, currency, payment_methods, target currency, statement descriptor, and others to create a checkout session object. In this example below, we'll show you how you can create a checkout session for your customer to send 200 USD.

Make a POST /checkout session request specifying the following mandatory parameters.

Request

{
  "amount": 200,
  "currency": "USD",
}

Request parameters

Provide the basic information outlined in the table below:

If optional parameters are not specified, then the checkout session object will be generated without them.

Request headers

More information can be found in our API reference.

Response

{
  "id": "cs_test_xxxxxxxxxxxxxx",
  "object": "checkout_session",
  "livemode": false,
  "status": "active",
  "default_url": null,
  "url": "https://checkout.tryspeed.com/pay/cs_test_xxxxxxxxxxxxxxxxxxxxx",
  "currency": "USD",
  "amount": 450.50,
  "target_currency": "SATS",
  "ttl": 31536000,
  "payment_methods": [
    "onchain",
    "lightning"
  ],
  "statement_descriptor": null,
  "description": null,
  "success_url": null,
  "cancel_url": null,
  "amount_paid": null,
  "target_amount_paid": null,
  "payments": [
    {
      "id": "pi_xxxxxxxxxxxxx",
      "module": "payment",
      "created": 1672056091072,
      "modified": 1672056091072,
      "amount_paid": 0.0505657529383032,
      "exchange_rate": 5932.8692359439210000,
      "target_amount_paid": 300
    }
  ],
  "source": null,
  "source_id": null,
  "metadata": {
    "key_1": "value_1",
    "key_2": "value_2"
  },
  "amount_paid_tolerance": 0.1,
  "created": 1669985420448,
  "modified": 1669985420448
}

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.

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 string
Unique identifier for the payment object.
module string
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 timestamp
Time at which this payment was created.
modified timestamp
Time at which the last modification was made.
amount_paid string
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 string
The exchange rate used to convert the currency(base currency) for this payment into target_currency.
target_amount_paid BigDecimal
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.

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))

created timestamp
Time at which the checkout session was created.

modified timestamp
Time at which the last modification was made.