Hosted Checkout Integration

Hosted Checkout is Alguna’s pre-built payment page: you create a checkout session for a plan (or one-off line items), send the customer to its URL, and Alguna collects payment, creates the customer and subscription, and issues the paid invoice. Card data never touches your servers. This guide walks the dashboard and API paths to a working checkout; the session fields, statuses and fulfilment details are on the Hosted Checkout page, and the in-page variant is Embedded Checkout.

How It Works

Creating Checkout Sessions

Via Dashboard

Create a checkout link for a customer:

Navigate to Customers → [Customer Name]
Click Create Checkout Session
Select the plan
Copy the checkout URL
Share with customer (email, chat, etc.)

Via Your Application

Create the session server-side with POST /checkout-sessions and redirect the customer to the url in the response:

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_alias": "acme-user-4821",
    "success_url": "https://yourapp.com/welcome",
    "client_reference_id": "order_1234"
  }'

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_alias": "acme-user-4821",
        "success_url": "https://yourapp.com/welcome",
        "client_reference_id": "order_1234",
    },
    timeout=10,
)
response.raise_for_status()
checkout_url = response.json()["url"]

const session = await alguna.checkoutSessions.create({
  plan_id: "pln_033ZYEaFZURxhK5a1cUAgQ",
  customer_alias: "acme-user-4821",
  success_url: "https://yourapp.com/welcome",
  client_reference_id: "order_1234",
});
// redirect to session.url

See Hosted Checkout for every session field and the redirect flow, Embedded Checkout to render checkout inside your own page, and the API reference.

Checkout Experience

When customers visit the checkout URL, they see:

Plan summary - Selected plan with pricing
Customer information - Name, email, company
Billing address - For tax calculation
Payment method - Card or bank transfer
Order summary - Total with tax

After completing payment:

Subscription is created automatically
Customer is redirected to your success URL
You receive webhook notification

Checkout Settings

Per session

Checkout behaviour is set per session, when you create it:

Field	Description
`success_url`	Where to send the customer after a successful checkout
`expires_in_seconds`	How long the link stays valid. Between 5 minutes and 7 days; defaults to 24 hours
`client_reference_id`	Your own order or cart reference, echoed back on the session and the completion webhook
`checkout_intent`	`payment` to charge, or `vault` to only store a payment method

Branding and payment methods

Checkout uses the logo, colors and brand slug set under Settings → Organization → Customizations → Branding (Branding) and the payment methods enabled under Settings → Workflows → Payments → Payment methods (Stripe, ACH). To serve it from your own domain, see Custom domains.

Handling Checkout Completion

Success Page

When payment succeeds, customers are redirected to your success URL. Create a page that:

Confirms their subscription is active
Provides next steps or onboarding
Links to your application

Webhooks

For reliable delivery confirmation, set up webhooks:

Event	When Sent
`checkout.session.completed`	Payment successful; `subscriptionId` (plan sessions) or `invoiceId` (one-off) and your `clientReferenceId` are in the payload

Configure webhooks under Settings → Connections → Developers → Webhooks; payload in the Webhooks reference. You can also poll GET /checkout-sessions/{id} until status is successful.

Testing Checkout

Sandbox Mode

Test checkout in sandbox before going live:

Use a sandbox API key against https://api.sandbox.alguna.io
Checkout sessions created in sandbox don’t process real payments
Use test card numbers provided by your payment processor

Test the Flow

Create a checkout session
Visit the checkout URL
Complete payment with test card
Verify:
- Redirected to success URL
- Subscription created in dashboard
- Webhook received (if configured)

Common Questions

Can customers apply discount codes?

No. Discounts are set on the plan or the subscription before checkout, not entered by the customer at the till.

What payment methods are supported?

Depends on your payment processor configuration:

Credit/Debit cards
ACH bank transfers (if enabled)

How long are checkout links valid?

24 hours by default. Set expires_in_seconds when you create the session to change it, between 5 minutes and 7 days.

Can I pre-fill customer information?

Yes. Pass an existing customer_id or customer_alias, or a customer object for a guest checkout, and the customer account is created when checkout completes.

Troubleshooting

Checkout Page Not Loading

Verify the checkout URL is valid
Check the session hasn’t expired
Ensure the plan is active

Payment Failed

Customer should verify card details
Check for sufficient funds
Try a different payment method

Customer Not Redirected After Payment

Verify success URL is correctly configured
Check for browser popup blockers
Ensure URL is publicly accessible

Best Practices

Clear Success Page

Create a success page that confirms the subscription and provides next steps.

Handle Webhooks

Always verify payment via webhooks, not just the redirect.

Test Thoroughly

Test the full flow in sandbox before going live.

Communicate Errors

If checkout fails, help customers understand what went wrong.

Next Steps

Customer Portal

Let customers manage their subscriptions.

Webhooks

Set up event notifications.

Launch self-serve

Trials, credits, checkout and portal in one flow.

Developer quick start

API basics, SDK and sandbox.

​How It Works

​Creating Checkout Sessions

​Via Dashboard

​Via Your Application

​Checkout Experience

​Checkout Settings

​Per session

​Branding and payment methods

​Handling Checkout Completion

​Success Page

​Webhooks

​Testing Checkout

​Sandbox Mode

​Test the Flow

​Common Questions

​Can customers apply discount codes?

​What payment methods are supported?

​How long are checkout links valid?

​Can I pre-fill customer information?

​Troubleshooting

​Checkout Page Not Loading

​Payment Failed

​Customer Not Redirected After Payment

​Best Practices

Clear Success Page

Handle Webhooks

Test Thoroughly

Communicate Errors

​Next Steps

Customer Portal

Webhooks

Launch self-serve

Developer quick start

How It Works

Creating Checkout Sessions

Via Dashboard

Via Your Application

Checkout Experience

Checkout Settings

Per session

Branding and payment methods

Handling Checkout Completion

Success Page

Webhooks

Testing Checkout

Sandbox Mode

Test the Flow

Common Questions

Can customers apply discount codes?

What payment methods are supported?

How long are checkout links valid?

Can I pre-fill customer information?

Troubleshooting

Checkout Page Not Loading

Payment Failed

Customer Not Redirected After Payment

Best Practices

Next Steps