Checkout Management

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

📘
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:

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
}

📘
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.