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

# Create a Stripe PaymentIntent for an order (client-side confirmation)

> Starts a card payment for whatever the order still owes. Returns a `clientSecret` to confirm with Stripe.js in the browser — the card details never reach this API. The charge is created on the project's connected account for `total - amountPaid - amountComped`, so part-paid orders are billed only for the remainder and an order paid or comped in full is a 400.

Safe to call more than once: an order has at most one open card payment. If its open intent can still be paid and is for the amount owed now, its existing `clientSecret` is returned instead of a second intent being created, so a user who reloads checkout is not charged twice. If the amount owed has changed since, the old intent is canceled and a new one is created for the new amount. While a card payment on the order is already moving (processing, or a saved-card charge in flight), the call is a 409 `PAYMENT_IN_FLIGHT`: wait for it to finish, then read the order's transactions.

The order must be DRAFT or PENDING; anything further along its lifecycle is a 400. A 409 means the project has no Stripe account connected or is not yet cleared to take charges, which is a setup problem no retry will fix. Confirming the intent does NOT settle the transaction here: the row stays PENDING until Stripe's webhook confirms it, so treat payment as complete only once the transaction reads SUCCEEDED.

When the order's client has an email on file, the card is saved to that client for future bookings (the intent is created with `setup_future_usage: off_session`), so tell the client at checkout that their card will be saved. An intent reused from an earlier call is updated to save the card as well, provided the payment has not been confirmed yet.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/projects/{projectId}/orders/{orderId}/payment-intent
openapi: 3.0.0
info:
  title: MarketBox 2.0 Open API
  version: 1.0.0
  description: >-
    The MarketBox public API for building booking experiences. Core model:
    create an order, then draw its order items down into bookings. Single
    bookings reference an order item per service line; package bookings draw one
    PACKAGE item down across N sessions. To schedule a package, build a slate
    (POST /availability/package-slate) and book it by slateId (POST
    /orders/{orderId}/package-bookings). See the guides for end-to-end
    walkthroughs.
  contact:
    name: MarketBox support
servers:
  - url: https://apiv2.gomarketbox.com
    description: MarketBox Open API
security:
  - ApiKeyAuth: []
paths:
  /v1/projects/{projectId}/orders/{orderId}/payment-intent:
    post:
      tags:
        - Transactions
      summary: Create a Stripe PaymentIntent for an order (client-side confirmation)
      description: >-
        Starts a card payment for whatever the order still owes. Returns a
        `clientSecret` to confirm with Stripe.js in the browser — the card
        details never reach this API. The charge is created on the project's
        connected account for `total - amountPaid - amountComped`, so part-paid
        orders are billed only for the remainder and an order paid or comped in
        full is a 400.


        Safe to call more than once: an order has at most one open card payment.
        If its open intent can still be paid and is for the amount owed now, its
        existing `clientSecret` is returned instead of a second intent being
        created, so a user who reloads checkout is not charged twice. If the
        amount owed has changed since, the old intent is canceled and a new one
        is created for the new amount. While a card payment on the order is
        already moving (processing, or a saved-card charge in flight), the call
        is a 409 `PAYMENT_IN_FLIGHT`: wait for it to finish, then read the
        order's transactions.


        The order must be DRAFT or PENDING; anything further along its lifecycle
        is a 400. A 409 means the project has no Stripe account connected or is
        not yet cleared to take charges, which is a setup problem no retry will
        fix. Confirming the intent does NOT settle the transaction here: the row
        stays PENDING until Stripe's webhook confirms it, so treat payment as
        complete only once the transaction reads SUCCEEDED.


        When the order's client has an email on file, the card is saved to that
        client for future bookings (the intent is created with
        `setup_future_usage: off_session`), so tell the client at checkout that
        their card will be saved. An intent reused from an earlier call is
        updated to save the card as well, provided the payment has not been
        confirmed yet.
      parameters:
        - schema:
            type: string
            minLength: 1
            description: >-
              The project (tenant) that owns the resource. Every resource in
              this API is scoped to a project, and your API key is restricted to
              the projects it was issued for — a project outside that scope
              returns 403.
            example: prj_01kv60qgnef2kt3pvqgwmkbzfr
          required: true
          description: >-
            The project (tenant) that owns the resource. Every resource in this
            API is scoped to a project, and your API key is restricted to the
            projects it was issued for — a project outside that scope returns
            403.
          name: projectId
          in: path
        - schema:
            type: string
            minLength: 1
            description: >-
              The order — the commercial record. Order items are drawn down into
              bookings.
            example: ord_01kv8m92p4jcrywn14znp8cym0
          required: true
          description: >-
            The order — the commercial record. Order items are drawn down into
            bookings.
          name: orderId
          in: path
      responses:
        '201':
          description: PaymentIntent created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      clientSecret:
                        type: string
                        minLength: 1
                      paymentIntentId:
                        type: string
                        minLength: 1
                      transactionId:
                        type: string
                        minLength: 1
                      amount:
                        $ref: '#/components/schemas/Money'
                    required:
                      - clientSecret
                      - paymentIntentId
                      - transactionId
                      - amount
                required:
                  - data
        '400':
          description: Nothing owed / invalid order state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '409':
          description: >-
            Project not charge-ready, or a card payment on the order is already
            in progress (PAYMENT_IN_FLIGHT): wait for it to finish, then read
            the order’s transactions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
components:
  schemas:
    Money:
      type: object
      properties:
        amount:
          type: integer
          minimum: 0
        currency:
          type: string
          minLength: 1
          maxLength: 3
      required:
        - amount
        - currency
    ErrorMessage:
      type: object
      properties:
        code:
          type: string
          description: Stable machine-readable error code, e.g. NOT_FOUND.
        message:
          type: string
          description: Human-readable description of what went wrong.
        statusCode:
          type: integer
          description: The HTTP status code of this response.
        requestId:
          type: string
          description: >-
            The id of this request, also returned as the X-Request-Id header.
            Quote it in a support ticket.
      required:
        - code
        - message
        - statusCode
        - requestId
      example:
        code: NOT_FOUND
        message: Booking not found
        statusCode: 404
        requestId: a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API key minted in the MarketBox dashboard. Scope is restricted to the
        projects you select at creation time. Every route needs the key's
        standard API access (`*`) except `POST /v1/projects/{projectId}/events`,
        which needs `events:write`; a key without `*` is refused with 403
        `CAPABILITY_NOT_GRANTED`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.