API reference
Payments
Take crypto payments for any amount on your own site. Create a payment, send the buyer to its url (a payment page Hidden hosts) and deliver when payment.paid arrives. The API never returns a deposit address, a coin amount or a QR code. Turn payments on in Developers, Payments first; test payments work before that.
Endpoints
POST/paymentspayments:writeIdempotency-Key201
Create a payment. Call it from your server when the buyer clicks Pay. The answer carries url: send the buyer there to pay. Calls from a web page are refused (403 server_only), except with a temporary key from Try it, which always creates test payments. A reference that matches an open payment with the same amount returns that payment instead (200, existing: true).
| Body | Type | Description |
|---|---|---|
| amountUsdrequired | Type: number | At least 1.00 and at most your per-payment limit (never more than 10,000). Rounded to cents. |
| reference | Type: string | Your own id, such as an order number: 1 to 64 letters, digits and _ . : @ + / = -. While a payment with it is open, the same amount returns that payment. |
| description | Type: string | Up to 120 characters of plain text, shown to the buyer. |
| returnUrl | Type: string | Where the page sends the buyer after paying: https, up to 2,048 characters, on one of your payment websites. Test payments may also return to localhost. |
| cancelUrl | Type: string | Linked on the page until the buyer pays. The same rules as returnUrl. |
| buyerEmail | Type: string | The buyer's email, up to 254 characters. Hidden emails them a receipt once the payment is paid. |
| expiresInMinutes | Type: 15..1440 | The time the buyer has to start paying. Default 60. |
| metadata | Type: object | Up to 20 keys of letters, digits, _ . or - (40 characters each), with string, number or true/false values of up to 200 characters, and 2 KB of JSON in all. Returned to you, never shown to the buyer. |
| test | Type: boolean | Set to true for a test payment: no money moves, and its page offers Mark as paid and Mark as expired. |
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",
"metadata": {
"plan": "pro"
}
}'{
"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": null,
"returnUrl": null,
"cancelUrl": null,
"coin": null,
"network": null,
"underpaid": null,
"availableAt": null,
"createdAt": "2026-09-26T09:58:40.000Z",
"expiresAt": "2026-09-26T10:58:40.000Z",
"paidAt": null
}
}GET/paymentspayments:read
List payments. Newest first.
| Query parameters | Type | Description |
|---|---|---|
| status | Type: pending | underpaid | paid | expired | cancelled | Only this status. pending includes confirming; expired also matches a pending or underpaid payment past its expiresAt. |
| reference | Type: string | Only payments with this reference. |
| test | Type: true | false | Only test payments, or only live ones. |
| since | Type: ISO date | Created at or after. |
| until | Type: ISO date | Created before. |
| limit | Type: 1..100 | Page size. Default 25. |
| cursor | Type: string | nextCursor from the previous page. |
curl https://api.sellhidden.com/v1/payments \
-H "Authorization: Bearer hsk_live_…"{ "ok": true, "payments": [ { "id": "NOVA-7K2Q-9XHD", "url": "https://sellhidden.com/order/NOVA-7K2Q-9XHD", "status": "paid", "test": false, "amountUsd": 49, "paidUsd": 49, "creditedUsd": 49, "reference": "order-1042", … } ], "nextCursor": null, "hasMore": false }GET/payments/{id}payments:read
Get a payment. {id} is the payment's id (any case, hyphen optional). If a webhook did not arrive, read the payment here.
curl https://api.sellhidden.com/v1/payments/ID \
-H "Authorization: Bearer hsk_live_…"{ "ok": true, "payment": { "id": "NOVA-7K2Q-9XHD", "status": "paid", "amountUsd": 49, "paidUsd": 49, "creditedUsd": 49, "coin": "USDT", "network": "Tron (TRC20)", "availableAt": "2026-09-28T10:01:12.000Z", "paidAt": "2026-09-26T10:01:12.000Z", … } }POST/payments/{id}/cancelpayments:writeIdempotency-Key
Cancel a payment. Cancels a pending payment and sends payment.cancelled. Once the buyer has started paying, it cannot be cancelled while their transfer can still arrive, or after money arrived: 409 payment_started, with retryAfter (an ISO time). Accept what arrived instead. Any other state answers 409 not_cancellable.
| Body | Type | Description |
|---|---|---|
| reason | Type: string | Private, up to 500 characters. |
curl -X POST \
https://api.sellhidden.com/v1/payments/ID/cancel \
-H "Authorization: Bearer hsk_live_…" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{}'{ "ok": true, "payment": { "id": "NOVA-7K2Q-9XHD", "status": "cancelled", … } }POST/payments/{id}/acceptpayments:writeIdempotency-Key
Accept what arrived. Settles an underpaid or expired payment on the money that arrived: you are credited it, minus any network fee you pay, and payment.paid is sent. Refused with 409 nothing_received, payment_in_flight (a transfer is still confirming; until says until when), payment_busy (another action on it is running: retry shortly) or not_underpaid.
curl -X POST \
https://api.sellhidden.com/v1/payments/ID/accept \
-H "Authorization: Bearer hsk_live_…" \
-H "Idempotency-Key: $(uuidgen)"{ "ok": true, "creditedUsd": 30, "payment": { "id": "NOVA-7K2Q-9XHD", "status": "paid", "amountUsd": 49, "paidUsd": 30, "shortUsd": 19, "creditedUsd": 30, … } }Get help
Send us the endpoint, the request or delivery id and the response you got. Security findings go through responsible disclosure. Live platform status is on the support page.
See also