Guides
Get API KeyStatusSupport

Checkout Management

This guide describes how to create a checkout session and check it's payment status.

Suggest Edits

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:

ParameterTypeRequiredDescription
line_items.price_data.product_data.namestring✅The name of the product to be displayed to your end-user. Such as “Ring NFT”
line_items.price_data.unit_amountinteger✅Non-negative integer in cents representing the price of your product.
line_items.price_data.currencystring✅Three-letter ISO currency code, in uppercase.
line_items.quantityinteger✅The quantity of products you want to create a checkout for.
success_urlstring✅The URL where your user will be directed in case of successful checkout. (URLs must begin with http or https)
cancel_urlstring✅The URL where your user will be directed in case they decide to cancel the payment. (URLs must begin with http or https)
modestring✅Only "payment” mode is allowed.
expires_atDate-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_idstring❌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.idstring❌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"
}

📘

Click here to read Stripe documentation for this endpoint.

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:

ParameterPossible Values & Description
payment_statuspaid: The payment funds are available in your account.

unpaid: The payment funds are not yet available in your account.
statusopen: 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_intentThe payment_intent object represents the actual payment transaction that needs to take place. It includes details about the amount, currency, payment method, etc.
amount_totalThe total sum of all items, factoring in applied discounts and taxes.
payment_linkThe 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
}

📘

Click here to read Stripe documentation for this endpoint.

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"
    }
}

📘

Click here to read Stripe documentation for this endpoint.

Updated 4 months ago