Payments

Create a payment

Send the amount in USD and your own reference from your server. Only amountUsd is required.

curl -X POST https://api.sellhidden.com/v1/payments \
  -H "Authorization: Bearer hsk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amountUsd": 49,
    "reference": "order-1042",
    "description": "Pro plan, 1 month",
    "returnUrl": "https://shop.example.com/thanks?order=1042",
    "cancelUrl": "https://shop.example.com/cart",
    "buyerEmail": "buyer@example.com",
    "metadata": {
      "plan": "pro"
    }
  }'

The answer is 201 Created with the payment. Every payment endpoint and every payment.* event carries this same object:

{
  "ok": true,
  "payment": {
    "id": "NOVA-7K2Q-9XHD",
    "url": "https://sellhidden.com/order/NOVA-7K2Q-9XHD",
    "status": "pending",
    "test": false,
    "amountUsd": 49,
    "paidUsd": null,
    "shortUsd": 0,
    "overpaidUsd": 0,
    "creditedUsd": null,
    "feeUsd": 0,
    "networkFeeUsd": 0,
    "reference": "order-1042",
    "description": "Pro plan, 1 month",
    "metadata": {
      "plan": "pro"
    },
    "buyerEmail": "buyer@example.com",
    "returnUrl": "https://shop.example.com/thanks?order=1042",
    "cancelUrl": "https://shop.example.com/cart",
    "coin": null,
    "network": null,
    "underpaid": null,
    "availableAt": null,
    "createdAt": "2026-09-26T09:58:40.000Z",
    "expiresAt": "2026-09-26T10:58:40.000Z",
    "paidAt": null
  }
}

Then send the buyer to payment.url, for example with a 303 redirect. Keep payment.id: it is the id of the payment in every event and in GET /payments/{id}.

Create the payment when the buyer clicks Pay, not when your page loads: open payments count against your limits.

The payment page

The page shows your store name and logo, the description, the amount and the Hidden mark. On the Enterprise plan the Hidden mark is left out.

The buyer picks a coin and a network. The page shows the exact amount and a QR code, waits for the network to confirm, and then sends the buyer to your returnUrl. Until they pay, a link takes them back to your cancelUrl.

The page is in the buyer's language and works on phones.

The buyer has expiresInMinutes to start paying. Once they pick a coin, the address stays valid for the time shown on the page.

Statuses and webhooks

Each event carries the payment as data: the same object as GET /payments/{id}. Verify the signature like every webhook (Verify signatures). Test payments carry "test": true, and order.* events never fire for payments.

POST https://example.com/hidden-webhook
Content-Type: application/json
X-Hidden-Event: payment.paid
X-Hidden-Delivery: dlv_01j9k2…
X-Hidden-Timestamp: 1727344800
X-Hidden-Signature: sha256=3f8a…c21e

{
  "id": "evt_9f2c…",
  "event": "payment.paid",
  "createdAt": "2026-09-26T10:01:12.000Z",
  "data": {
    "id": "NOVA-7K2Q-9XHD",
    "url": "https://sellhidden.com/order/NOVA-7K2Q-9XHD",
    "status": "paid",
    "test": false,
    "amountUsd": 49,
    "paidUsd": 49,
    "shortUsd": 0,
    "overpaidUsd": 0,
    "creditedUsd": 49,
    "feeUsd": 0,
    "networkFeeUsd": 0,
    "reference": "order-1042",
    "description": "Pro plan, 1 month",
    "metadata": {
      "plan": "pro"
    },
    "buyerEmail": "buyer@example.com",
    "returnUrl": "https://shop.example.com/thanks?order=1042",
    "cancelUrl": "https://shop.example.com/cart",
    "coin": "USDT",
    "network": "Tron (TRC20)",
    "underpaid": null,
    "availableAt": "2026-09-28T10:01:12.000Z",
    "createdAt": "2026-09-26T09:58:40.000Z",
    "expiresAt": "2026-09-26T10:58:40.000Z",
    "paidAt": "2026-09-26T10:01:12.000Z"
  }
}

// After checking X-Hidden-Signature (see Verifying signatures on the Webhooks page):
const event = JSON.parse(rawBody);
const payment = event.data;

if (event.event === "payment.paid") {
  if (payment.test) {
    console.log("Test payment marked as paid:", payment.reference); // nothing was paid
  } else {
    await deliverOnce(payment.reference, payment.id); // your order id, Hidden's payment id
  }
}
return new Response("ok");

# After checking X-Hidden-Signature (see Verifying signatures on the Webhooks page):
event = json.loads(raw_body)
payment = event["data"]

if event["event"] == "payment.paid":
    if payment["test"]:
        print("Test payment marked as paid:", payment["reference"])  # nothing was paid
    else:
        deliver_once(payment["reference"], payment["id"])  # your order id, Hidden's payment id

<?php
// After checking X-Hidden-Signature (see Verifying signatures on the Webhooks page):
$event   = json_decode($raw, true);
$payment = $event["data"];

if ($event["event"] === "payment.paid") {
    if ($payment["test"]) {
        error_log("Test payment marked as paid: " . $payment["reference"]); // nothing was paid
    } else {
        deliver_once($payment["reference"], $payment["id"]); // your order id, Hidden's payment id
    }
}
http_response_code(200);

If an event did not arrive, read the payment with GET /payments/{id}.

Amounts, fees and payouts

There is no platform fee. The buyer pays the network fee on top of the amount, unless you chose in Payment methods to pay it yourself. Then it comes out of your credit and shows as networkFeeUsd.

creditedUsd is what was added to your store balance.

Money from an API payment can be withdrawn from availableAt, after a short hold.

New stores start with lower limits on single payments and on the total per 24 hours. Your limits and hold are shown in Developers, Payments. Write to support to raise them.

Short and extra payments

A payment short by no more than your underpayment tolerance (Payment methods) counts as paid. You are credited what arrived, and shortUsd shows the gap.

If more is missing, the payment is underpaid. The buyer can send the rest from the same page for 48 hours. You can accept what arrived at any time with POST /payments/{id}/accept. Otherwise the payment expires and the money waits for you to accept it.

Money above the amount is not added to your balance. overpaidUsd shows it, and payment.overpaid tells you when a transfer arrives after the payment was complete.

Refunds

Crypto payments are final, and Hidden does not send refunds for API payments. To refund a buyer, send them the money yourself.

References and retries

Send an Idempotency-Key header with every create. A retry after a timeout then returns the first answer instead of creating a second payment.

An answer that asks you to wait is not kept for its key: a 429, a 503, and 409 payment_started, payment_in_flight or payment_busy. After the wait, retry with the same key.

reference is your own id, such as an order number. While a payment with that reference is open, creating it again with the same amount returns the same payment (existing: true). With another amount the answer is 409 reference_in_use.

After a payment with that reference is paid, the reference cannot be used again (409 reference_paid).

Test payments

Create a payment with "test": true. Its page shows Test mode and two buttons: Mark as paid and Mark as expired.

Your endpoint receives the matching events with "test": true. No money moves and nothing is credited.

Keys made by the Try it button in these docs always create test payments.

Errors

Errors have the usual shape (Responses and errors), with any extra values next to code. The codes of the payments endpoints:

Key errors such as unauthorized, insufficient_scope and store_suspended are the same as on every endpoint (Authentication).