> ## Documentation Index
> Fetch the complete documentation index at: https://walletconnect-pay-docs-wcagent-webview-integration-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a new payment

> Creates a new payment with the provided payment details.



## OpenAPI

````yaml api/2026-02-18.json POST /v1/payments
openapi: 3.1.0
info:
  title: WalletConnect Pay API
  version: '2026-02-18'
servers:
  - url: https://api.pay.walletconnect.com
security:
  - API Key: []
  - ApiKey: []
  - AppId: []
tags:
  - name: Gateway
  - name: Payments
  - name: Refunds
  - name: Merchant Management
  - name: Settlements
  - name: Crypto Settlement
paths:
  /v1/payments:
    post:
      tags:
        - Payments
      summary: Create a new payment
      description: Creates a new payment with the provided payment details.
      operationId: paymentsCreatePayment
      parameters:
        - name: Api-Key
          in: header
          required: true
          schema:
            type: string
        - name: Merchant-Id
          in: header
          required: true
          schema:
            type: string
        - name: WCP-Version
          in: header
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: Sdk-Name
          in: header
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: Sdk-Version
          in: header
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: Sdk-Platform
          in: header
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type:
              - string
              - 'null'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePayment'
        required: true
      responses:
        '201':
          description: Payment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePaymentResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    CreatePayment:
      type: object
      required:
        - referenceId
        - amount
      properties:
        amount:
          $ref: '#/components/schemas/AmountParameter'
        expiresAt:
          type:
            - integer
            - 'null'
          format: int64
        referenceId:
          type: string
      example:
        amount:
          unit: iso4217/USD
          value: '100'
        expiresAt: null
        referenceId: ORDER-123
    CreatePaymentResponse:
      type: object
      required:
        - paymentId
        - status
        - expiresAt
        - isFinal
        - gatewayUrl
      properties:
        expiresAt:
          type: integer
          format: int64
          description: Payment expiration timestamp, in seconds since epoch
          minimum: 0
        gatewayUrl:
          type: string
          description: Gateway URL to redirect the user to for payment
        isFinal:
          type: boolean
          description: >-
            True if the payment is in a final state and no longer requires
            polling
        paymentId:
          $ref: '#/components/schemas/PaymentId'
          description: Payment ID
        pollInMs:
          type:
            - integer
            - 'null'
          format: int64
          description: |-
            Time to poll for payment status, in milliseconds. Not present if the
            payment is in a final state.
          minimum: 0
        status:
          $ref: '#/components/schemas/PaymentStatus'
          description: Payment status
      example:
        expiresAt: 1718236800
        gatewayUrl: https://api.pay.walletconnect.com/pay_123
        isFinal: false
        paymentId: pay_fea2ecc101KQFN7X7QP87PNA9SVQNAQAFP
        pollInMs: 1000
        status: requires_action
    ErrorResponse:
      type: object
      description: Standard error response structure for API errors.
      required:
        - code
        - message
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
    AmountParameter:
      type: object
      required:
        - unit
        - value
      properties:
        unit:
          type: string
          description: Currency unit, prefixed with either "iso4217/" or "caip19/"
          example: iso4217/USD
        value:
          type: string
          description: Amount value, in the currency unit's minor units
      example:
        unit: iso4217/USD
        value: '100'
    PaymentId:
      type: string
      description: Payment ID
      examples:
        - pay_7fa2ecc101ARZ3NDEKTSV4RRFFQ69G5FAV
    PaymentStatus:
      type: string
      description: |-
        Payment status representing the lifecycle of a payment.

        Payments progress through these states from creation to terminal status.
        Some states are specific to the payment source (pull vs push).
      enum:
        - requires_action
        - processing
        - succeeded
        - failed
        - expired
        - cancelled
    ErrorCode:
      type: string
      description: |-
        Standard error codes for API responses.

        This prevents typos like "invlaid_params" from reaching production.
      enum:
        - rate_limited
        - invalid_params
        - params_validation
        - payment_not_found
        - idempotency_conflict
        - internal_error
        - invalid_api_key
        - unauthorized
        - forbidden
        - invalid_state
        - payment_expired
        - quote_expired
        - missing_api_key
        - missing_merchant_api_key
        - missing_merchant_id
        - header_not_ascii
        - not_sandbox_api_key
        - merchant_not_found
        - merchant_exists
        - api_key_not_found
        - partner_not_found
        - customer_not_found
        - wallet_not_found
        - executor_not_found
        - missing_app_id
        - missing_client_id
        - invalid_app_id
        - conflicting_auth_headers
        - missing_auth_headers
        - invalid_api_version
        - unknown_api_version
        - api_version_downgrade
        - sanctioned_user
        - payment_not_succeeded
        - already_refunded
  securitySchemes:
    API Key:
      type: apiKey
      in: header
      name: Api-Key
    ApiKey:
      type: apiKey
      in: header
      name: Api-Key
      description: Private API key for wallet authentication
    AppId:
      type: apiKey
      in: header
      name: App-Id
      description: >-
        Public App ID for wallet authentication. When using this auth mode, the
        Client-Id header is also required.

````