---
title: "Create a payment page"
method: POST
path: "/v1/payment_pages"
tags: ["Payment Pages"]
---

# Create a payment page

`POST /v1/payment_pages`

## Request body

- union — Payment page details
  - object — Payment page details
    - `clientReferenceId` string
    - `successReturnUrl` string
    - `failReturnUrl` string
    - `billingEmail` string, email
    - `location` union — User location details.
      - object
        - `country` string, required
        - `zipcode` string, required
        - `state` string
        - `latitude` number
        - `longitude` number
      - object
        - `country` string, required
        - `zipcode` string
        - `state` string, required
        - `latitude` number
        - `longitude` number
    - `fromChannel` string — The channel through which this payment page was created, valid value are web or app.
    - `lineItems` object[], required
      - `productId` string, required — The Breeze product ID to attach to this line item. Mutually exclusive with clientProductId.
      - `quantity` integer, required — Number of units of this product. Minimum 1.
    - `settings` object
      - `expireInSeconds` number — Expiration in seconds. Defaults to 7 days (604,800 seconds). The maximum allowed expiration is 90 days (7,776,000 seconds).
      - `flexibleAmount` object — Allow payers to choose a flexible deduction amount up to a maximum, or specify it as a percentage or fixed value. At least one of percentage or fixedAmount must be provided. Only enabled for the crypto deposit payment type.
        - `maxAmount` integer — Maximum flexible deduction amount (in minor units, eg: 100 for $1.00). Optional.
        - `percentage` number — Flexible deduction amount as a percentage of the base amount. Optional.
        - `fixedAmount` integer — Fixed flexible deduction amount (in minor units, eg: 100 for $1.00). Optional.
    - `description` string
    - `customer` union — Customer identification. Provide exactly one of the three variants below.
      - object — Look up an existing customer by their Breeze `cus_*` ID. No other customer fields may be sent in this mode.
        - `id` string, required
      - object — Look up an existing customer by your `referenceId`. This is a strict lookup: if no customer with this `referenceId` exists, the request fails with `RESOURCE_NOT_FOUND`. To create the customer in the same request when it may not exist yet, use the inline create / update variant below (add `signupAt`). No other customer fields may be sent in this mode.
        - `referenceId` string, required
      - object — Create or update a customer inline in a single request. `referenceId` and `signupAt` are required — `signupAt` is what switches this from a lookup to a create-or-update. If a customer with this `referenceId` already exists it is updated, otherwise it is created. Include any other customer details to store.
        - `referenceId` string, required
        - `signupAt` integer, required
        - `email` string, email
        - `firstName` string
        - `middleName` string
        - `lastName` string
        - `dateOfBirth` string
        - `address` object
          - `line1` string
          - `line2` string
          - `city` string
          - `country` string
          - `state` string
          - `postalCode` union
            - string
            - string
        - `phoneNumber` string
  - object — Payment page details
    - `clientReferenceId` string
    - `successReturnUrl` string
    - `failReturnUrl` string
    - `billingEmail` string, email
    - `location` union — User location details.
      - object
        - `country` string, required
        - `zipcode` string, required
        - `state` string
        - `latitude` number
        - `longitude` number
      - object
        - `country` string, required
        - `zipcode` string
        - `state` string, required
        - `latitude` number
        - `longitude` number
    - `fromChannel` string — The channel through which this payment page was created, valid value are web or app.
    - `lineItems` object[], required
      - `quantity` integer, required — Number of units of this product. Minimum 1.
      - `clientProductId` string, required — Your unique identifier for this product. Minimum 1 character, maximum 100 characters. Allowed characters: letters (a–z, A–Z), numbers (0–9), dot (.), underscore (_), and hyphen (-). Example: 'prod_123', 'my-product.v2'.
      - `displayName` string, required — The name of the product shown to customers.
      - `description` string — Optional description of the product shown to customers. Minimum 1 character, maximum 280 characters.
      - `image` string, uri — URL of the product image shown to customers.
      - `amount` integer, required — Price of the product in minor units / cents (e.g., currency: "USD", 1000 = USD 10).
      - `currency` 'USD' | 'AUD' | 'CAD' | 'CHF' | 'DKK' | 'EUR' | 'GBP' | 'NOK' | 'NZD' | 'PLN' | 'SEK' | 'SGD', required — Three-letter ISO currency code for the product price. Supported values: USD, AUD, CAD, CHF, DKK, EUR, GBP, NOK, NZD, PLN, SEK, SGD.
    - `settings` object
      - `expireInSeconds` number — Expiration in seconds. Defaults to 7 days (604,800 seconds). The maximum allowed expiration is 90 days (7,776,000 seconds).
      - `flexibleAmount` object — Allow payers to choose a flexible deduction amount up to a maximum, or specify it as a percentage or fixed value. At least one of percentage or fixedAmount must be provided. Only enabled for the crypto deposit payment type.
        - `maxAmount` integer — Maximum flexible deduction amount (in minor units, eg: 100 for $1.00). Optional.
        - `percentage` number — Flexible deduction amount as a percentage of the base amount. Optional.
        - `fixedAmount` integer — Fixed flexible deduction amount (in minor units, eg: 100 for $1.00). Optional.
    - `description` string
    - `customer` union — Customer identification. Provide exactly one of the three variants below.
      - object — Look up an existing customer by their Breeze `cus_*` ID. No other customer fields may be sent in this mode.
        - `id` string, required
      - object — Look up an existing customer by your `referenceId`. This is a strict lookup: if no customer with this `referenceId` exists, the request fails with `RESOURCE_NOT_FOUND`. To create the customer in the same request when it may not exist yet, use the inline create / update variant below (add `signupAt`). No other customer fields may be sent in this mode.
        - `referenceId` string, required
      - object — Create or update a customer inline in a single request. `referenceId` and `signupAt` are required — `signupAt` is what switches this from a lookup to a create-or-update. If a customer with this `referenceId` already exists it is updated, otherwise it is created. Include any other customer details to store.
        - `referenceId` string, required
        - `signupAt` integer, required
        - `email` string, email
        - `firstName` string
        - `middleName` string
        - `lastName` string
        - `dateOfBirth` string
        - `address` object
          - `line1` string
          - `line2` string
          - `city` string
          - `country` string
          - `state` string
          - `postalCode` union
            - string
            - string
        - `phoneNumber` string

## Response `200`

Success

- object — The created payment page
  - `status` 'SUCCEEDED', required
  - `data` CreatePaymentPageResponse, required
    - `id` string, required
    - `merchant` object, required
      - `merchantId` string, required
      - `name` string, required
      - `wallet` object
        - `evmAddress` string, required
        - `solanaAddress` string, required
      - `livemode` boolean, required
      - `regionCode` 'US' | 'CA' | 'EU'
      - `checkoutSettings` object
        - `processingChannelIdLivemode` 'pc_jlkqbuuu2svulf7jkiyw5m6w44' | 'pc_cjd2au72ozrelgqc2oi4pjpaoi' | 'pc_jplm2l7q77eunak5ngtyb7yqt4' | 'pc_nddjkfedyxienabgww2d7yqkwa'
        - `processingChannelIdTestmode` string, required
      - `isGiftCardPayinEffective` boolean
      - `gcWalletAddress` string
      - `gcWalletNetwork` 'ETHEREUM' | 'OPTIMISM' | 'BINANCE' | 'POLYGON' | 'ARBITRUM' | 'AVALANCHE' | 'SOLANA' | 'TRON' | 'BASE' | 'BITCOIN'
    - `currency` 'USD' | 'AUD' | 'CAD' | 'CHF' | 'DKK' | 'EUR' | 'GBP' | 'HKD' | 'JPY' | 'NOK' | 'NZD' | 'PLN' | 'SEK' | 'SGD' | 'TWD' | 'KRW' | 'SOL' | 'USDC' | 'USDT' | 'HONEY' | 'EURC', required — Presentment currency — the currency the user sees and pays with.
    - `amount` number, required — Total amount the user sees and pays with, in presentment currency, minor units format (e.g. 10000 for $10.00)
    - `source` 'direct' | 'iap' | 'subscription' | 'card-verification' | 'consumer-onramp', required
    - `lineItems` object[]
      - `productId` string
      - `name` string, required
      - `currency` 'USD' | 'AUD' | 'CAD' | 'CHF' | 'DKK' | 'EUR' | 'GBP' | 'HKD' | 'JPY' | 'NOK' | 'NZD' | 'PLN' | 'SEK' | 'SGD' | 'TWD' | 'KRW' | 'SOL' | 'USDC' | 'USDT' | 'HONEY' | 'EURC', required
      - `amount` number, required
      - `price` number, required
      - `quantity` number, required
      - `description` string
      - `images` string[]
    - `clientReferenceId` string
    - `successReturnUrl` string
    - `failReturnUrl` string
    - `fromChannel` string
    - `createdAt` number, required
    - `url` string, required
    - `clientSecret` string, required
    - `status` 'UNPAID' | 'PAID' | 'EXPIRED' | 'CANCELED', required
    - `isRecurring` boolean, required
    - `billingEmail` string
    - `location` object
      - `country` string, required
      - `zipcode` string
      - `state` string
      - `latitude` number
      - `longitude` number
    - `description` string
    - `expireAtSeconds` number
    - `disputeId` string — Identifies the specific dispute whose state is mirrored onto this page. First-wins binding (mirrors refundId semantics): once set, subsequent disputes against the same page do NOT overwrite — only the dispute matching this id can update disputeStatus. Absent on pages that have never been disputed.
    - `disputeStatus` 'new' | 'actionRequired' | 'ongoing' | 'partialWon' | 'won' | 'lost' | 'canceled' | 'manuallyCanceled' — Mirrors the status of the dispute identified by disputeId. Only updated when the upstream dispute's id matches page.disputeId. Absent on pages that have never been disputed.
    - `displayStatus` 'UNPAID' | 'SUCCESSFUL' | 'REFUNDING' | 'REFUNDED' | 'DISPUTED' | 'EXPIRED' | 'CANCELED' — Derived, user-facing status. Computed from (status, refundStatus, disputeStatus) via computeDisplayStatus(). Written on every state change to those inputs. Absent only on legacy pages predating the backfill.
    - `customer` object
      - `id` string, required
      - `referenceId` string, required
      - `email` string
    - `integrationType` 'HOSTED' | 'SERVER_TO_SERVER' — Integration method: HOSTED (default for all existing pages) or SERVER_TO_SERVER. Absent on legacy documents — treat as HOSTED.
    - `threeDsMode` 'MERCHANT_PROVIDED' | 'BREEZE_HOSTED' — 3DS mode for S2S payments: "MERCHANT_PROVIDED" or "BREEZE_HOSTED". Absent for hosted flows.

## Other responses

- `400` — Bad request
- `401` — Unauthorized

---

[API](https://skmtc.dev/breeze/apis/breeze-api.md) · [All operations](https://skmtc.dev/breeze/apis/breeze-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/breeze/breeze-api/revisions/8911892bdf29/schema)