> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talescria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hosted checkout

> Take a card payment for an amount your server decides.

Hosted checkout is a payment page for one payment, with an amount your server sets: a basket total, a booking, a top-up. Your server creates a **session**, you send the payer to its page, and they pay there by card. Card details go straight from the payer's browser to the card processor and never touch your servers.

Use [payment links](https://docs.talescria.com/guides/payment-links.md) instead when the amount is fixed and the same for everyone.

Scope: `checkout:write`.

## How it works

**1. Create a session on your server**

```bash curl theme={null}
curl https://pay.talescria.com/v1/sessions \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": { "minorUnits": "12999", "currency": "USD" },
    "country": "US",
    "methods": ["card"]
  }'
```

```python Python theme={null}
resp = requests.post(
    "https://pay.talescria.com/v1/sessions",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "amount": {"minorUnits": "12999", "currency": "USD"},
        "country": "US",
        "methods": ["card"],
    },
    timeout=30,
)
session = resp.json()["session"]
```

The payment goes to your [default account](https://docs.talescria.com/guides/accounts.md#the-default-account) in that currency, so open one first.

**2. Send the payer to the page**

Redirect the payer, or link them, to:

```
https://pay.talescria.com/pay/s/{session.id}
```

The page shows your business's verified name and the amount, takes the card (with 3-D Secure where the bank asks), and shows the result. A declined card leaves the session open, so they can try another card.

**3. Confirm the payment**

Fetch the session from your server and fulfil the order when `state` is `completed`.

```python theme={null}
resp = requests.get(f"https://pay.talescria.com/v1/sessions/{session_id}", timeout=30)
session = resp.json()["session"]
if session["state"] == "completed":
    fulfil_order(session["id"], session["paymentId"])
```

## Session states

| `state` | Meaning |
| - | - |
| `open` | Waiting for the payer. Also the state after a declined card. |
| `processing` | A payment is under way. If `underReview` is `true`, it's held for a compliance review and nothing has been charged yet. |
| `completed` | Paid. `paymentId` identifies the payment. |
| `cancelled` | Cancelled before payment. |
| `expired` | Not paid in time. Sessions last 30 minutes unless you set `ttlMs`. |

Treat `completed` as the only paid state. A `processing` session isn't paid yet and doesn't expire while a payment is in flight.

> [!NOTE]
>
> Checkout doesn't notify your server yet, and the page doesn't redirect back to your site. Poll the session from your server (for example every few seconds while the payer is on the page, then less often) until it's `completed`, `cancelled` or `expired`. Webhooks are coming.

## Keeping it secure

* **Create sessions on your server.** The access token is a secret. The amount comes from your server, so a payer can't change it.
* **The session ID is the payer's key to the page.** Anyone with it can see the amount and pay it. Don't publish it, but it's fine in a redirect.
* **Check the amount** in the completed session matches the order before fulfilling.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.