Hosted Checkout

A hosted payment page that takes a card or bank payment and creates the customer, subscription and invoice — opened from a checkout session you create via the API or the dashboard.

Hosted Checkout is Alguna’s pre-built payment page. You create a checkout session that says what is being sold — a plan, ad-hoc line items, or a bare amount — and who the buyer is; Alguna renders the page, collects payment details on its own origin, charges the customer, and creates the customer account, the subscription (for plans) and the paid invoice. Use it for self-serve signups, upgrades, one-off purchases, or simply to vault a card for later invoices, without building a payment form or handling card data. To render the same checkout inside your own page instead of redirecting, use Embedded Checkout.

What checkout creates — customers, subscriptions, invoices, payments — is described in How Alguna works.

---

What a session can sell

Provide exactly one of the following:

Field	Behaviour	Created on payment
plan_id	Charges the plan’s prices; line items and amount derive from the plan	Customer account + active subscription + paid first invoice
line_items	Ad-hoc items (description, quantity, unit_price, optional product_name)	Customer account + paid one-off invoice, no subscription
amount	A bare total with no itemization	Customer account + paid one-off invoice with a single line

To store a payment method without charging, set "checkout_intent": "vault" and omit all three; the checkout collects and vaults a card for later use, such as invoice autopay.

One-off sessions (line_items or amount) are invoiced with zero tax so the invoice total equals what the customer was charged. Plan sessions calculate tax per your tax configuration from the address entered at checkout.

---

Who the buyer is

You pass	Use when	Checkout behaviour
customer_id or customer_alias	The buyer is an existing Alguna customer	Identity is skipped; saved payment methods are offered
customer object (name, email, optional first_name, last_name, website_url, address)	The buyer is signed in to your product but not yet a customer	Identity is pre-filled; the account is created when checkout completes
Nothing	Anonymous visitors on a public pricing page	Checkout collects name and email before payment

---

Creating a session

Via the API

cURL

curl -X POST https://api.alguna.io/checkout-sessions \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "pln_033ZYEaFZURxhK5a1cUAgQ",
    "customer": { "name": "Acme Corp", "email": "[e-mail]" },
    "success_url": "https://yourapp.com/welcome",
    "client_reference_id": "order_1234",
    "expires_in_seconds": 3600
  }'

Redirect the customer to the url in the response. Other useful request fields:

Field	Description
success_url	Where the customer is sent after a successful payment
client_reference_id	Your own order or cart reference, echoed on the session and on the checkout.session.completed webhook
expires_in_seconds	Session lifetime, 300 to 604 800 seconds (5 minutes to 7 days). Default 86 400 (24 hours)
currency	ISO 4217 code; defaults to the organization currency
legal_entity_id	Legal entity to bill from; defaults to the customer’s, then the organization default
checkout_intent	payment (default) or vault

Reference: Create a checkout session.

Via the dashboard

1. Open Customers and select the customer
2. Click Create Checkout Session
3. Select the plan
4. Copy the checkout URL, or send it to the customer

---

Session lifecycle

GET /checkout-sessions/{id} returns the session with its status:

Status	Meaning
created	Minted; the customer has not opened it
started	The customer opened the checkout
successful	Payment succeeded; payment_id, subscription_id (plan sessions) or invoice_id (one-off sessions) are set once fulfilment finishes
expired	expires_at passed without payment; the session can no longer be rendered or paid

Sessions are immutable snapshots of what is being sold. To change the price or plan, create a new session. Reference: Get a checkout session.

---

Checkout flow

---

Handling completion

Treat the redirect to success_url as a UI signal only — fulfil from the server:

• Webhook — subscribe to checkout.session.completed. The payload carries the session id, amount, currency, accountId, paymentId, invoiceId, subscriptionId (plan sessions) and your clientReferenceId. See Webhooks.
• Polling — GET /checkout-sessions/{id} until status is successful and the fulfilment IDs are present.

Fulfilment is asynchronous: the payment, account and subscription or invoice attach within seconds of the customer seeing the success state, not in the same instant.

A session reaching successful with a subscriptionId means the subscription exists — not necessarily that it is live. Read it with GET /subscriptions/{id} and check its own status before granting access; if your organization uses approval flows, a new subscription can land in pending_approval rather than active. See Subscription statuses.

---

Payment methods, tax and branding

• Payment methods are the ones your connected processor supports and you have enabled under Settings → Workflows → Payments → Payment methods — cards through Stripe, and ACH where enabled. 3-D Secure and other processor-driven authentication run inside the checkout.
• Tax on plan checkouts follows your tax configuration and the address entered at checkout.
• Branding — logo, colors and brand slug — comes from Settings → Organization → Customizations → Branding; see Branding. Serve checkout from your own domain with Custom domains.

---

Security

• Card data is entered on Alguna’s origin and passed to the payment processor; it never touches your servers
• Sessions are single-use, expire automatically, and cannot be reused after completion
• Only the session url is safe to expose; your API key stays on your server

---

Best practices

Pass what you know

Send customer_id/customer_alias or a customer object so the buyer is not asked for details you already have.

Keep sessions short

Use expires_in_seconds in the hour range for cart-specific links; mint a new one if it expires.

Fulfil from the webhook

Provision on checkout.session.completed, matched by clientReferenceId, not on the redirect.

Test in sandbox

Run the full flow with your processor’s test cards before going live.

---

Troubleshooting

Checkout does not load — the session has expired, or the plan is not active. Create a new session.

Payment failed — the customer’s bank declined the charge; the checkout shows the processor’s reason and lets them try another method.

Customer not redirected — check success_url is set on the session and publicly reachable; the checkout.session.completed webhook still fires either way.

---

Next steps

Embedded checkout

Render the same checkout inside your own page.

Hosted checkout integration guide

Dashboard-first walkthrough.

Customer portal

Self-service after the first payment.

Launch self-serve

Trials, credits, checkout and portal in one flow.