Developer API

Accept USD invoices with USDT payment

Create a checkout session, send your customer the returned link, and they pay the exact amount on a hosted page. No card fields — Bybit internal transfer.

1 POST checkout-session 2 Open checkout_url 3 Customer pays USDT (1 USD = 1 USDT)

Integration checklist

  • 1) Create API merchant and copy X-Merchant-Key
  • 2) Call POST /api/v1/merchant/checkout-session from backend
  • 3) Redirect customer to checkout_url
  • 4) Do not manually build public checkout URLs by merchant ID.
  • 5) Customer must pay exact amount shown on invoice
  • 6) If you see Invalid merchant key or inactive merchant: use a Gateway API merchant (not SMM), copy the key from Integration, ensure merchant + linked Bybit account are active, and forward X-Merchant-Key from your server (or Edge function) with no typos or extra spaces.

Flow

  • 1) Server creates session with amount and optional note.
  • 2) API returns checkout_url.
  • 3) Customer opens link and pays exact invoice amount.

Sandbox credentials

Use these test values to verify gateway integration flow before production keys.

Base URL: https://gatenoc.com
Endpoint: https://gatenoc.com/api/v1/merchant/checkout-session
Header: X-Merchant-Key: SANDBOX_PUBLIC_KEY
Sample amount: 10.50
Sample note: sandbox_order_1001

If your sandbox account uses different test keys, replace the header value only.

Quick start Auth Create payment Webhooks Errors

Quick start

Call the API from your backend. Use your app’s base URL as https://gatenoc.com.

  1. Create an API merchant in the dashboard and copy X-Merchant-Key.
  2. POST JSON with amount (and optional note).
  3. Redirect the customer to checkout_url.

Base URL

https://gatenoc.com

Endpoint

https://gatenoc.com/api/v1/merchant/checkout-session

Authentication

Send the merchant API key in a header on every request. The key identifies your API merchant.

Header 
X-Merchant-Key: YOUR_PUBLIC_API_KEY
Security: do not put the key in frontend JavaScript, mobile apps, or public repos. Call this API only from your server.

Create payment

Single endpoint creates a short-lived session and returns shareable checkout links.

HTTP

POST https://gatenoc.com/api/v1/merchant/checkout-session

Request body (JSON)

application/json
{
  "amount": 10.50,
  "note": "order_123",
  "notify_url": "https://your-server.com/webhooks/gateway-paid",
  "success_url": "https://yourstore.com/checkout/done",
  "support_url": "https://yourstore.com/help"
}

Fields

Field Type Required Description
amount number Yes Invoice amount in USD (payer sends the same value in USDT; 1 USD = 1 USDT).
note string No Optional reference. Legacy username is accepted as an alias.
notify_url string (URL) No HTTPS endpoint on your server. When the payment is confirmed (Bybit webhook or customer submits TXID on the pay page), the gateway POSTs JSON payment.completed with amount, bybit_pay_id, note, and payment_record_id. Header X-Gateway-Merchant-Key repeats your public API key.
success_url string (URL) No Where to send the customer after payment succeeds on the hosted page. If omitted, the payer is redirected to your merchant Site URL (dashboard) with gateway_status=paid and gateway_payment_id (internal record id). Never uses /addfunds for API checkout.
support_url string (URL) No “Support & help” link on the pay page. If omitted, defaults to {site_url}/tickets when Site URL is set, else this gateway’s contact page.

Success response 200

{
  "checkout_url": "https://gatenoc.com/checkout/{merchant_id}?cs=PAYMENT_SESSION_TOKEN",
  "invoice_url": "https://gatenoc.com/checkout/{merchant_id}?cs=PAYMENT_SESSION_TOKEN",
  "merchant_id": 0,
  "amount": 10.5,
  "currency": "USD",
  "expires_at": "2026-03-24T12:00:00+00:00",
  "note": "order_123"
}

The note field is omitted when you did not send one.

Invoices: you can paste invoice_url into email or chat — same as checkout_url.

Examples

cURL

curl -X POST "https://gatenoc.com/api/v1/merchant/checkout-session" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Merchant-Key: YOUR_PUBLIC_API_KEY" \
  -d '{"amount":10.50,"note":"order_123"}'

JavaScript (Node / server)

const res = await fetch("https://gatenoc.com/api/v1/merchant/checkout-session", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-Merchant-Key": "YOUR_PUBLIC_API_KEY"
  },
  body: JSON.stringify({ amount: 10.5, note: "order_123" })
});
const data = await res.json();

PHP

$ch = curl_init('https://gatenoc.com/api/v1/merchant/checkout-session');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Accept: application/json',
        'X-Merchant-Key: YOUR_PUBLIC_API_KEY',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'amount' => 10.50,
        'note' => 'order_123',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$res = json_decode(curl_exec($ch), true);
if (!empty($res['checkout_url'])) {
    header('Location: ' . $res['checkout_url']);
    exit;
}

Webhooks

Bybit notifies this gateway when a Bybit Pay order completes. To notify your backend, pass notify_url when creating the checkout session. The gateway POSTs a JSON body to that URL when the payment is recorded (automatic Bybit confirmation or manual TXID verification on the pay page). Use success_url so the customer’s browser returns to your app after paying; polling notify_url alone is optional.

Errors

Responses are JSON with an error string and often a hint for integration issues.

401 “Invalid merchant key or inactive merchant” means the server did not find an active Gateway API merchant with that exact api_public_key, or the merchant’s linked Bybit account is missing or inactive. It is not your Supabase project key — use the merchant key from this dashboard only.

401 — auth

{"error":"Missing X-Merchant-Key header","hint":"..."}
{"error":"Invalid merchant key or inactive merchant","hint":"..."}

422 — validation

{"error":"Amount below minimum","min_amount":1}

Dummy transaction IDs (testing)

Use a predictable transaction ID format in sandbox so your verify flow and reports are easy to review.

Suggested memo format

SBX-TX-20260324-0001

Suggested metadata pattern

sandbox_order_1001|api-v1|test
  • - Track memo as transaction ID in payment details.
  • - Keep metadata stable across retries so duplicate detection is easier.
  • - Move to production keys after successful end-to-end sandbox run.

Verification checklist

  • - Create session returns checkout_url with 200 response.
  • - Sandbox payment appears in admin Sandbox Reports.
  • - Payment details show memo as transaction ID and metadata pattern.
  • - Integration logs include your own order ID for reconciliation.