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

# Create a payment link

> Creates a link for an amount in fiat, payable in any of `allowedAssets`. Send the payer to `https://pay.staging.paywire.xyz/pay/{id}`.

Create one link per purchase and send the payer to `https://pay.staging.paywire.xyz/pay/{id}`. See [Create a payment link](https://docs.paywire.xyz/guides/create-payment-link.md) for the full walkthrough.


## OpenAPI

````yaml POST /payments/links
openapi: 3.1.0
info:
  title: Paywire API
  version: 1.0.0
  description: >-
    Accept crypto payments: create payment links, follow orders, receive signed
    webhooks.
servers:
  - url: https://api.staging.paywire.xyz
    description: Staging (testnets)
security:
  - apiKey: []
tags:
  - name: Payment links
  - name: Orders
  - name: Account
  - name: Webhooks
paths:
  /payments/links:
    post:
      tags:
        - Payment links
      summary: Create a payment link
      description: >-
        Creates a link for an amount in fiat, payable in any of `allowedAssets`.
        Send the payer to `https://pay.staging.paywire.xyz/pay/{id}`.
      operationId: createPaymentLink
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentLinkRequest'
            example:
              amount: 49.9
              currency: USD
              callbackUrl: https://shop.example.com/webhooks/paywire
              returnUrl: https://shop.example.com/orders/1042
              orderTtlMinutes: 20
              allowedAssets:
                - network: ethereum_sepolia
                  token: '0x1c7d4b196cb0c7b01d743fbc6116a902379c7238'
                - network: solana_devnet
                  token: native
      responses:
        '201':
          description: The payment link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentLink'
              example:
                id: 0193a0c4-5f2e-7c1d-9b8a-3e4f5a6b7c8d
                merchantId: 0193a0b1-2c3d-7e4f-8a9b-0c1d2e3f4a5b
                amount: 49.9
                currency: USD
                allowedAssets:
                  - network: ethereum_sepolia
                    token: '0x1c7d4b196cb0c7b01d743fbc6116a902379c7238'
                    decimals: 6
                  - network: solana_devnet
                    token: native
                    decimals: 9
                callbackUrl: https://shop.example.com/webhooks/paywire
                orderTtlMinutes: 20
                policyOverride: null
                returnUrl: https://shop.example.com/orders/1042
                isActive: true
                createdAt: '2026-10-24T09:12:31.204Z'
        '400':
          description: Invalid request.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                title: PaymentLink.NoAllowedAssets
                status: 400
                detail: A link needs at least one allowed asset.
        '401':
          description: Missing, unknown or revoked API key.
        '409':
          description: The gateway is disabled.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                title: Merchant.Disabled
                status: 409
                detail: This merchant is disabled and can't take new payments.
components:
  schemas:
    CreatePaymentLinkRequest:
      type: object
      required:
        - amount
        - allowedAssets
        - callbackUrl
      properties:
        amount:
          type: number
          exclusiveMinimum: 0
          description: Price in `currency`.
        currency:
          type: string
          default: USD
        allowedAssets:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/AssetRef'
          description: Coins the payer may pay with.
        callbackUrl:
          type: string
          format: uri
          description: Absolute https URL for webhooks.
        returnUrl:
          type:
            - string
            - 'null'
          format: uri
          description: Absolute https URL offered to the payer after paying.
        orderTtlMinutes:
          type:
            - integer
            - 'null'
          minimum: 5
          maximum: 1440
          description: How long a quote holds. Default 30.
        policyOverride:
          $ref: '#/components/schemas/PolicyOverride'
    PaymentLink:
      type: object
      properties:
        id:
          type: string
          format: uuid
        merchantId:
          type: string
          format: uuid
        amount:
          type: number
        currency:
          type: string
        allowedAssets:
          type: array
          items:
            $ref: '#/components/schemas/Asset'
        callbackUrl:
          type: string
          format: uri
        orderTtlMinutes:
          type: integer
        policyOverride:
          $ref: '#/components/schemas/PolicyOverride'
        returnUrl:
          type:
            - string
            - 'null'
          format: uri
        isActive:
          type: boolean
        createdAt:
          type: string
          format: date-time
    Problem:
      type: object
      description: RFC 7807 problem details. `title` is a stable error code.
      properties:
        type:
          type: string
        title:
          type: string
          example: PaymentLink.NotFound
        status:
          type: integer
        detail:
          type: string
    AssetRef:
      type: object
      required:
        - network
        - token
      properties:
        network:
          type: string
          example: ethereum_sepolia
          description: Network id. See Networks and assets.
        token:
          type: string
          example: native
          description: >-
            `native` for the network's coin, else the token contract (mint on
            Solana).
    PolicyOverride:
      type:
        - object
        - 'null'
      description: This link's own payment policy, replacing the company's.
      properties:
        tolerancePercent:
          type:
            - number
            - 'null'
          description: Shortfall or excess, in %, that still counts as exact.
        overpayDustThreshold:
          type:
            - number
            - 'null'
          description: Fiat excess kept rather than refunded.
        overpayReviewThreshold:
          type:
            - number
            - 'null'
          description: Fiat difference above which a person reviews.
    Asset:
      allOf:
        - $ref: '#/components/schemas/AssetRef'
        - type: object
          properties:
            decimals:
              type: integer
              example: 18
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: Your gateway's API key (`w3g_...`).

````

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