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

# Hosted checkout

> Create short-lived payment sessions for purchases, card management, subscriptions, and AI credits.

Create every payment session from a trusted backend. The request selects one allowed action and one server-authorized purchase source.

## Authentication

```http theme={null}
Authorization: Bearer <service-client-secret>
X-Boxpressd-Client-Id: <service-client-id>
Idempotency-Key: <stable-checkout-attempt-id>
Content-Type: application/json
```

Your service-client policy must allow the action, billing resource type, return URL, and embedding origin in the request.

## Session fields

<ParamField body="action" type="string" required>
  `purchase`, `manage_methods`, `change_subscription`, or `buy_credits`.
</ParamField>

<ParamField body="actor" type="object" required>
  The `boxpressd_user`, `guest`, or `service` actor and its stable ID.
</ParamField>

<ParamField body="billingAccountId" type="string" required>
  The authorized billing account UUID.
</ParamField>

<ParamField body="billingAccountAssertion" type="string">
  A short-lived signed assertion when the client policy requires account-specific authorization.
</ParamField>

<ParamField body="returnUrl" type="string" required>
  An exact registered URL or a URL under a registered prefix.
</ParamField>

<ParamField body="cancelUrl" type="string">
  A registered destination for cancellation.
</ParamField>

<ParamField body="parentOrigin" type="string">
  The registered parent origin when checkout runs in an iframe.
</ParamField>

<ParamField body="presentation" type="string" default="page">
  `page`, `modal`, or `sheet`.
</ParamField>

## Marketplace purchase

The trusted shop backend supplies the merchant, order reference, and final minor-unit amount:

```json theme={null}
{
  "action": "purchase",
  "actor": { "type": "boxpressd_user", "id": "123" },
  "billingAccountId": "00000000-0000-0000-0000-000000000001",
  "marketplace": {
    "merchantAccountId": "00000000-0000-0000-0000-000000000002",
    "orderReference": "shop-order-987",
    "money": { "amountMinor": 3599, "currency": "USD" }
  },
  "returnUrl": "https://shop.example/orders/987/complete",
  "cancelUrl": "https://shop.example/orders/987",
  "parentOrigin": "https://shop.example",
  "presentation": "sheet"
}
```

The browser cannot change the amount or merchant after session creation.

## Server-configured offer

For a Boxpressd-owned purchase, send an offer code. Payments loads the price and effects from the active immutable offer version.

```json theme={null}
{
  "action": "purchase",
  "actor": { "type": "boxpressd_user", "id": "123" },
  "billingAccountId": "00000000-0000-0000-0000-000000000001",
  "billingAccountAssertion": "<short-lived-signed-assertion>",
  "offerCode": "developer-ai-credits-1000",
  "returnUrl": "https://developers.boxpressd.com/dashboard/apps/app_123/ai?payments=returned",
  "cancelUrl": "https://developers.boxpressd.com/dashboard/apps/app_123/ai?payments=cancelled",
  "presentation": "page"
}
```

## Manage saved methods

Create a session with `action: "manage_methods"` and no offer, credit purchase, subscription, or marketplace order. The hosted screen lets the user add, make default, and remove saved methods.

## Session response

The first successful request returns `201` with a raw one-time URL:

```json theme={null}
{
  "data": {
    "session": {
      "id": "57bb98ed-2c51-4e0a-bb1b-83d5e30b8c89",
      "environment": "development",
      "status": "created",
      "action": "purchase",
      "presentation": "page",
      "expiresAt": "2026-09-10T18:15:00.000Z"
    },
    "url": "https://payments-dev.boxpressd.com/session/<one-time-token>",
    "replayed": false
  }
}
```

An identical idempotency replay returns `200`, `replayed: true`, and `url: null`.