API Documentation

Getting Started

Create a merchant, generate a payment API key, and call the checkout session endpoint. Most integrations ship in under an hour.

Credentials

Dashboard → Merchants → Integration: payment API key (outbound) and webhook secret (verify inbound POSTs).

Log in or register for API keys.

Authentication

All Merchant API requests require a Bearer token (or X-Merchant-Key).

Bearer token

Authorization: Bearer YOUR_PAYMENT_API_KEY

Keep keys server-side only
Rotate keys if exposed
Optional merchant_id must match the key’s merchant

Never embed payment API keys in client-side apps or public repositories.

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

Quick Start

Create a checkout session and redirect the customer to checkout_url.

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

$ch = curl_init('https://gatenoc.com/api/v1/merchant/checkout-session');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer '.$apiKey,
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 10.50,
    'note' => 'order_123',
  ]),
  CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);

const res = await fetch('https://gatenoc.com/api/v1/merchant/checkout-session', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ amount: 10.5, note: 'order_123' }),
});
const data = await res.json();
// data.checkout_url

import requests
r = requests.post(
  "https://gatenoc.com/api/v1/merchant/checkout-session",
  headers={"Authorization": f"Bearer {api_key}"},
  json={"amount": 10.50, "note": "order_123"},
)
print(r.json()["checkout_url"])

req, _ := http.NewRequest("POST", "https://gatenoc.com/api/v1/merchant/checkout-session", bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer "+apiKey)
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

Response

{
  "checkout_url": "https://…/checkout/…",
  "expires_at": "2026-07-31T12:30:00+00:00",
  "merchant_id": 1
}

Payments

Retrieve a single payment or list payments for a merchant. Same auth. ~300 requests/min per merchant.

GET https://gatenoc.com/api/v1/merchant/payments/{id}

Authentication required · Returns the same fields as the webhook payload.

GET https://gatenoc.com/api/v1/merchant/payments

Query: status, from, to, per_page

Invoices

Create a hosted checkout session (invoice). Amount is USD (USDT 1:1).

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

Authentication required · Rate limit ~300/min · Optional Idempotency-Key (24h replay)

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

Optional Template 2 preselect

When Checkout Template 2 is active, optional gateway, currency/token, and chain/network can skip or prefill stage 1.

Refunds

Request a refund against a paid payment.

POST https://gatenoc.com/api/v1/merchant/payments/{id}/refund

Body: amount, optional reason.

Merchants

Merchant records, API keys, and gateway enablement are managed in the dashboard under Merchants → Integration. API calls are scoped to the authenticated merchant key.

Related: Authentication · Getting Started

Balances

GET https://gatenoc.com/api/v1/merchant/balance

Authentication required. Returns the merchant’s credited balance summary.

Withdrawals

Payout requests are initiated from the merchant dashboard. Configure withdrawal methods in account settings, then request a payout when your balance is ready.

Webhooks

JSON POST to your notify_url when a payment settles. Verify HMAC with the webhook secret (not the API key).

Your system creates a checkout session and stores the reference.

Customer opens checkout_url and completes payment on the hosted page.

GateNoc POSTs payment.completed, payment.overpaid, or payment.underpaid to notify_url with signature headers.

Return HTTP 200 quickly. Retry policy applies on non-2xx responses.

Use status + amount (credited gross). Over/underpaid amount is what the customer actually sent.

Headers: X-Gateway-Timestamp, X-Gateway-Signature as t=<ts>,v1=<hex> — HMAC-SHA256 of <timestamp>.<raw_body>.

status / event

completed → event: payment.completed (exact invoice amount credited)
overpaid → event: payment.overpaid (credits FlowNoc amount_fiat_received / amount_received_usd, e.g. invoice 10 / received 10.59)
underpaid → event: payment.underpaid (credits received fiat the same way when shortfall)

success is true for all three. Wallet credit uses amount minus the merchant receive fee (same as exact paid).

{
  "event": "payment.completed",
  "success": true,
  "status": "completed",
  "merchant_id": 1,
  "amount": "10.50",
  "currency": "USD",
  "payment_id": 42,
  "paid_at": "2026-03-24T12:00:00+00:00"
}

{
  "event": "payment.overpaid",
  "success": true,
  "status": "overpaid",
  "merchant_id": 1,
  "amount": "10.59",
  "currency": "USD",
  "payment_id": 43,
  "paid_at": "2026-08-06T13:39:17+00:00"
}

{
  "event": "payment.underpaid",
  "success": true,
  "status": "underpaid",
  "merchant_id": 1,
  "amount": "16.00",
  "currency": "USD",
  "payment_id": 44,
  "paid_at": "2026-08-06T14:00:00+00:00"
}

Errors

Standard HTTP status codes. Search the table below.

Code	Meaning	Action
401	Invalid or missing key	Check Bearer token / X-Merchant-Key
404	Not found	Verify payment or resource id
422	Validation error	Fix request body fields
429	Rate limited	Backoff and retry

SDKs

Official SDKs are not required—the REST API works with any HTTP client. Use the Quick Start samples for cURL, PHP, JavaScript, Python, and Go.

Changelog

API v1

Checkout session, payments, balance, refunds, and signed webhooks.

Partial settlements

Webhook/API status overpaid and underpaid with events payment.overpaid / payment.underpaid. Credited amount is what the customer sent (minus receive fee on wallet).