API Documentation — PaymentHub

Authentication

All API requests require an API key sent via the X-API-Key header.

Request Header

X-API-Key: your-merchant-api-key

You can find your API key in your merchant dashboard. Keep it secret — never expose it in client-side code.

Endpoints

POST /api/v1/invoices

Create a new payment invoice. Returns a unique payment address and checkout URL.

Parameters

Field	Type	Description
coin required	string	Cryptocurrency: `BTC`, `USDT`, or `ALL` (customer selects at checkout)
amount required	number	Fiat amount to charge (min: 0.01)
fiat_currency optional	string	3-letter currency code (default: USD)
order_id optional	string	Your internal order ID for reference
callback_url optional	string	URL to redirect after payment
metadata optional	object	Custom key-value data stored with the invoice

Example Request

curl -X POST https://www.paymenthub.net/api/v1/invoices \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "coin": "BTC",
    "amount": 50.00,
    "order_id": "ORD-12345"
  }'
                    

Example Response (BTC/USDT)

{
  "success": true,
  "data": {
    "uuid": "a1b2c3d4-...",
    "coin": "BTC",
    "selected_coin": null,
    "amount_fiat": 50.00,
    "amount_crypto": 0.00078500,
    "exchange_rate": 63694.27,
    "pay_address": "bc1q...",
    "payment_url": "https://www.paymenthub.net/pay/a1b2c3d4-...",
    "status": "pending",
    "expires_at": null
  }
}
                    

Example Response (ALL — multi-coin)

// When coin=ALL, crypto fields are null until customer selects a coin at checkout
{
  "success": true,
  "data": {
    "uuid": "e5f6g7h8-...",
    "coin": "ALL",
    "selected_coin": null,
    "amount_fiat": 50.00,
    "amount_crypto": null,
    "exchange_rate": null,
    "pay_address": null,
    "payment_url": "https://www.paymenthub.net/pay/e5f6g7h8-...",
    "status": "pending",
    "expires_at": null
  }
}
                    

GET /api/v1/invoices/{uuid}

Retrieve an invoice by its UUID. Use this to check payment status.

Example Response

{
  "success": true,
  "data": {
    "uuid": "a1b2c3d4-...",
    "status": "paid",
    "paid_amount": 0.00078500,
    "paid_txid": "abc123...",
    ...
  }
}
                    

GET /api/v1/invoices

List all your invoices with pagination. Supports filtering by status and coin.

Query Param	Type	Description
status optional	string	Filter: pending, confirming, paid, expired, underpaid
coin optional	string	Filter by coin: BTC, USDT, or ALL
per_page optional	number	Items per page (default: 20)

GET /api/v1/merchant/profile

Get your merchant profile with stats (total invoices, volume).

GET /api/v1/rates

Get current BTC and USDT exchange rates (cached, refreshes every 60 seconds).

Invoice Statuses

pending — Waiting for payment
confirming — Payment detected, awaiting confirmations
paid — Payment confirmed
expired — Invoice expired without payment
underpaid — Partial payment received

Webhooks

When an invoice status changes, we send a POST request to your configured webhook URL.

Verification

Each webhook includes an X-Signature header containing an HMAC-SHA256 hash of the request body, signed with your webhook secret.

// Verify in PHP:
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_SIGNATURE'];
$expected = hash_hmac('sha256', $payload, $webhookSecret);

if (hash_equals($expected, $signature)) {
    // Valid webhook
}
                

Events

invoice.created
invoice.coin_selected — Customer selected a coin (multi-coin invoices)
invoice.confirming
invoice.paid
invoice.expired
invoice.underpaid

Payload Format

{
  "event": "invoice.paid",
  "invoice": {
    "uuid": "a1b2c3d4-...",
    "order_id": "ORD-12345",
    "status": "paid",
    "coin": "BTC",
    "selected_coin": null,
    "amount_crypto": 0.00078500,
    "paid_amount": 0.00078500,
    "paid_txid": "abc123...",
    ...
  },
  "timestamp": "2026-03-11T12:05:00+00:00"
}
                

Multi-Coin Invoices

Set coin to ALL to let the customer choose between BTC and USDT on the checkout page.

How it works

Create invoice with coin: "ALL" — fields amount_crypto, exchange_rate, and pay_address will be null
Customer visits checkout and selects BTC or USDT
A payment address is generated, crypto amount calculated at the current exchange rate, and selected_coin is set
An invoice.coin_selected webhook event is fired

No Expiry

Invoices do not expire. The crypto amount recalculates automatically based on the current exchange rate each time the checkout page is loaded, ensuring the customer always pays the correct fiat equivalent.

Error Handling

All errors return a JSON object with success: false and an error message.

{
  "success": false,
  "error": "Invalid or inactive API key."
}
            

Code	Description
401	Invalid or missing API key
404	Invoice not found
422	Validation error (invalid coin, amount, etc.)
503	Exchange rate service unavailable

PaymentHub API