> ## Documentation Index
> Fetch the complete documentation index at: https://alguna.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Hosted Checkout Integration
> Accept payments with Alguna's secure hosted checkout
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](/docs/hosted/checkout) page, and the in-page variant is [Embedded Checkout](/docs/hosted/embedded-checkout).
***
## How It Works
```mermaid theme={null}
sequenceDiagram
participant Customer
participant YourApp
participant Alguna
Customer->>YourApp: Clicks "Subscribe"
YourApp->>Alguna: Create checkout session
Alguna-->>YourApp: Checkout URL
YourApp->>Customer: Redirect to checkout
Customer->>Alguna: Enter payment info
Alguna->>Alguna: Process payment & create subscription
Alguna->>Customer: Redirect to success page
```
***
## Creating Checkout Sessions
### Via Dashboard
Create a checkout link for a customer:
1. Navigate to **Customers → \[Customer Name]**
2. Click **Create Checkout Session**
3. Select the plan
4. Copy the checkout URL
5. 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:
```bash cURL theme={null}
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"
}'
```
```python Python theme={null}
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"]
```
```typescript TypeScript SDK theme={null}
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](/docs/hosted/checkout) for every session field and the redirect flow, [Embedded Checkout](/docs/hosted/embedded-checkout) to render checkout inside your own page, and the [API reference](/docs/api-reference/v2/2026-04-01/checkout-sessions/create-a-checkout-session).
***
## Checkout Experience
When customers visit the checkout URL, they see:
1. **Plan summary** - Selected plan with pricing
2. **Customer information** - Name, email, company
3. **Billing address** - For tax calculation
4. **Payment method** - Card or bank transfer
5. **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](/docs/getting-started/branding)) and the payment methods enabled under **Settings → Workflows → Payments → Payment methods** ([Stripe](/docs/integrations/payments/stripe), [ACH](/docs/integrations/payments/ach)). To serve it from your own domain, see [Custom domains](/docs/hosted/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](/docs/api-reference/v2/webhooks#checkout-events). You can also poll [`GET /checkout-sessions/{id}`](/docs/api-reference/v2/2026-04-01/checkout-sessions/get-a-checkout-session) until `status` is `successful`.
***
## Testing Checkout
### Sandbox Mode
Test checkout in sandbox before going live:
1. Use a sandbox API key against `https://api.sandbox.alguna.io`
2. Checkout sessions created in sandbox don't process real payments
3. Use test card numbers provided by your payment processor
### Test the Flow
1. Create a checkout session
2. Visit the checkout URL
3. Complete payment with test card
4. 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
1. Verify the checkout URL is valid
2. Check the session hasn't expired
3. Ensure the plan is active
### Payment Failed
1. Customer should verify card details
2. Check for sufficient funds
3. Try a different payment method
### Customer Not Redirected After Payment
1. Verify success URL is correctly configured
2. Check for browser popup blockers
3. Ensure URL is publicly accessible
***
## Best Practices
Create a success page that confirms the subscription and provides next steps.
Always verify payment via webhooks, not just the redirect.
Test the full flow in sandbox before going live.
If checkout fails, help customers understand what went wrong.
***
## Next Steps
Let customers manage their subscriptions.
Set up event notifications.
Trials, credits, checkout and portal in one flow.
API basics, SDK and sandbox.