lollipayDocs
Checkouts

Create checkout session

POST
/v1/stores/{storeId}/checkouts

Creates a checkout session that stays open for 1 hour and returns a checkout_url to redirect the buyer to. Line items are dynamic: send a name and an amount (in minor units, for example cents) for each one. When the buyer pays they're sent to return_url with checkout_id added to the query string.

Requires the checkouts:write permission.

Authorization

headerAuthorizationBearer <lp_test_sk_… / lp_live_sk_…>

A bearer key's secret in the Authorization header. Keep it on your server.

Path Parameters

storeId*string

Your store ID, shown in Dashboard → Developers → API keys.

Formatuuid

Request Body

application/json
  1. body
items*array<>

Line items. Together they must add up to between 99 and 100000000 minor units ($0.99 at least).

Items1 <= items <= 10
title?string

Heading on the checkout page. Defaults to your store name.

Length1 <= length <= 128
description?string

Shown under the total on the checkout page.

Length1 <= length <= 500
currency?string

Three-letter ISO 4217 code. Defaults to your store's currency (USD).

Match^[a-zA-Z]{3}$
amount?integer

Expected total in minor units. If you send it, it must equal the items total, a safeguard against pricing bugs.

customer*
metadata?

Up to 20 string values (keys up to 40 characters), stored on the session.

Propertiesproperties <= 20
return_url?string

HTTPS URL the buyer goes to after paying. checkout_id is added to its query string.

Formaturi
cancel_url?string

HTTPS URL behind the checkout page's back link.

Formaturi

Response Body

Checkout session created.

application/json
  1. response
ok*boolean
data*
Example Request
curl -X POST 'https://api.lollipay.cc/v1/stores/497f6eca-6276-4993-bfeb-53cbbbba6f08/checkouts' \  -H 'Content-Type: application/json' \  -d '{  "title": "Upgrade to Pro",  "items": [    {      "name": "Pro plan (yearly)",      "amount": 4900    },    {      "name": "Extra seat",      "amount": 1500,      "quantity": 2    }  ],  "amount": 7900,  "currency": "usd",  "customer": {    "email": "buyer@example.com",    "name": "Emma Wilson"  },  "metadata": {    "order_id": "A-1042"  },  "return_url": "https://example.com/thanks",  "cancel_url": "https://example.com/pricing"}'
Example Response
{  "ok": true,  "data": {    "id": "cs_55ca30f7581d9a76ac7188349f33b4811c4b43f28935ed507586d3bd92fa4982",    "object": "checkout_session",    "livemode": false,    "status": "open",    "title": "Upgrade to Pro",    "description": null,    "checkout_url": "https://checkout.lollipay.cc/invoice/cs_55ca30f7581d9a76ac7188349f33b4811c4b43f28935ed507586d3bd92fa4982",    "merchant": {      "id": "4f9c2d1e-7b3a-4c58-9e21-6d0f8a3b5c47",      "name": "Example",      "statement_descriptor": "ALTURA",      "website": "https://example.com"    },    "currency": "USD",    "amount": 7900,    "discount_amount": 0,    "tax_amount": 0,    "total_amount": 7900,    "items": [      {        "name": "Pro plan (yearly)",        "amount": 4900,        "quantity": 1,        "image": null      },      {        "name": "Extra seat",        "amount": 1500,        "quantity": 2,        "image": null      }    ],    "customer": {      "email": "buyer@example.com",      "name": "Emma Wilson"    },    "metadata": {      "order_id": "A-1042"    },    "return_url": "https://example.com/thanks",    "cancel_url": "https://example.com/pricing",    "payment_id": null,    "created_at": 1792315200,    "expires_at": 1792336800,    "completed_at": null  }}

Overview

The Lollipay REST API. Try every endpoint from this site with your own test key.

Retrieve checkout session GET

Returns a checkout session created with a key of the same mode. Use it on your `return_url` page to confirm `status` is `complete` before fulfilling the order. Requires the `checkouts:read` permission (`checkouts:write` includes it).