NOWPayments Payments API

openapi: 3.0.3
info:
  title: NOWPayments Authentication Payments API
  description: 'NOWPayments is a crypto payment gateway that enables businesses to accept 300+ cryptocurrencies, create payment invoices, process recurring subscriptions, and manage merchant mass payouts. The API supports automatic coin conversion, IPN webhooks, and fiat withdrawals.

    '
  version: 1.0.0
  contact:
    name: NOWPayments Support
    email: support@nowpayments.io
    url: https://nowpayments.io/help
  termsOfService: https://nowpayments.io/terms
servers:
- url: https://api.nowpayments.io/v1
  description: Production server
- url: https://api.sandbox.nowpayments.io/v1
  description: Sandbox server
security:
- ApiKeyAuth: []
tags:
- name: Payments
  description: Payment creation and management
paths:
  /payment:
    post:
      operationId: createPayment
      summary: Create a payment
      description: 'Creates a new cryptocurrency payment. The customer will send crypto to the returned pay_address. Supports automatic coin conversion and IPN webhook notifications.

        '
      tags:
      - Payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentRequest'
            example:
              price_amount: 100
              price_currency: usd
              pay_currency: btc
              ipn_callback_url: https://example.com/ipn
              order_id: ORDER-12345
              order_description: Apple Macbook Pro 2019 x 1
      responses:
        '201':
          description: Payment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    get:
      operationId: listPayments
      summary: List payments
      description: Returns a paginated list of all payments for the merchant account.
      tags:
      - Payments
      parameters:
      - name: limit
        in: query
        description: Number of records per page (default 10)
        schema:
          type: integer
          default: 10
          minimum: 1
          maximum: 500
      - name: page
        in: query
        description: Page number (0-indexed)
        schema:
          type: integer
          default: 0
          minimum: 0
      - name: sortBy
        in: query
        description: Field to sort by
        schema:
          type: string
          enum:
          - payment_id
          - payment_status
          - pay_address
          - price_amount
          - price_currency
          - pay_amount
          - pay_currency
          - order_id
          - created_at
          - updated_at
      - name: orderBy
        in: query
        description: Sort direction
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: dateFrom
        in: query
        description: Filter payments from this date (ISO 8601)
        schema:
          type: string
          format: date-time
      - name: dateTo
        in: query
        description: Filter payments up to this date (ISO 8601)
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: List of payments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /payment/{payment_id}:
    get:
      operationId: getPaymentStatus
      summary: Get payment status
      description: Returns the current status and details of a specific payment.
      tags:
      - Payments
      parameters:
      - name: payment_id
        in: path
        required: true
        description: Unique payment identifier
        schema:
          type: string
          example: '5045208125'
      responses:
        '200':
          description: Payment details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentStatusResponse'
              example:
                payment_id: 5045208125
                payment_status: waiting
                pay_address: 3EktnHQD7RiAE6uzMj2ZifT9YgRrkSgzQX
                price_amount: 100
                price_currency: usd
                pay_amount: 0.00267
                actually_paid: 0
                pay_currency: btc
                order_id: ORDER-12345
                order_description: Apple Macbook Pro 2019 x 1
                purchase_id: 4944856743
                created_at: '2021-01-15T12:00:00.000Z'
                updated_at: '2021-01-15T12:00:00.000Z'
                outcome_amount: 0.00267
                outcome_currency: btc
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    PaymentResponse:
      type: object
      properties:
        payment_id:
          type: integer
          description: Unique payment identifier
        payment_status:
          type: string
          description: Current payment status
          enum:
          - waiting
          - confirming
          - confirmed
          - sending
          - partially_paid
          - finished
          - failed
          - refunded
          - expired
        pay_address:
          type: string
          description: Cryptocurrency address to which the customer should send payment
        price_amount:
          type: number
          format: double
          description: Requested payment amount in fiat currency
        price_currency:
          type: string
          description: Fiat currency of the price amount
        pay_amount:
          type: number
          format: double
          description: Amount to pay in cryptocurrency
        pay_currency:
          type: string
          description: Cryptocurrency for payment
        order_id:
          type: string
          description: Merchant order ID
        order_description:
          type: string
          description: Order description
        ipn_callback_url:
          type: string
          description: IPN callback URL
        created_at:
          type: string
          format: date-time
          description: Payment creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Payment last update timestamp
        purchase_id:
          type: integer
          description: Purchase identifier
    PaymentListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PaymentStatusResponse'
        limit:
          type: integer
          description: Records per page
        page:
          type: integer
          description: Current page number
        pagesCount:
          type: integer
          description: Total number of pages
        total:
          type: integer
          description: Total number of payments
    CreatePaymentRequest:
      type: object
      required:
      - price_amount
      - price_currency
      - pay_currency
      properties:
        price_amount:
          type: number
          format: double
          description: Fiat equivalent of the price to be paid in crypto
          example: 100
        price_currency:
          type: string
          description: Fiat currency in which price_amount is specified (e.g., usd, eur)
          example: usd
        pay_amount:
          type: number
          format: double
          description: Amount users have to pay in crypto (overrides price_amount conversion)
        pay_currency:
          type: string
          description: Cryptocurrency in which to receive payment
          example: btc
        ipn_callback_url:
          type: string
          format: uri
          description: URL to receive IPN callback notifications
        order_id:
          type: string
          description: Merchant order ID for reconciliation
          example: ORDER-12345
        order_description:
          type: string
          description: Human-readable order description
          example: Apple Macbook Pro 2019 x 1
        purchase_id:
          type: string
          description: ID of existing purchase to create additional payment for
        payout_address:
          type: string
          description: Custom payout address (overrides account default)
        payout_currency:
          type: string
          description: Currency for the payout address (required when payout_address is specified)
        payout_extra_id:
          type: string
          description: Extra ID, memo, or tag for the payout address
        fixed_rate:
          type: boolean
          description: Use fixed exchange rate for the payment
    PaymentStatusResponse:
      allOf:
      - $ref: '#/components/schemas/PaymentResponse'
      - type: object
        properties:
          actually_paid:
            type: number
            format: double
            description: Amount actually received so far
          outcome_amount:
            type: number
            format: double
            description: Amount to be credited to merchant after conversion
          outcome_currency:
            type: string
            description: Currency of the outcome amount
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Error message
        errors:
          type: array
          description: Detailed error list
          items:
            type: string
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: NOWPayments API key obtained from your merchant dashboard
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from the /auth endpoint (required for mass payout operations)
externalDocs:
  description: NOWPayments API Documentation
  url: https://nowpayments.io/help/api