Callbacks

NearPayments sends Instant Payment Notification (IPN) callbacks to your server when a payment status changes. The webhook format automatically matches the adapter you used to create the payment.

Adapter	Signature Location	Algorithm	Header / Field
NOWPayments	HTTP header	HMAC-SHA512	`x-nowpayments-sig`
Cryptomus	Embedded in body	MD5	`sign` field in JSON
OxaPay	HTTP header	HMAC-SHA512	`HMAC`

NOWPayments Callback Format

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

Signature is in the x-nowpayments-sig header: HMAC-SHA512 of the sorted JSON body, signed with your IPN Secret.

Cryptomus Callback Format

{
  "type": "payment",
  "uuid": "a1b2c3...",
  "order_id": "order-42",
  "amount": "25.50",
  "payment_amount": "0.00029",
  "status": "paid",
  "is_final": true,
  "currency": "USD",
  "payer_currency": "BTC",
  "sign": "md5-signature-here"
}

The sign field is embedded in the body itself. Compute: MD5(base64(JSON.stringify(body).replace(/\\/g, "/")) + apiKey).

OxaPay Callback Format

{
  "track_id": "uuid-here",
  "status": "Paid",
  "type": "White-Label",
  "amount": 25.50,
  "currency": "usd",
  "order_id": "order-42"
}

Signature is in the HMAC header: HMAC-SHA512 of the raw JSON body, signed with your API key.

Verification Steps

Read the raw request body
Compute the signature using the appropriate algorithm for your adapter
Compare with the provided signature (header or body field)

Retry Behavior

If your endpoint returns a non-2xx status code, callbacks are retried with exponential backoff (up to 10 attempts).

Payment Statuses

Each adapter uses its own status vocabulary. See the per-adapter payment info docs for the full mapping: