Hosted sessions

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.

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`

Sidaxis is the human authorisation layer. It never moves money, holds funds or settles. The machine-readable contract is openapi.yaml.