# Hosted Page Read

What the hosted page reads with its link's token. The page calls it itself; your app never needs to.

## Overview

- Answers the session's status (refreshed from the payment provider while not final) with what the page shows the user — `pair` (`currency`, `network`, `networkName` as the page names it, and `explorerTx`, the explorer's transaction page it links a live delivery to, `null` in the sandbox), `destination` (`kind`, `address`), `requested`, `amounts` (in `amounts.sourceCurrency`, the currency the payment provider charges in) and `transactionId`, never an internal id — the client secret and publishable key while it can be paid in a widget the page mounts itself, the return URL, the page's locale and theme, `poweredBy` (the payment provider the page names), and your tenant's `name`, `logoUrl` and `primaryColor` (`null` when unset or not a `#rrggbb` value).
- With `widget: true` — the page's first read only — a session whose payment provider's widget runs in a frame answers `widgetUrl`: made for the address the request came from, valid five minutes and once, once the payment provider priced exactly the session's pair, currency and amount. None is made while a payment of the session is under way. Where the payment provider no longer sells them, the read answers its refusal (`400` `CARD_ONRAMP_INVALID_REQUEST`) and the session stays open.
- `404` `CARD_ONRAMP_LINK_NOT_FOUND` for a token no link has, `410` `CARD_ONRAMP_LINK_EXPIRED` after 30 minutes, `403` `CARD_ONRAMP_ORIGIN_NOT_ALLOWED` for a request a browser sends from another site's page, `400` `CARD_ONRAMP_CUSTOMER_IP_REQUIRED` for a widget asked from no public address. No authentication: the token is the credential. At most 30 calls a minute from one address; `Cache-Control: no-store`.

## Endpoint

### `POST /v1/ramp/card/hosted/session`

Authentication: none (public endpoint).

What the hosted page needs, for its link's token.

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | string | yes | The token from the link's fragment |
| `widget` | boolean | no | `true` on the page's first read: makes the widget of a payment provider that runs in a frame |

**Responses**

`200` OK

```json
{
  "session": {
    "id": "444417bc-0675-4d3a-8831-bd1cbedc9738",
    "status": "requires_payment",
    "environment": "sandbox",
    "pair": { "currency": "usdc", "network": "ethereum", "networkName": "Ethereum", "explorerTx": null },
    "destination": { "kind": "proven_address", "address": "0x973Eb7c2BCae2FECBc012F1762AddB30143eA62e" },
    "requested": { "sourceCurrency": "eur", "sourceAmount": "50.00", "destinationAmount": null },
    "amounts": { "sourceCurrency": "eur", "sourceAmount": "50.00", "destinationAmount": "56.573880" },
    "transactionId": null
  },
  "clientSecret": "cos_1QAbCdEfGhIjKlMn_secret_Xy9ZkLmNoPqRsTuVwXyZ01",
  "publishableKey": "pk_test_51QAbCdEfGhIjKlMnOpQrStUv",
  "widgetUrl": null,
  "poweredBy": "Stripe",
  "returnUrl": "brandbank://onramp/done",
  "locale": "en",
  "theme": "light",
  "tenant": { "name": "Brand Bank", "logoUrl": "https://api.aureahub.com/uploads/logos/brand.png", "primaryColor": "#0A7C3E" }
}
```

`410` Expired

```json
{
  "statusCode": 410,
  "error": "GoneError",
  "message": "This link has expired",
  "details": { "code": "CARD_ONRAMP_LINK_EXPIRED" }
}
```

---

Web version: https://docs.aureahub.com/#card-onramp-hosted-session