# Hosted Page Link

A link to Aurea's hosted page for one of the user's open sessions, for an app with no web page of its own.

## Overview

- The session must be the user's (`404` `CARD_ONRAMP_SESSION_NOT_FOUND`) and still payable — `initialized` or `requires_payment` as the payment provider has it now — else `409` `CARD_ONRAMP_SESSION_CLOSED` with `details.status`.
- `returnUrl` must be one of your tenant's return URLs, a deep link or an https origin the Aurea operator allowed: `400` `RETURN_URL_NOT_ALLOWED` otherwise, and always while your tenant allows none. Without it, the page tells the user to close it when the session ends.
- `url` works for 30 minutes; its token is in the fragment. Each call makes a new link. See [Card to Crypto](https://docs.aureahub.com/docs/guide-card-onramp.md), Hosted page.
- The body is checked as sent: an unknown field, locale or theme answers `400`.

## Endpoint

### `POST /v1/ramp/card/sessions/{id}/hosted-link`

Authentication: bearer token required.

A link to the hosted page for one of the user's open sessions.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes | The session's `id` |

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `returnUrl` | string | no | Where to send the browser back: a deep link or an https URL your tenant allows |
| `locale` | string | no | `en` (default) or `it` |
| `theme` | string | no | `light` (default) or `dark` |

**Responses**

`201` Created

```json
{
  "url": "https://api.aureahub.com/v1/ramp/card/hosted#fse17-3QkR0t56XcLd_a2JH9CldWnE1bVXPtdoMS1BU",
  "expiresAt": "2026-09-24T15:40:10.912Z"
}
```

`409` No longer payable

```json
{
  "statusCode": 409,
  "error": "ConflictError",
  "message": "This session can no longer be paid: only an initialized session, or one waiting for its payment, is opened in the hosted page.",
  "details": { "code": "CARD_ONRAMP_SESSION_CLOSED", "status": "fulfillment_processing" }
}
```

`400` Return URL not allowed

```json
{
  "statusCode": 400,
  "error": "BadRequestError",
  "message": "This return URL is not one the tenant allows. Ask the Aurea operator to add it.",
  "details": { "code": "RETURN_URL_NOT_ALLOWED" }
}
```

---

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