# Create a hosted session

`POST /functions/v1/hosted-session-create`

Called by your server with a secret key. The session carries merchant, action, reference and amount, so a browser cannot alter a value it never holds.

A publishable `pk_` is rejected: minting a session is a server act.

## Body

| Field | Type | Notes |
| --- | --- | --- |
| action | authorize|checkin|sign|verify|enroll | required |
| external_txn_ref | string ≤128 | Required for authorize; charset [\w.:@/-] |
| amount_cents | integer | Required for authorize; minor unit |
| currency | ISO-4217 | Defaults to BRL when an amount is present |
| brand | string ≤40 | Display label only, sanitized |
| ttl_seconds | 60–900 | Default 300 |
| metadata | object ≤2 KB | Display and passthrough only |
| merchant_id | string | Optional; must match the key's merchant |

```
curl -X POST https://api.sidaxis.com/functions/v1/hosted-session-create \
  -H "x-sidaxis-api-key: sk_live_..." \
  -H "content-type: application/json" \
  -d '{
    "action": "authorize",
    "external_txn_ref": "order-88213",
    "amount_cents": 18900,
    "currency": "USD",
    "brand": "Northwind",
    "ttl_seconds": 300
  }'
```

## Response

201:

```
{
  "session_token": "hs_9c1f...",
  "session_id": "hss_71ac33",
  "merchant_id": "mrc_9f2c",
  "action": "authorize",
  "external_txn_ref": "order-88213",
  "amount_cents": 18900,
  "currency": "USD",
  "brand": "Northwind",
  "expires_at": "2026-09-16T12:06:03Z",
  "ttl_seconds": 300,
  "single_use": true
}
```

> `session_token` is shown exactly once. It is 32 random bytes, and only `SHA-256(token)` is persisted, so the plaintext is never stored, logged or recoverable.

## What this call does not have

No `url`, no `mode`, no `return_url`, no branding block. There is no redirect URL: you hand the token to the browser and open the hosted screen with it, and branding comes from [merchant-theme-get](/theme).

The security property, plainly: the session carries merchant, action, reference and amount, and it is the session that decides the values the screen shows. The browser never carries the amount, so it cannot alter it.

## Errors

| Status | Codes |
| --- | --- |
| 400 | INVALID_ACTION, INVALID_EXTERNAL_TXN_REF, INVALID_AMOUNT_CENTS, INVALID_CURRENCY, AMOUNT_AND_REF_REQUIRED, INVALID_TTL, INVALID_BRAND, INVALID_METADATA, METADATA_TOO_LARGE |
| 401 | API_KEY_REQUIRED, INVALID_API_KEY |
| 403 | MERCHANT_MISMATCH |
| 500 | SESSION_WRITE_FAILED |