Checkout Management
This guide describes how to create a checkout session and check it's payment status.
1. Create Checkout for a Single Payment
Initiate the checkout process for a single payment by calling the following endpoint:
Request Endpoint: reference
POST /checkout/sessions
Request Body:
Parameter | Type | Required | Description |
---|---|---|---|
line_items.price_data.product_data.name | string | ✅ | The name of the product to be displayed to your end-user. Such as “Ring NFT” |
line_items.price_data.unit_amount | integer | ✅ | Non-negative integer in cents representing the price of your product. |
line_items.price_data.currency | string | ✅ | Three-letter ISO currency code, in uppercase. |
line_items.quantity | integer | ✅ | The quantity of products you want to create a checkout for. |
success_url | string | ✅ | The URL where your user will be directed in case of successful checkout. (URLs must begin with http or https ) |
cancel_url | string | ✅ | The URL where your user will be directed in case they decide to cancel the payment. (URLs must begin with http or https ) |
mode | string | ✅ | Only "payment” mode is allowed. |
expires_at | Date-time | ❌ | The date-time at which the Checkout Session will expire. It can be set to expire anytime between 30 minutes to 24 hours after it's created. By default, it expires 24 hours after creation. This field accepts a date-time in ISO-8601 format. |
client_reference_id | string | ❌ | A distinctive identifier for the Checkout Session. This might be a customer ID, cart ID, or something similar, and can be utilized to match the session with your internal systems. |
customer.id | string | ❌ | The unique ID of your customer for whom this checkout request is being created. |
In this example, we are creating a checkout link for one Ring NFT with a value of €20. We have also specified the success and cancel URLs.
{
"line_items": [
{
"price_data": {
"product_data": {
"name": "Ring NFT"
},
"unit_amount": 2000,
"currency": "EUR"
},
"quantity": 1
}
],
"success_url": "https://www.venly.io/",
"cancel_url": "https://www.venly.io/",
"mode": "payment"
}
Response Body:
Save the following parameters from the response body:
id
: This parameter is the sessionId (Used when checking status of this checkout)url
: This parameter is the checkout URL (You pass this to your end-user)
{
"id": "cs_test_a1tpJvmnmcQtoBZmIR9jsTLNg07T8N6OgPLPdYJ9uwiE6I9JQqEcEmFFUf",
"object": "checkout.session",
"after_expiration": null,
"allow_promotion_codes": null,
"amount_subtotal": 2000,
"amount_total": 2000,
"automatic_tax": {
"enabled": false,
"status": null
},
"billing_address_collection": null,
"cancel_url": "https://www.venly.io/",
"client_reference_id": null,
"consent": null,
"consent_collection": null,
"created": 1692785133,
"currency": "eur",
"currency_conversion": null,
"custom_fields": [],
"custom_text": {
"shipping_address": null,
"submit": null
},
"customer": null,
"customer_creation": "if_required",
"customer_details": null,
"customer_email": null,
"expires_at": 1692871532,
"invoice": null,
"invoice_creation": {
"enabled": false,
"invoice_data": {
"account_tax_ids": null,
"custom_fields": null,
"description": null,
"footer": null,
"metadata": {},
"rendering_options": null
}
},
"livemode": false,
"locale": null,
"metadata": {},
"mode": "payment",
"payment_intent": null,
"payment_link": null,
"payment_method_collection": "always",
"payment_method_options": {},
"payment_method_types": [
"card"
],
"payment_status": "unpaid",
"phone_number_collection": {
"enabled": false
},
"recovered_from": null,
"setup_intent": null,
"shipping_address_collection": null,
"shipping_cost": null,
"shipping_details": null,
"shipping_options": [],
"status": "open",
"submit_type": null,
"subscription": null,
"success_url": "https://www.venly.io/",
"total_details": {
"amount_discount": 0,
"amount_shipping": 0,
"amount_tax": 0
},
"url": "https://checkout.stripe.com/c/pay/cs_test_a1tpJvmnmcQtoBZmIR9jsTLNg07T8N6OgPLPdYJ9uwiE6I9JQqEcEmFFUf#fid2cXdsdWBEZmZqcGtxJz8nZGZmcVo0S21cUGRGVmR%2FNUAxZEFyJyknZHVsTmB8Jz8ndW5acWB2cVowNE10Z3BQQ2FnSmxpVFVsX19gRFxATGZdTmZGTD18NHBmdktycDEydzFLbjx1VVVjSFJGYH9WcVJ9SjdcUG1mYk1qXWs0SVZ8M1VPcUEzZkRyV39IfFxVSzU1b1BIYG88M30nKSdjd2poVmB3c2B3Jz9xd3BgKSdpZHxqcHFRfHVgJz8ndmxrYmlgWmxxYGgnKSdga2RnaWBVaWRmYG1qaWFgd3YnP3F3cGB4JSUl"
}
2. Check the Status of a Checkout
To retrieve the details of a completed or canceled checkout, call this endpoint using the corresponding session ID:
Request Endpoint: reference
GET /checkout/sessions/{sessionId}
Path Parameter
{sessionId}: This is the session ID to check the status of a specific checkout payment. It’s in the response body when you create a checkout link.
Response Body:
Look for the following parameters in the response body:
Parameter | Possible Values & Description |
---|---|
payment_status | paid: The payment funds are available in your account. unpaid: The payment funds are not yet available in your account. |
status | open: The checkout session is still in progress. Payment processing has not started. complete: The checkout session is complete. Payment processing may still be in progress. expired: The checkout session has expired. No further processing will occur. |
payment_intent | The payment_intent object represents the actual payment transaction that needs to take place. It includes details about the amount, currency, payment method, etc. |
amount_total | The total sum of all items, factoring in applied discounts and taxes. |
payment_link | The payment_link object includes the checkout URL, data about the products being sold, and indicates whether the payment link’s URL is active. |
{
"id": "cs_test_a1cLJATpwDr0N5nfKSIk3VJDKMcEtOMGIZNwWf5nZ2v1EivlO6wIK5gY0f",
"object": "checkout.session",
"after_expiration": null,
"allow_promotion_codes": null,
"amount_subtotal": 2000,
"amount_total": 2000,
"automatic_tax": {
"enabled": false,
"status": null
},
"billing_address_collection": null,
"cancel_url": "https://www.venly.io/",
"client_reference_id": null,
"consent": null,
"consent_collection": null,
"created": 1692750644,
"currency": "eur",
"currency_conversion": null,
"custom_fields": [],
"custom_text": {
"shipping_address": null,
"submit": null
},
"customer": null,
"customer_creation": "if_required",
"customer_details": {
"address": {
"city": null,
"country": "PK",
"line1": null,
"line2": null,
"postal_code": null,
"state": null
},
"email": "[email protected]",
"name": "Stripe",
"phone": null,
"tax_exempt": "none",
"tax_ids": []
},
"customer_email": null,
"expires_at": 1692837044,
"invoice": null,
"invoice_creation": {
"enabled": false,
"invoice_data": {
"account_tax_ids": null,
"custom_fields": null,
"description": null,
"footer": null,
"metadata": {},
"rendering_options": null
}
},
"livemode": false,
"locale": null,
"metadata": {},
"mode": "payment",
"payment_intent": "pi_3Ni59PCSaz0E4aDw1hw6eAnw",
"payment_link": null,
"payment_method_collection": "always",
"payment_method_options": {},
"payment_method_types": [
"card"
],
"payment_status": "paid",
"phone_number_collection": {
"enabled": false
},
"recovered_from": null,
"setup_intent": null,
"shipping_address_collection": null,
"shipping_cost": null,
"shipping_details": null,
"shipping_options": [],
"status": "complete",
"submit_type": null,
"subscription": null,
"success_url": "https://www.venly.io/",
"total_details": {
"amount_discount": 0,
"amount_shipping": 0,
"amount_tax": 0
},
"url": null
}
3. Retrieve Line Items
To retrieve the details of line items of a specific checkout session, call this endpoint using the corresponding session ID:
Request Endpoint: reference
GET /checkout/sessions/{sessionId}/line_items
Path Parameter
{sessionId}: This is the session ID. It’s in the response body when you create a checkout link.
Response Body:
{
"success": true,
"result": {
"object": "list",
"data": [
{
"id": "li_1OPPr7FdbOilQPiZ19dCZvZR",
"object": "item",
"amount_discount": 0,
"amount_subtotal": 3000,
"amount_tax": 0,
"amount_total": 3000,
"currency": "eur",
"description": "Test Product",
"price": {
"id": "price_1OPPr7FdbOilQPiZf5ZZJvEP",
"object": "price",
"active": false,
"billing_scheme": "per_unit",
"created": 1703079037,
"currency": "eur",
"custom_unit_amount": null,
"livemode": false,
"lookup_key": null,
"metadata": {},
"nickname": null,
"product": "prod_PDraAFolOC5zVg",
"recurring": null,
"tax_behavior": "unspecified",
"tiers_mode": null,
"transform_quantity": null,
"type": "one_time",
"unit_amount": 3000,
"unit_amount_decimal": "3000"
},
"quantity": 1
}
],
"has_more": false,
"url": "/v1/checkout/sessions/cs_test_a14f5OdnVXD0sPY0Wsapi7YxLO0UJ1uY2kCxR3nXKtOq9qUjuJxs9gD94B/line_items"
}
}
Updated 3 months ago