Introducing Hosted Checkout Sessions — v1.0.9

Calmony Pay v1.0.9 ships the Hosted Checkout Session, the simplest way to collect one-off card payments without writing a payment form or handling card data on your servers.

What's New

Two new API endpoints:

• POST /v1/checkout/sessions — create a session with line items, a success URL, and a cancel URL
• GET /v1/checkout/sessions/:id — retrieve a session and its outcome

The Redirect Flow in Three Steps

1. Create a session on your server

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": 4900,
        "product_data": { "name": "Starter Plan" }
      },
      "quantity": 1
    }],
    "success_url": "https://yourapp.com/thank-you",
    "cancel_url": "https://yourapp.com/pricing",
    "customer": "cus_abc123"
  }'

The response includes a url field pointing to the Cardstream Hosted Payment Page. Redirect your customer there.

2. Customer pays on the Hosted Payment Page

Cardstream securely collects the customer's card details. Your application is out of PCI scope for this step.

3. Calmony Pay handles the rest

On a successful payment callback from Cardstream, Calmony Pay automatically:

• Creates a payment_intent with status: succeeded
• Tokenises the card as a payment_method and attaches it to the customer
• Updates the session status to complete

The customer lands on your success_url. Poll or retrieve the session to get the resulting IDs:

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

{
  "id": "cs_abc123",
  "status": "complete",
  "payment_intent": "pi_xyz789",
  "payment_method": "pm_def456",
  "customer": "cus_abc123"
}

Why This Matters

• No card data on your servers — the HPP is fully hosted by Cardstream
• Automatic tokenisation — every completed session produces a reusable payment_method for the customer, ready for future charges or subscriptions
• One integration, two outcomes — a payment_intent proves the charge happened; a payment_method enables future payments without asking the customer again

Full Reference

See the Hosted Checkout Sessions API reference for the complete parameter list, response shapes, and session lifecycle states.