CoinPayments adapter

payzum exposes a form-encoded endpoint at POST /legacy/api.php. It accepts a command-based protocol with HMAC-SHA-512 request signing — a wire format used by common shopping-cart payment plugins. In most cases, swapping the base URL is enough to migrate an existing integration without any code changes.

/legacy/api.php is the only legacy route — any other /legacy/* path returns 404.

Signing requests

Every request body is signed exactly as transmitted: the HMAC header is the lowercase hex output of HMAC-SHA-512(private_key, raw_body_bytes). Do not re-encode the form before signing — the bytes you send must match the bytes you signed.

cmd=create_transaction

Creates an invoice. Equivalent to POST /v1/payment in the REST API.

BODY="version=1&cmd=create_transaction&key=<PUBLIC_KEY>&nonce=$(date +%s%3N)&amount=10.00&currency1=USD&currency2=USDT.TRC20&invoice=ORDER-1234&ipn_url=https%3A%2F%2Fmerchant.example.com%2Fipn"
HMAC=$(printf '%s' "$BODY" | openssl dgst -sha512 -hmac "<PRIVATE_KEY>" | sed 's/^.*= //')
curl -X POST "https://<HOST>/legacy/api.php" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "HMAC: $HMAC" \
  -d "$BODY"

Each network has a minimum payment amount. If amount (converted to the currency2 network) falls below that floor, the request is rejected with the error envelope { "error": "amount below minimum", "result": null } (see Error responses below). Read the per-currency minimum from cmd=rates (below) before creating the transaction, or see Minimum amounts for the published floors.

cmd=get_tx_info

Reads a single invoice by its payzum id (txid).

BODY="version=1&cmd=get_tx_info&key=<PUBLIC_KEY>&nonce=$(date +%s%3N)&txid=pzi_..."
HMAC=$(printf '%s' "$BODY" | openssl dgst -sha512 -hmac "<PRIVATE_KEY>" | sed 's/^.*= //')
curl -X POST "https://<HOST>/legacy/api.php" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "HMAC: $HMAC" \
  -d "$BODY"

cmd=get_tx_info_multi

Reads up to 25 invoices in one call. Pass the payzum ids as a |-separated list in txid.

BODY="version=1&cmd=get_tx_info_multi&key=<PUBLIC_KEY>&nonce=$(date +%s%3N)&txid=pzi_aaa%7Cpzi_bbb"
HMAC=$(printf '%s' "$BODY" | openssl dgst -sha512 -hmac "<PRIVATE_KEY>" | sed 's/^.*= //')
curl -X POST "https://<HOST>/legacy/api.php" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "HMAC: $HMAC" \
  -d "$BODY"

cmd=rates

Returns the current rate table for supported currencies. No per-transaction parameters.

BODY="version=1&cmd=rates&key=<PUBLIC_KEY>&nonce=$(date +%s%3N)"
HMAC=$(printf '%s' "$BODY" | openssl dgst -sha512 -hmac "<PRIVATE_KEY>" | sed 's/^.*= //')
curl -X POST "https://<HOST>/legacy/api.php" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "HMAC: $HMAC" \
  -d "$BODY"

Each currency entry also includes its minimum payment amount:

• min_amount_usd — the network minimum in USD.
• min_amount — the same minimum expressed in that currency.

Use these to validate the buyer's amount before calling cmd=create_transaction, so a below-minimum charge is caught up front rather than rejected. See Minimum amounts for the full per-network table.

Error responses

Every response uses the stable CP envelope:

{ "error": "ok", "result": { ... } }   // success
{ "error": "<message>", "result": null } // error

Always check the body's error field — application-level errors can arrive with HTTP 200, following the CP contract where the error field is the authoritative signal. Protocol-level errors carry an HTTP error status as well: 401 for HMAC or key failures, 400 for a bad nonce, missing fields, or wrong content-type, and 429 for rate limiting.

Rate limits

The adapter shares the same per-merchant rate limit as /v1/*: 60 requests per minute. Exceeding it returns { "error": "rate limit exceeded", "result": null } with HTTP 429.

IPN delivery

Merchants using this adapter receive IPNs in the CoinPayments dialect: a form-urlencoded body (keys sorted, RFC-3986 percent-encoding) signed with HMAC-SHA-512 in the fixed HMAC header. The signing key is your merchant webhook secret — not your CoinPayments-style private key. The private key signs your requests to payzum; outbound IPNs are signed with the webhook secret. Deduplicate on the ipn_id field, which is stable across retries. See Overview & verification for the full field list and status mapping.

Limitations

• The adapter implements the common command surface: create_transaction, get_tx_info, get_tx_info_multi, and rates — 4 commands. Advanced commands such as mass withdrawals and currency conversion are not yet supported.