Hosted checkout

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

Authentication

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

string

required

purchase, manage_methods, change_subscription, or buy_credits.

object

required

The boxpressd_user, guest, or service actor and its stable ID.

string

required

The authorized billing account UUID.

string

A short-lived signed assertion when the client policy requires account-specific authorization.

string

required

An exact registered URL or a URL under a registered prefix.

string

A registered destination for cancellation.

string

The registered parent origin when checkout runs in an iframe.

string

default:"page"

page, modal, or sheet.

Marketplace purchase

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

{
  "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.

{
  "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:

{
  "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.

Getting started

Integrate

Credits and billing

Authentication

Session fields

Marketplace purchase

Server-configured offer

Manage saved methods

Session response

​Authentication

​Session fields

​Marketplace purchase

​Server-configured offer

​Manage saved methods

​Session response

Authentication

Session fields

Marketplace purchase

Server-configured offer

Manage saved methods

Session response