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:

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โ€ is allowed.
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.