Payments

Create Payment

POST /v1/payment

Creates a new payment. The buyer sends crypto to the returned pay_address.

Request Body

Field	Type	Required	Description
`price_amount`	number	Yes	Amount in `price_currency`
`price_currency`	string	Yes	Fiat or crypto currency code (e.g., `usd`)
`pay_currency`	string	Yes	Cryptocurrency the buyer pays with (e.g., `btc`)
`order_id`	string	No	Your internal order identifier
`order_description`	string	No	Description of the purchase
`ipn_callback_url`	string	No	URL for payment status webhooks

Example

curl -X POST https://api.nearpayments.io/v1/payment \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "price_amount": 25.50,
    "price_currency": "usd",
    "pay_currency": "btc",
    "order_id": "order-42",
    "ipn_callback_url": "https://example.com/webhook"
  }'

Response

{
  "payment_id": 1,
  "purchase_id": 5234123456,
  "payment_status": "waiting",
  "pay_address": "bc1q...",
  "pay_amount": 0.00029,
  "price_amount": 25.50,
  "price_currency": "usd",
  "pay_currency": "btc",
  "order_id": "order-42",
  "created_at": "2025-01-15T10:30:00.000Z",
  "updated_at": "2025-01-15T10:30:00.000Z"
}

Get Payment Status

GET /v1/payment/{payment_id}

Example

curl https://api.nearpayments.io/v1/payment/1 \
  -H "x-api-key: YOUR_API_KEY"

Payment Statuses

Status	Description
`waiting`	Awaiting payment
`confirming`	Transaction detected, waiting for confirmations
`confirmed`	Confirmed on-chain
`sending`	Converting and sending to merchant
`finished`	Payment complete
`partially_paid`	Buyer sent less than required
`failed`	Payment failed
`refunded`	Payment was refunded
`expired`	Payment expired (24h default)

List Payments

GET /v1/payment/

Query Parameters

Parameter	Type	Description
`limit`	number	Results per page (max 500)
`page`	number	Page number
`sortBy`	string	Field to sort by
`orderBy`	string	`asc` or `desc`
`dateFrom`	string	Filter from date
`dateTo`	string	Filter to date