payzum (Node.js / TypeScript)

Official SDK for Payzum — accept stablecoin and crypto payments, and verify IPN webhooks.

npm install payzum

Zero runtime dependencies. Ships ESM with full TypeScript declarations. Requires Node.js 18.17+ (require() of this package needs Node 20.19+ or 22+; import works everywhere).

Quickstart: from zero to a paid invoice

import { Payzum } from 'payzum'

const payzum = new Payzum(process.env.PAYZUM_API_KEY!)
// or, against the sandbox: Payzum.sandbox(apiKey)

const invoice = await payzum.payments.create({
  priceAmount: '49.99',          // a string — nothing gets rounded on the way in
  priceCurrency: 'usd',
  payCurrency: 'all',            // let the buyer choose the asset
  orderId: 'ORDER-12345',
  ipnCallbackUrl: 'https://example.com/webhooks/payzum',
})

// Send the buyer to the hosted checkout:
redirect(String(invoice.invoice_url))

Look an invoice up later by its payment_id or by your own order_id — no mapping table needed:

const same = await payzum.payments.get('ORDER-12345')

Webhooks: the part worth reading twice

Payzum sends three kinds of signed webhook and none of them is interchangeable:

| Webhook | Algorithm | Header | Verifier | |---|---|---|---| | Payment IPN (default) | HMAC-SHA-512 | x-nowpayments-sig | verifyPaymentIpn | | Payment IPN, CoinPayments-mode merchants | HMAC-SHA-512 over a form-encoded body | HMAC | verifyCoinPaymentsIpn | | Mass payout | HMAC-SHA-256 | X-Payzum-Signature | verifyMassPayout |

The payment IPN header is named after Payzum's NowPayments-compatible dialect, which lets an existing NowPayments integration point at Payzum without code changes. Using X-Payzum-Signature for a payment IPN is the single most common bug with this API — the signature never verifies, deliveries get a 401, and orders are silently never fulfilled. This SDK owns the header names precisely so that mistake cannot be configured back in.

Verify against the raw request bytes, before any body parsing:

import { SignatureError, paymentStatusFromMerchant, isPaidStatus } from 'payzum'

// Express example — note express.raw(), NOT express.json():
app.post('/webhooks/payzum', express.raw({ type: '*/*' }), (req, res) => {
  const verifier = payzum.webhooks(process.env.PAYZUM_WEBHOOK_SECRET!)

  let payload
  try {
    payload = verifier.verifyPaymentIpn(req.body, req.headers)
  } catch (e) {
    if (e instanceof SignatureError) return res.status(401).end()
    throw e
  }

  // Deduplicate: delivery retries reuse the same event id.
  const eventId = verifier.eventId(req.headers)
  if (eventId && alreadyProcessed(eventId)) return res.status(200).end()

  const status = paymentStatusFromMerchant(String(payload.payment_status))
  if (isPaidStatus(status)) fulfilOrder(String(payload.order_id))

  res.status(200).end()
})

The verifier also enforces a 10-minute replay window on the schemes that carry a signed timestamp. The CoinPayments scheme has no timestamp, so its only defence is deduplicating on the ipn_id body field — the SDK documents this instead of pretending otherwise.

Five IPN event types exist, not two — including two that matter for security: invoice.paid, invoice.expired, late_deposit_received, wrong_token_received, suspicious_token_received.

Money never touches a float

The merchant surface returns amounts as JSON numbers (frozen for NowPayments compatibility), and JSON.parse silently rounds anything past 17 significant digits — by the time a reviver runs, the digits are gone. This SDK parses losslessly, so every number in every response arrives as an exact decimal string, and outbound amounts are written into the JSON text without ever becoming a float.

Honest caveat: the gateway itself emits those fields with double precision, so the SDK's guarantee is that it adds no further loss. When you need exact amounts, read the buyer surface — payzum.invoices.status(paymentId) — whose amounts are decimal strings end to end.

Retries you do not have to think about

• Only RATE_LIMIT_EXCEEDED, INTERNAL_ERROR and RATE_PROVIDER_DOWN are retried; Retry-After is honoured. QUOTA_EXCEEDED is a 429 that is not retried — it means too many open invoices, and retrying makes it worse.
• payments.create is never retried automatically without an idempotencyKey — a blind retry can create a second real invoice. With a key, the first retry waits out the API's ~60 s idempotency consistency window.
• All 16 API error codes are typed (ApiError.errorCode); branch on the code, never on the message.

Surface

payzum.payments.create(params)   POST /v1/payment
payzum.payments.get(id)          GET  /v1/payment/{idOrOrderId}
payzum.payments.list(params)     GET  /v1/payment          (page is zero-based)
payzum.invoices.status(id)       GET  /v1/invoices/{id}/status   (public, exact decimals)
payzum.currencies.list()         GET  /v1/currencies       (cached; detailed catalogue)
payzum.rates.estimate(params)    GET  /v1/estimate
payzum.rates.minAmount(params)   GET  /v1/min-amount       (call before create)
payzum.health()                  GET  /v1/status           (public diagnostics)
payzum.webhooks(secret)          the three verifiers above

Mass payouts (UTXO and EVM) are planned for v1.1.

Links

• Documentation: https://merchant.payzum.com/docs
• Machine-readable reference for AI agents: https://merchant.payzum.com/llms.txt
• Sandbox: https://staging.payzum.com

Note that api.payzum.com does not serve the API. Use merchant.payzum.com.

License

MIT — see LICENSE.