payzum docs
payzum.comAPI referenceSign in

API reference

Full reference for the Payzum payment API endpoints.

The payzum public API is a REST payment surface. Base URL: https://merchant.payzum.com/v1/ (production); staging/sandbox is https://staging.payzum.com/v1/. All authenticated requests require the x-api-key header. For an interactive explorer, see /api/docs.

Authentication

Pass your merchant API key in the x-api-key request header. Keys are issued per merchant from the dashboard under Settings → API Keys. The plaintext key is shown once at creation time; payzum stores only a SHA-256 hash for verification.

Endpoint summary

| Method | Path | Auth | Description | |--------|------|------|-------------| | GET | /v1/status | none | Liveness probe. | | GET | /v1/currencies | none | List supported (chain, symbol) tuples. | | GET | /v1/estimate | none | Quote price → pay amount (includes minimum-amount fields). | | GET | /v1/min-amount | none | Per-currency minimum payment amount. | | POST | /v1/payment | x-api-key | Create an invoice. | | GET | /v1/payment/:id | x-api-key | Read invoice by id or order_id. | | GET | /v1/payment | x-api-key | Paginated list of invoices. |

GET /v1/status

Unauthenticated liveness probe. Returns { "message": "OK" } on success.

curl -s "$PAYZUM_BASE/v1/status"

GET /v1/currencies

Returns a list of all supported currency (chain, symbol) tuples. No authentication required.

curl -s "$PAYZUM_BASE/v1/currencies" | jq '.currencies | length'

GET /v1/estimate

Quote a fiat amount in a target crypto currency. No authentication required.

Query parameters:

  • amount — fiat amount to convert (e.g. 10)
  • currency_from — source fiat currency (e.g. usd)
  • currency_to — target crypto currency (e.g. usdttrc20)
curl -s "$PAYZUM_BASE/v1/estimate?amount=10&currency_from=usd&currency_to=usdttrc20" | jq .

GET /v1/min-amount

Returns the minimum payment amount for a given currency pair. No authentication required.

Query parameters:

  • currency_from — source fiat currency (e.g. usd)
  • currency_to — target crypto currency (e.g. usdttrc20)

Response fields:

  • currency_from — the source fiat currency
  • currency_to — the target crypto currency
  • min_amount — minimum amount expressed in the target crypto currency
  • min_amount_usd — minimum amount in USD
curl -s "$PAYZUM_BASE/v1/min-amount?currency_from=usd&currency_to=usdttrc20" | jq .

If the invoice price_amount would result in a value below min_amount_usd for the chosen network, the invoice creation returns 400 AMOUNT_BELOW_MINIMUM. Check the live minimum before building the invoice to surface a helpful error to the buyer. See Minimum amounts for per-network floors.

Minimum-amount fields

In addition to the quoted pay amount, GET /v1/estimate now returns:

| Field | Description | |-------|-------------| | min_amount_usd | Network minimum in USD for the chosen currency. | | below_minimum | true if the quoted amount is below the network minimum. |

Use below_minimum to warn the buyer before they attempt to create an invoice that would be rejected.

POST /v1/payment

Create an invoice. Returns 201 with the full payment object, including the deposit address and expiration timestamp.

Body parameters:

  • price_amount (required) — invoice amount in the price currency
  • price_currency (required) — fiat currency for the invoice (e.g. usd)
  • pay_currency (required) — crypto currency to accept (e.g. usdttrc20)
  • order_id (optional) — your internal order identifier (must be unique per merchant)
  • ipn_callback_url (optional) — URL payzum will POST signed IPN events to
curl -X POST "$PAYZUM_BASE/v1/payment" \
  -H "x-api-key: $PAYZUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "price_amount": 49.99,
    "price_currency": "usd",
    "pay_currency": "usdttrc20",
    "order_id": "ORDER-12345",
    "ipn_callback_url": "https://merchant.example.com/payzum/ipn"
  }' | jq .

Response (201 Created)

A successful create returns the full payment object. The identifier is payment_id — persist this value to track the invoice. (There is no id field; the :id path parameter on GET /v1/payment/:id accepts either this payment_id or your merchant order_id.)

{
  "payment_id": "pzi_viawy8vaio26d82n023epiq4",
  "payment_status": "waiting",
  "pay_address": "0x1a2b3c4d5e6f7890a1b2c3d4e5f60718293a4b5c",
  "pay_amount": 49.99,
  "pay_currency": "usdcmatic",
  "network": "polygon",
  "network_precision": 6,
  "smart_contract": "0x3c499c542cef5e3811e1192ce70d8cc03d5c3359",
  "price_amount": 49.99,
  "price_currency": "usd",
  "actually_paid": 0,
  "amount_received": 0,
  "order_id": "ORDER-12345",
  "order_description": null,
  "ipn_callback_url": "https://merchant.example.com/payzum/ipn",
  "purchase_id": "pzi_viawy8vaio26d82n023epiq4",
  "invoice_url": "https://merchant.payzum.com/pay/pzi_viawy8vaio26d82n023epiq4",
  "invoice_type": "payment",
  "time_limit": "01:00:00",
  "expiration_estimate_date": "2026-07-13T12:34:56.000Z",
  "created_at": "2026-07-13T11:34:56.000Z",
  "updated_at": "2026-07-13T11:34:56.000Z",
  "burning_percent": null,
  "payin_extra_id": null,
  "subscriber_email": null,
  "subscription_cycle": null,
  "next_renewal_at": null
}

Response fields:

| Field | Type | Description | |-------|------|-------------| | payment_id | string | Payzum invoice identifier. This is the id — store it to track the invoice. | | payment_status | string | Lifecycle status: waiting, partially_paid, finished, expired, failed (see Invoice lifecycle). New invoices start at waiting. | | pay_address | string | Deposit address the buyer must send funds to. | | pay_amount | number | Amount to pay, denominated in pay_currency. | | pay_currency | string | Currency code the buyer pays in (e.g. usdcmatic). | | network | string | Underlying chain (e.g. polygon, tron, ethereum). | | network_precision | number | Token decimals for pay_currency (e.g. 6 for USDC). | | smart_contract | string | null | Token contract address; null for native coins. | | price_amount | number | Original invoice amount in price_currency. | | price_currency | string | Invoice pricing currency (e.g. usd). | | actually_paid | number | Amount received so far, in pay_currency (0 until a deposit lands). | | amount_received | number | Alias of actually_paid. | | order_id | string | null | Your order identifier, echoed back. | | order_description | string | null | Your order description, echoed back. | | ipn_callback_url | string | null | Where signed IPN events are POSTed. | | purchase_id | string | Equal to payment_id (NowPayments compatibility). | | invoice_url | string | null | Hosted-checkout page for the buyer. | | invoice_type | string | One of payment, donation, subscription, pos. | | time_limit | string | Payment window as HH:MM:SS. | | expiration_estimate_date | string | ISO 8601 timestamp when the invoice expires. | | created_at | string | ISO 8601 creation timestamp. | | updated_at | string | ISO 8601 last-update timestamp. | | burning_percent | null | Reserved; always null. | | payin_extra_id | null | Reserved; always null (memo/tag chains not yet exposed here). | | subscriber_email | string | null | Set only when invoice_type is subscription. | | subscription_cycle | number | null | Set only when invoice_type is subscription. | | next_renewal_at | string | null | Set only when invoice_type is subscription. |

GET /v1/payment/:id

Read a single invoice. The :id path parameter accepts either the payzum payment id or the merchant's order_id.

curl -s -H "x-api-key: $PAYZUM_API_KEY" \
  "$PAYZUM_BASE/v1/payment/inv_abc123" | jq .

GET /v1/payment

Paginated list of invoices for the authenticated merchant.

Query parameters:

  • limit — number of results per page (default 20)
  • offset — pagination offset
  • status — filter by invoice status (e.g. finished, waiting, expired)
  • order_id — filter by your order identifier
curl -s -H "x-api-key: $PAYZUM_API_KEY" \
  "$PAYZUM_BASE/v1/payment?limit=20&status=finished" | jq '.data[].payment_id'

Error responses

All errors return a JSON body of the form { "code": "ERROR_CODE", "message": "..." }.

Common error codes:

| Code | HTTP | Meaning | |------|------|---------| | API_KEY_MISSING | 401 | No x-api-key header present. | | MERCHANT_SUSPENDED | 403 | The merchant account is suspended. | | INVOICE_NOT_FOUND | 404 | No invoice matches the given id or order_id. | | VALIDATION_FAILED | 422 | A required parameter is missing or invalid. |

← Supported chains & currenciesHosted checkout →