Gateway API

Accept USDT with a hosted checkout

One POST creates a payment session; you send the customer to checkout_url. When they pay, we notify your server at notify_url with a signed payload.

After sign up: Dashboard → Merchants → Integration for merchant id, API key, and webhook secret.

1 · Create session

POST /api/v1/merchant/checkout-session with your API key

2 · Redirect

Customer opens checkout_url and pays

3 · Confirm

Verify the webhook signature, or poll GET /payments/{id}

Credentials

Every API merchant has three values in the dashboard under Merchants → your API merchant → Integration. Two are used when you call us; the third is used when we call you (webhook verification).

Merchant ID

Numeric id of your merchant. Send it as the merchant header (or equivalent) on every API request so we know which account to bill.

Used on → outgoing API requests

Payment API key

Secret key for authenticating requests to our API. Send as Authorization: Bearer …. Never expose this in a browser or mobile app—only on your server.

Used on → outgoing API requests

Webhook secret

Not sent as a header on your checkout or REST calls. Store it only on your server. When we POST to your notify_url, we sign the body—your backend recomputes the signature with this secret to prove the request is from us.

Used on → verifying incoming webhooks

Is the webhook secret required? For production you should always verify signatures. Without the secret you cannot cryptographically validate callbacks—anyone who guesses your URL could fake posts. Regenerating the secret is available on the same Integration page if it leaks.

Authentication

Authenticate only with Merchant ID + Payment API key. The webhook secret is not part of this—see Webhooks.

If you send a merchant id (header, query, or JSON), it must match the merchant that owns the key.

Recommended headers

merchant: YOUR_MERCHANT_ID
Authorization: Bearer YOUR_PAYMENT_API_KEY
Content-Type: application/json
Accept: application/json

Alternative headers

X-Merchant-Id: YOUR_MERCHANT_ID
X-Merchant-Key: YOUR_PAYMENT_API_KEY

On GET requests you may use ?merchant=YOUR_MERCHANT_ID instead of the merchant header. On POST checkout, JSON fields merchant or merchant_id must match when provided.

Create checkout session

amount (required) is in USD; settlement is USDT 1:1. note is your order reference. notify_url receives the signed webhook when paid.

POST https://gatenoc.com/api/v1/merchant/checkout-session
merchant: YOUR_MERCHANT_ID
Authorization: Bearer YOUR_PAYMENT_API_KEY
Content-Type: application/json

{
  "amount": 10.50,
  "note": "order_123",
  "notify_url": "https://yoursite.com/webhooks/paid",
  "success_url": "https://yoursite.com/thanks"
}

Optional Idempotency-Key header — same key within 24h returns the same response.
username is accepted as an alias for note.
Response includes checkout_url, invoice_url (same value), and expires_at — the ?cs= token is valid until then (often ~30 minutes).

Webhooks

We send an HTTP POST with Content-Type: application/json to the notify_url you passed at checkout. Verify the request using your webhook secret from the Integration page (not the payment API key).

Request headers we send

X-Gateway-Timestamp: Unix seconds (string)
X-Gateway-Signature: t=<timestamp>,v1=<hex>
X-Gateway-Merchant-Key: Your payment API key (informational; verify with signature)

Compute v1 as HMAC-SHA256, hex-encoded, of the string timestamp + "." + raw_request_body using your webhook secret as the key. Compare to the v1 value in X-Gateway-Signature (constant-time compare). The timestamp in the signature must match X-Gateway-Timestamp.

Example JSON body

{
  "event": "payment.completed",
  "status": "completed",
  "merchant_id": 1,
  "amount": "10.50",
  "total_amount": "10.50",
  "currency": "USD",
  "bybit_pay_id": "…",
  "merchant_trade_no": "…",
  "note": "order_123",
  "payment_record_id": 42,
  "paid_at": "2026-03-24T12:00:00+00:00"
}

Other endpoints

Same authentication as above. About 120 requests per minute per merchant.

GET https://gatenoc.com/api/v1/merchant/payments/{id} — one payment (404 if not yours)
GET https://gatenoc.com/api/v1/merchant/payments?merchant=&status=&from=&to=&per_page= — paginated data, current_page, total
GET https://gatenoc.com/api/v1/merchant/balance?merchant= — received_total, refunded_total, available_ledger
POST https://gatenoc.com/api/v1/merchant/payments/{id}/refund — body {"amount":1,"reason":"..."} → 201 with refund_id, status

HTTP errors

Code	Meaning
401	Missing or invalid payment API key, merchant id mismatch, or inactive merchant / Bybit account
404	Payment id not found (REST)
422	Validation error (e.g. amount below minimum)
429	Rate limited — retry after `retry_after_seconds`