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. | | 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 .

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 .

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 →