POST /v1/payment

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

Request

POST /v1/payment

Request Body

Field	Type	Required	Description
price_amount	number	Yes	Amount in price_currency (max 1,000,000,000)
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 (must be valid HTTP/HTTPS)
pay_amount	number	No	Override the calculated pay amount
purchase_id	string	No	Custom purchase ID (auto-generated if omitted)
payout_address	string	No	Custom payout address
payout_currency	string	No	Custom payout currency
payout_extra_id	string	No	Extra ID for payout (e.g., memo)
is_fixed_rate	boolean	No	Use exact output mode for settlement amount
is_fee_paid_by_user	boolean	No	Whether the buyer pays the fee

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,
  "payment_status": "waiting",
  "pay_address": "bc1q...",
  "price_amount": 25.50,
  "price_currency": "usd",
  "pay_amount": 0.00029,
  "actually_paid": 0,
  "pay_currency": "btc",
  "order_id": "order-42",
  "order_description": null,
  "purchase_id": 5234123456,
  "outcome_amount": null,
  "outcome_currency": null,
  "invoice_id": null,
  "payin_extra_id": null,
  "payin_hash": null,
  "payout_hash": null,
  "burning_percent": "null",
  "type": "crypto2crypto",
  "created_at": "2025-01-15T10:30:00.000Z",
  "updated_at": "2025-01-15T10:30:00.000Z"
}