Hosted Checkout - Alguna Docs

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 -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": "billing@acme.com" },
    "success_url": "https://yourapp.com/welcome",
    "client_reference_id": "order_1234",
    "expires_in_seconds": 3600
  }'

import os

import requests

response = requests.post(
    "https://api.alguna.io/checkout-sessions",
    headers={
        "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
        "Alguna-Version": "2026-04-01",
        "Content-Type": "application/json",
    },
    json={
        "plan_id": "pln_033ZYEaFZURxhK5a1cUAgQ",
        "customer": {"name": "Acme Corp", "email": "billing@acme.com"},
        "success_url": "https://yourapp.com/welcome",
        "client_reference_id": "order_1234",
        "expires_in_seconds": 3600,
    },
    timeout=10,
)
response.raise_for_status()
session = response.json()
# redirect the customer to session["url"]

const session = await alguna.checkoutSessions.create({
  plan_id: "pln_033ZYEaFZURxhK5a1cUAgQ",
  customer: { name: "Acme Corp", email: "billing@acme.com" },
  success_url: "https://yourapp.com/welcome",
  client_reference_id: "order_1234",
  expires_in_seconds: 3600,
});
// redirect the customer to session.url

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

Open Customers and select the customer
Click Create Checkout Session
Select the plan
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.

​What a session can sell

​Who the buyer is

​Creating a session

​Via the API

​Via the dashboard

​Session lifecycle

​Checkout flow

​Handling completion

​Payment methods, tax and branding

​Security

​Best practices