Hosted Checkout Sessions

Calmony Pay's Hosted Checkout Session API lets you redirect customers to a Cardstream-powered Hosted Payment Page (HPP) to collect card payments. Your servers never handle raw card data — the HPP manages the payment form and Calmony Pay handles tokenisation and payment intent creation on completion.

How It Works

1. Create a session — Your server calls POST /v1/checkout/sessions with line items, a success URL, and a cancel URL.
2. Redirect the customer — Return the url from the response and redirect the customer's browser to it.
3. Customer pays — The customer enters their card details on the Cardstream Hosted Payment Page.
4. Completion callback — Once payment completes, Calmony Pay:
   • Creates a payment_intent with status succeeded
   • Tokenises the card as a payment_method and attaches it to the customer
5. Redirect — The customer is sent to your success_url (or cancel_url if they abandon).

Endpoints

Create a Checkout Session

POST /v1/checkout/sessions

Request body:

Parameter	Type	Required	Description
line_items	array	Yes	Array of items in the order (see below)
success_url	string	Yes	URL to redirect to after successful payment
cancel_url	string	Yes	URL to redirect to if the customer cancels
customer	string	No	ID of an existing customer to attach the payment method to

line_items object:

Field	Type	Required	Description
price_data.currency	string	Yes	Three-letter ISO currency code (e.g. gbp)
price_data.unit_amount	integer	Yes	Amount in the smallest currency unit (e.g. pence)
price_data.product_data.name	string	Yes	Name of the product or service
quantity	integer	Yes	Quantity of this line item

Example request:

curl -X POST https://api.calmonypay.com/v1/checkout/sessions \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      {
        "price_data": {
          "currency": "gbp",
          "unit_amount": 2999,
          "product_data": {
            "name": "Pro Plan — Monthly"
          }
        },
        "quantity": 1
      }
    ],
    "success_url": "https://yourapp.com/checkout/success",
    "cancel_url": "https://yourapp.com/checkout/cancel",
    "customer": "cus_abc123"
  }'

Example response:

{
  "id": "cs_abc123",
  "object": "checkout.session",
  "status": "open",
  "url": "https://hpp.cardstream.com/pay/cs_abc123",
  "success_url": "https://yourapp.com/checkout/success",
  "cancel_url": "https://yourapp.com/checkout/cancel",
  "customer": "cus_abc123",
  "payment_intent": null,
  "created": 1718000000
}

Redirect the customer to the url field immediately after creating the session.

---

Retrieve a Checkout Session

GET /v1/checkout/sessions/:id

Path parameters:

Parameter	Description
id	The checkout session ID (prefixed cs_)

Example request:

curl https://api.calmonypay.com/v1/checkout/sessions/cs_abc123 \
  -H "Authorization: Bearer sk_live_..."

Example response (after completion):

{
  "id": "cs_abc123",
  "object": "checkout.session",
  "status": "complete",
  "url": "https://hpp.cardstream.com/pay/cs_abc123",
  "success_url": "https://yourapp.com/checkout/success",
  "cancel_url": "https://yourapp.com/checkout/cancel",
  "customer": "cus_abc123",
  "payment_intent": "pi_xyz789",
  "payment_method": "pm_def456",
  "created": 1718000000
}

Session Lifecycle

Status	Description
open	Session created, customer has not yet completed payment
complete	Payment was successful; payment_intent and payment_method are populated
expired	Session expired before the customer completed payment

What Happens on Completion

When the Cardstream HPP posts back a successful payment callback, Calmony Pay automatically:

1. Creates a payment_intent with status: succeeded and links it to the session
2. Tokenises the card used as a payment_method object
3. Attaches the payment_method to the customer (if one was provided when creating the session)
4. Updates the session status to complete

You can retrieve the session at any point to check its status and access the resulting payment_intent and payment_method IDs.

ID Prefixes

Object	Prefix	Example
Checkout Session	cs_	cs_abc123
Payment Intent	pi_	pi_xyz789
Payment Method	pm_	pm_def456
Customer	cus_	cus_abc123

Notes

• The hosted payment page is served and secured by Cardstream — no PCI scope is added to your servers.
• Card tokenisation happens automatically on completion; you do not need to call a separate tokenise endpoint.
• The payment_method is reusable for future charges against the same customer.