Welcome to the MaxPaya REST API v1 documentation. MaxPaya allows merchants to programmatically issue multi-chain cryptocurrency invoices, monitor live confirmations, automate payouts, and receive cryptographically signed HMAC webhooks.
The base URL for all API requests is: https://maxpaya.com
1. Authentication
Every administrative and merchant request must include your public API key in the custom HTTP header:
Header: X-API-KEY: mp_live_your_api_key_here
You can generate and rotate your API credentials at any time inside the Merchant Console.
2. Create New Invoice
Generates an invoice order and returns a multi-currency payment checkout URL.
POST /api/invoices/create/
Request Body (JSON):
{ "amount_usd": "25.00", "order_id": "ORD-10042", "allowed_currencies": ["USDT", "TON", "TRX", "BNB"], "callback_url": "https://yourdomain.com/payment/success/", "webhook_url": "https://yourdomain.com/api/webhooks/maxpaya/" }
Response Example:
{ "uuid": "e7899a8d-d9aa-49eb-9c1e-28910ca422d1", "order_id": "ORD-10042", "amount_usd": "25.00", "status": "pending", "payment_url": "https://maxpaya.com/pay/e7899a8d-d9aa-49eb-9c1e-28910ca422d1/", "created_at": "2026-10-19T14:30:00Z" }
3. Select Currency & Lock Deposit Address
When the customer selects their preferred token on your custom checkout, lock the exchange rate and allocate the dedicated deposit address.
POST /api/invoice/{uuid}/select-currency/
{ "currency_id": 1 }
4. Query Invoice Status
Polling endpoint to check on-chain confirmations, received amount, and current transaction state.
GET /api/invoice/{uuid}/status/
Response Example:
{ "uuid": "e7899a8d-d9aa-49eb-9c1e-28910ca422d1", "status": "paid", "expected_amount": "25.000000", "received_amount": "25.000000", "currency": "USDT", "network": "TRON", "tx_hash": "b4a8e9f...", "confirmed": true }
5. Settle Partial Deposits Programmatically
If an invoice enters partial_expired due to an underpaid deposit, merchants can settle the received funds instantly via API.
POST /api/invoices/{uuid}/accept-partial/
6. Request Settlement Withdrawal
Dispatches funds from your available ledger balance to an external cold or warm wallet.
POST /dashboard/payouts/api/submit/
{ "currency_symbol": "TON", "network_symbol": "TON", "amount": "10.00", "destination_address": "UQDC9w8...r4", "destination_memo": "104928" }
7. Webhook HMAC-SHA256 Signature Verification
When an invoice is paid or swept, MaxPaya sends an HTTP POST request containing the event payload to your configured webhook_url with header X-Signature-SHA256.
Python Implementation:
import hmac import hashlib def verify_maxpaya_webhook(raw_payload_bytes: bytes, incoming_signature: str, api_secret: str) -> bool: """Verify incoming X-Signature-SHA256 header.""" expected = hmac.new( api_secret.encode('utf-8'), raw_payload_bytes, hashlib.sha256 ).hexdigest() return hmac.compare_digest(expected, incoming_signature)
Node.js Implementation:
const crypto = require('crypto'); function verifyMaxpayaWebhook(rawPayloadBuffer, incomingSignature, apiSecret) { const expected = crypto .createHmac('sha256', apiSecret) .update(rawPayloadBuffer) .digest('hex'); return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(incomingSignature)); }