API Reference

Create a checkout session

Turn a saved Quote into its one Brek-hosted payment handoff or native payment authorization. Each Quote can create exactly one checkout.

POST/api/v1/agent-commerce/checkout-sessions

Headers

Authorization

string · required

Bearer $BREK_AGENT_API_KEY. Keep the key server-side.

Content-Type

string · required

application/json

Idempotency-Key

string · required

A unique value whose trimmed length is at least 8 characters and that identifies one logical write. The current contract publishes no maximum length or restricted character set; for portability, use a conservative ASCII UUID-like token without leading or trailing whitespace and retain its exact bytes. The key alone does not make a replay safe, and there is no universal retention promise: recovery lifetime and lookup scope are specific to the Quote, checkout session, booking, and operation. Follow the operation-specific recovery contract.

Parameters

quoteId

string · required

quote.id returned by the Quote endpoint. The first logical create atomically reserves this Quote. Only after an ambiguous transport result or HTTP 502, 503, or 504 may trusted code recover with the same Idempotency-Key and byte-identical retained body. The key alone is not replay permission; obtain a fresh Quote for any different checkout attempt.

mode

hosted | native · required

Hosted opens Brek checkout. Native returns a payment client secret to the authenticated caller.

holder / occupancies

object / array · required

Lead guest and 1–3 nonempty room occupancies used for the reservation. holder.name and holder.surName are required and must each contain at least 2 characters. Every pax requires an integer age from 0 through 120; pax name/surName are optional in the backend contract and, when supplied, must each contain at least 2 characters. Carry the exact room order and guest-age structure approved in Quote. You do not need to supply occupancyId: Brek assigns backend room IDs from that validated party. Preserve any explicit occupancyId values already supplied in Quote.

customer.email

email · required

Traveler email used for the booking confirmation.

returnUrl

absolute URL · optional

Optional destination shown as an explicit Return to agent button after hosted authorization. Brek does not redirect automatically. The runtime requires a URL with a protocol; use HTTPS outside local development.

partnerReference

string <= 120 characters · optional

Caller reconciliation reference. Brek generates agent-{checkoutSessionId} when omitted. It is not the Brek bookingReference and does not replace Idempotency-Key.

Request

{
  "quoteId": "quote_123",
  "mode": "hosted",
  "holder": { "name": "Ada", "surName": "Lovelace" },
  "occupancies": [{
    "paxes": [{ "age": 34, "name": "Ada", "surName": "Lovelace" }]
  }],
  "customer": { "email": "ada@example.com" },
  "partnerReference": "trip_456",
  "returnUrl": "https://agent.example.com/trips/456"
}

cURL

Replace every placeholder and run this from a trusted server-side environment. Never expose the API key in browser code.

curl --request POST "https://api.brek.com/api/v1/agent-commerce/checkout-sessions" \
  --header "Authorization: Bearer $BREK_AGENT_API_KEY" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "quoteId": "quote_123",
  "mode": "hosted",
  "holder": { "name": "Ada", "surName": "Lovelace" },
  "occupancies": [{
    "paxes": [{ "age": 34, "name": "Ada", "surName": "Lovelace" }]
  }],
  "customer": { "email": "ada@example.com" },
  "partnerReference": "trip_456",
  "returnUrl": "https://agent.example.com/trips/456"
}
JSON

Response

{
  "object": "agent_commerce.checkout_session",
  "id": "acs_123",
  "mode": "hosted",
  "environment": "test",
  "status": "awaiting_payment",
  "expiresAt": "<checkout expiry: ISO 8601>",
  "price": {
    "payNow": { "amount": 281.42, "currency": "USD" },
    "payAtProperty": { "amount": 5.00, "currency": "USD" },
    "travelerTotal": { "amount": 286.42, "currency": "USD" }
  },
  "approvalReceipt": {
    "object": "agent_commerce.approval_receipt",
    "version": 1,
    "quoteId": "quote_123",
    "issuedAt": "<receipt issue time: ISO 8601>",
    "validUntil": "<quote expiry: ISO 8601>",
    "hotel": {
      "propertyId": "hotel_123",
      "name": "Example Hotel",
      "type": "Hotel"
    },
    "stay": {
      "checkIn": "<booked check-in: YYYY-MM-DD>",
      "checkOut": "<booked check-out: YYYY-MM-DD>",
      "roomCodes": ["KING"],
      "roomNames": ["King Room"]
    },
    "price": {
      "payNow": { "amount": 281.42, "currency": "USD" },
      "payAtProperty": { "amount": 5.00, "currency": "USD" },
      "travelerTotal": { "amount": 286.42, "currency": "USD" }
    },
    "cancellationPolicy": {
      "refundable": true,
      "currency": "USD",
      "deadlineTimezone": "UTC",
      "cancelPenalties": [],
      "summary": "Refundable with no monetary cancellation penalty currently listed."
    },
    "travelerSafe": true,
    "partnerEconomicsIncluded": false,
    "sourceQuoteFingerprint": "<opaque hash>",
    "fingerprint": "<64 lowercase hex characters>"
  },
  "payment": {
    "provider": "stripe",
    "status": "requires_payment_method",
    "livemode": false,
    "publishableKey": "pk_test_...",
    "authorizationOwner": "calling_agent_or_traveler"
  },
  "action": {
    "type": "open_hosted_checkout",
    "url": "https://www.brek.com/checkout/agent/acs_123?token=<redacted>"
  }
}

Native checkout response

Native mode returns the Stripe.js inputs only to the authenticated caller. Hand them directly to the traveler's secure payment UI.

{
  "object": "agent_commerce.checkout_session",
  "id": "acs_123",
  "mode": "native",
  "environment": "test",
  "status": "awaiting_payment",
  "expiresAt": "<expiry time: ISO 8601>",
  "price": {
    "payNow": {
      "amount": 281.42,
      "currency": "USD"
    },
    "payAtProperty": {
      "amount": 5,
      "currency": "USD"
    },
    "travelerTotal": {
      "amount": 286.42,
      "currency": "USD"
    }
  },
  "approvalReceipt": {
    "object": "agent_commerce.approval_receipt",
    "version": 1,
    "quoteId": "quote_123",
    "issuedAt": "<receipt issue time: ISO 8601>",
    "validUntil": "<quote expiry: ISO 8601>",
    "hotel": {
      "propertyId": "hotel_123",
      "name": "Example Hotel",
      "type": "Hotel"
    },
    "stay": {
      "checkIn": "<future check-in: YYYY-MM-DD>",
      "checkOut": "<future check-out: YYYY-MM-DD>",
      "roomCodes": [
        "KING"
      ],
      "roomNames": [
        "King Room"
      ]
    },
    "price": {
      "payNow": {
        "amount": 281.42,
        "currency": "USD"
      },
      "payAtProperty": {
        "amount": 5,
        "currency": "USD"
      },
      "travelerTotal": {
        "amount": 286.42,
        "currency": "USD"
      }
    },
    "cancellationPolicy": {
      "refundable": true,
      "currency": "USD",
      "deadlineTimezone": "UTC",
      "cancelPenalties": [],
      "summary": "Refundable with no monetary cancellation penalty currently listed."
    },
    "travelerSafe": true,
    "partnerEconomicsIncluded": false,
    "sourceQuoteFingerprint": "quote_snapshot_123",
    "fingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  },
  "payment": {
    "provider": "stripe",
    "status": "requires_payment_method",
    "livemode": false,
    "publishableKey": "pk_test_...",
    "authorizationOwner": "calling_agent_or_traveler",
    "clientSecret": "<sensitive Stripe client secret>"
  },
  "action": {
    "type": "confirm_payment_natively_then_confirm_booking"
  }
}

Response fields

id

string

Checkout session identifier used for status and confirm.

environment

live | test

Whether payment and booking are real or simulated.

price.payNow

Money

Amount Brek will authorize and capture through Stripe. It is copied from the saved Quote for the complete stay and all requested rooms.

price.payAtProperty

Money

Known mandatory amount paid directly to the hotel, not charged by Brek.

price.travelerTotal

Money

price.payNow + price.payAtProperty in the same currency. It excludes optional incidentals, deposits, and charges the API does not return.

approvalReceipt.price

CheckoutPrice

Authoritative approved Quote tax-and-fee breakdown frozen for this checkout. If checkout's top-level price.sourceCompleteness is false for an optional component, present approvalReceipt.price rather than inferring zero or reconstructing the value.

payment

object

Authorization status. Native checkout creation also returns publishableKey and a one-time-delivery clientSecret for Stripe.js in the secure payment UI; ordinary status retrieval omits the client secret.

payment.livemode

boolean

Stripe mode assertion. This must be false for a Test application and true for Live.

payment.publishableKey / payment.clientSecret

string

Native Stripe.js configuration scoped to this checkout's environment. The client secret appears only in the POST create response or the documented same-key, byte-identical recovery after an ambiguous transport result or HTTP 502, 503, or 504 while checkout awaits payment; GET/status and later lifecycle responses omit it. Use the returned publishable key; do not substitute another environment's key. The client secret is sensitive and belongs only in the traveler's secure payment UI.

action

object

The exact next step for hosted or native checkout.

Payment authorization is not a booking

Process the entire checkout response in trusted non-model code. Never serialize or log the full response, raw card data, payment.clientSecret, or the signed hosted action.url. Give the model only an explicit allowlisted non-secret summary such as checkout id, environment, status, expiry, display labels, price totals, payment status, and action type. Do not send sensitive values through a model prompt, trace, analytics event, shared log, screenshot, support ticket, or persistent storage; hand them directly to the traveler's secure payment UI. The hosted page consumes its signed token, removes it from the address bar, and retains it only in page memory. Hosted returnUrl creates a traveler-clicked button after authorization and never an automatic redirect. Before Confirm, poll only awaiting_payment; continue only for payment_authorized and stop immediately for failed, cancelled, expired, expiry_requires_attention, or any unexpected state. A checkout session can authorize payment, but a real hotel booking requires Confirm to return status=confirmed, environment=live, and isSimulation=false. A confirmed Test response is simulated. quote_checkout_conflict means this Quote already owns a checkout: recover the identified checkout or obtain a fresh Quote, never rotate keys to create a second session.

← All endpoints Quickstart Pricing contract

Create a checkout session

Headers

Parameters

Request

cURL

Response

Native checkout response

Response fields

Brek

Brek with AI

Developers

Legal