PayXif API v1

Base URL https://api.payxif.com. Every response is JSON:

{ "ok": true,  "data": { ... } }
{ "ok": false, "error": { "code": "unsupported_currency", "message": "..." } }

Authentication

Send the merchant API key in any of these headers. Keys start with pxk_live_ (mainnet) or pxk_test_ (testnet); create them in Merchant service.

X-API-Key: pxk_live_xxxxxxxx
Authorization: Bearer pxk_live_xxxxxxxx
merchant_api_key: pxk_live_xxxxxxxx   # OxaPay-compatible

Create invoice

POST /v1/invoices — price in USD (customer picks the coin on checkout) or in a specific coin.

amount_usd	string	USD amount, e.g. "49.99" — customer chooses the coin. Either this or amount+currency.
amount	string	coin amount, e.g. "25.50"
currency	string	USDT, TRX, … (with amount)
network	string	TRON (default), BSC, …
order_id	string	your reference, echoed in webhooks
description	string	shown on the payment page
email	string	customer email
callback_url	url	webhook for this invoice (falls back to merchant default)
return_url	url	where the customer is sent after payment
lifetime	int	minutes, 5–1440, default 60 — the USD→coin rate is locked until expiry
underpaid_cover	number	% shortfall still accepted as paid (0–60)
fee_paid_by_payer	bool	add the service fee on top of the customer total
mixed_payment	bool	allow several transactions / coins until the USD total is reached
metadata	object	up to 20 keys, echoed back in webhooks

curl -X POST https://api.payxif.com/v1/invoices \
  -H "X-API-Key: pxk_live_..." -H "Content-Type: application/json" \
  -d '{"amount_usd": "49.99", "order_id": "A-1042", "callback_url": "https://shop.example/hook"}'

# 201 → data.track_id, data.pay_link  (redirect the customer there)

Get & list invoices

GET /v1/invoices/{track_id}     # includes txs[] with confirmations
GET /v1/invoices?status=paid&order_id=A-1042&page=1&per_page=25
GET /v1/balance                 # your wallet balances
GET /v1/me                      # merchant profile, fee %, network mode
GET /v1/currencies              # public: enabled coins & networks

USD pricing & payer coin choice

Invoices created with amount_usd open a checkout where the customer picks any accepted coin. The USD→coin rate locks the moment they choose, until the invoice expires. With mixed_payment the invoice settles by accumulated USD value, allowing several transfers — even in different coins after re-selection.

Payment links & donations

No code needed: create links from the dashboard. A link https://payxif.com/pay/l/12345678 takes fixed-amount payments (links) or lets the payer choose the amount (donations). Both support branding (logo, colour, theme), customer fields (name / email / note), accepted-coin lists and a thanks message — and report payments in Stats and the per-link payment list.

Invoice statuses

new		USD invoice waiting for the customer to pick a coin
waiting		nothing received yet
confirming		transfer seen on chain, waiting for confirmations (~1 min on Tron)
paid		confirmed amount ≥ requested — wallet credited
underpaid		below requested; the address stays open for top-up until expiry
expired		deadline passed — late payments still credit your wallet (invoice.paid_late)

Webhooks

POST JSON to your callback_url with an HMAC-SHA512 signature of the raw body. Events: invoice.confirming · invoice.paid · invoice.underpaid · invoice.expired · invoice.paid_late. Respond 2xx within 10s; retries back off over 8 attempts. Deliveries are idempotent — the same event can arrive twice.

X-PayXif-Event: invoice.paid
X-PayXif-Delivery: 1234
X-PayXif-Signature: <hex hmac_sha512(raw_body, webhook_secret)>

// verify (PHP)
$body = file_get_contents('php://input');
$sig  = $_SERVER['HTTP_X_PAYXIF_SIGNATURE'] ?? '';
if (!hash_equals(hash_hmac('sha512', $body, $SECRET), $sig)) { http_response_code(401); exit; }

Payout API

Programmatic withdrawals with a payout-scoped key (pxp_…, created in Payout API with password + 2FA, optional IP allowlist). Key possession is the auth — no OTP per call.

POST /v1/payout        # {"address":"T...","amount":"25","currency":"USDT","network":"TRON"}
GET  /v1/payouts       # list payouts made through the API
GET  /v1/payout/{id}   # single payout with txid + explorer url

Errors & limits

401 unauthorized		missing/invalid key, wrong OTP or withdrawal password
403 ip_not_allowed		caller IP not on the key's allowlist
429 rate_limited		over 120 req/min per key — back off
400 amount_too_small		below the coin's minimum
400 withdrawal_uneconomic		fee would not cover network cost — raised automatically
503 maintenance		short maintenance window, retry with backoff