OpenAPI Specification
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