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

# Create a payment

> Creates a payment and returns the hosted checkout URL to send the buyer to. Call this from your server with your secret key so the amount is fixed server-side. The publishable key is also accepted, for client-side use through the JavaScript SDK.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/payments
openapi: 3.1.0
info:
  title: Paywit API
  version: '1.0'
  description: >-
    Create payments, send buyers to the hosted checkout, and receive a signed
    webhook when they pay.
servers:
  - url: https://api.sandbox.paywit.xyz
    description: Sandbox (Stellar testnet, no real money)
security:
  - SecretKey: []
  - PublishableKey: []
paths:
  /v1/payments:
    post:
      tags:
        - Payments
      summary: Create a payment
      description: >-
        Creates a payment and returns the hosted checkout URL to send the buyer
        to. Call this from your server with your secret key so the amount is
        fixed server-side. The publishable key is also accepted, for client-side
        use through the JavaScript SDK.
      operationId: createPayment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentRequest'
            example:
              amount: 5.43
              description: 'Order #18421'
              clientReferenceId: order_18421
              returnUrl: https://shop.example/orders/18421
      responses:
        '201':
          description: Payment created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePaymentResponse'
              example:
                paymentCheckoutUrl: >-
                  https://checkout.sandbox.paywit.xyz/checkout/0f4c1e2a-7b3d-4e5f-9a6b-1c2d3e4f5a6b
                payment:
                  id: 0f4c1e2a-7b3d-4e5f-9a6b-1c2d3e4f5a6b
                  createdAt: '2026-10-14T09:29:07.335Z'
                  amount: 5.43
                  status: Created
                  description: 'Order #18421'
                  returnUrl: https://shop.example/orders/18421
                  expiresAt: '2026-10-14T10:29:07.335Z'
                  bridgeStatus: null
        '400':
          description: >-
            Malformed or invalid request, for example a non-positive amount or a
            returnUrl that is not http(s). The body says which field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Missing, invalid or revoked API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
        - SecretKey: []
        - PublishableKey: []
components:
  schemas:
    CreatePaymentRequest:
      type: object
      required:
        - amount
      properties:
        amount:
          type: number
          exclusiveMinimum: 0
          description: Amount in USDC.
          example: 5.43
        description:
          type:
            - string
            - 'null'
          description: Shown to the buyer on the checkout.
          example: 'Order #18421'
        clientReferenceId:
          type:
            - string
            - 'null'
          description: >-
            Your own order or invoice id. Echoed back in webhooks so you can
            match the payment to your records.
          example: order_18421
        returnUrl:
          type:
            - string
            - 'null'
          format: uri
          description: >-
            Where the checkout sends the buyer after paying. Must be http or
            https.
          example: https://shop.example/orders/18421
    CreatePaymentResponse:
      type: object
      properties:
        paymentCheckoutUrl:
          type: string
          format: uri
          description: Send the buyer here.
        payment:
          $ref: '#/components/schemas/Payment'
    ApiError:
      type: object
      properties:
        statusCode:
          type: integer
        body:
          description: A message or a validation-problem object describing what went wrong.
    Payment:
      type: object
      properties:
        id:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
        amount:
          type: number
          description: Amount in USDC.
        status:
          type: string
          enum:
            - Created
            - Pending
            - Bridging
            - Paid
            - Expired
            - Failed
            - DestinationMismatch
            - AssetMismatch
            - AmountMismatch
          description: >-
            Treat as an open set and ignore values you do not recognise. See the
            payment statuses guide.
        description:
          type:
            - string
            - 'null'
        returnUrl:
          type:
            - string
            - 'null'
        expiresAt:
          type: string
          format: date-time
          description: >-
            After this time the payment moves to Expired. Bridging payments
            never expire.
        bridgeStatus:
          type:
            - string
            - 'null'
          description: >-
            Cross-chain progress, for example `AwaitingPayment` or `Bridging`.
            Null for same-chain payments.
  securitySchemes:
    SecretKey:
      type: apiKey
      in: header
      name: X-Paywit-Secret-Key
      description: >-
        Server-to-server key, `sk_test_...` on sandbox and `sk_live_...` on
        production. Generate it in the dashboard under your app. Never ship it
        to a browser or mobile app.
    PublishableKey:
      type: apiKey
      in: header
      name: X-Paywit-Publishable-Key
      description: >-
        Client-side key, `pk_test_...` on sandbox and `pk_live_...` on
        production. Safe to embed in a web page. Can only create payments.

````

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