Every API merchant has a payment API key and webhook secret in the dashboard under Merchants → your API merchant → Integration. The key identifies your merchant for outbound API calls; the secret verifies inbound webhooks. A numeric merchant id is shown for your records—you do not need to send it if you authenticate only with the API key.

Authenticate with your payment API key only: Authorization: Bearer … or header X-Merchant-Key. The webhook secret is not used here—see Webhooks.

Optional merchant id headers, query, or JSON fields are ignored unless present; when present they must match the merchant that owns the key.

Recommended headers

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

Alternative

X-Merchant-Key: YOUR_PAYMENT_API_KEY

Optional compatibility: merchant, X-Merchant-Id, ?merchant=, or JSON merchant / merchant_id when provided must match your merchant.

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
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",
  "return_url": "https://yoursite.com/deposit"
}

• Optional return_url — page to send the customer after pay; any valid http(s) URL (any domain). If omitted, we may capture the browser Referer when allowed. success_url still wins when it is a specific path; if success_url is only your site root, return_url / captured page is preferred.
• 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 — URL shape /checkout/<public_key>/<session> (legacy ?cs= on the base checkout URL still works). Session is valid until expires_at (often ~30 minutes).

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).

Example JSON body

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

reference — gateway transaction or order id (format depends on the payment method). Webhooks no longer include bybit_pay_id; use reference instead.

Same authentication as above. About 120 requests per minute per merchant. For merchants created only on App, use https://app.gatenoc.com instead of https://gatenoc.com in each URL below.

• GET https://gatenoc.com/api/v1/merchant/payments/{id} — one payment (404 if not yours)
• GET https://gatenoc.com/api/v1/merchant/payments?status=&from=&to=&per_page= — paginated data, current_page, total (merchant inferred from API key)
• GET https://gatenoc.com/api/v1/merchant/balance — 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

{
  "id": 42,
  "status": "completed",
  "amount": "10.50",
  "currency": "USD",
  "note": "order_123",
  "merchant_trade_no": "550e8400-e29b-41d4-a716-446655440000",
  "reference": "1293e171-2094-4e2f-aacb-9c0dc900beab",
  "memo": "…",
  "paid_at": "2026-03-24T12:00:00+00:00",
  "created_at": "2026-03-24T11:55:00+00:00"
}