Once your customer has chosen a currency and network, create the order with a POST request.
Place the gateway ApiKey in the URL path, replacing {apiKey}. No Authorization header or apiKey in the body is needed.
- 1
Prepare the request fields
amount is the exact cryptocurrency amount your customer must pay — not a fiat amount.
Take currencyId and networkId from the previous API (currencyId on each currency, and id inside networkDetails).
Copy the gateway ApiKey from the dashboard, on the Gateway page, and put it in place of {apiKey} at the end of the URL.
- 2
Generate a unique refNumber
refNumber is your order id at ezGate and must not be reused. Sending a duplicate value will fail order creation.
You can use your own site’s order id directly; there is no need to generate a separate value. Just make sure it is unique per order.
- 3
Send your domain in the Origin header
The CreateOrder request must send your site’s domain in the Origin header (and in Referer when possible); without it the request is rejected.
The domain you send must match the domain of the callback URL registered in the dashboard (Gateway page, gateway details) exactly. For example, if your callback URL is https://back.yourdomain.ir/app/v1/crypto/verify-payment, Origin must be https://back.yourdomain.ir — otherwise the request fails with an error.
So you send the same origin you registered for the callback in the CreateOrder request as well. Set this header on your server, not in the customer’s browser.
- 4
Redirect your customer to paymentUrl
On success, paymentUrl is the field that matters. Redirect your customer to that link; the ezGate payment page handles the rest.
After payment or expiry, order status is sent as a callback to the URL you configured in the dashboard, on the Gateway page, in the gateway details.
POSThttps://api.ezgate.org/api/Order/CreateOrder/{apiKey}
Generate a unique refNumber
The simplest approach is to set refNumber to your own site’s order id so you can match the callback later. If you do not have such an id, use a UUID.
import uuid
# Option 1: reuse your own order id from your site
ref_number = "YOUR_ORDER_ID"
# e.g. "ORD-1842" or "10000231"
# Option 2: generate a random unique value (UUID hex)
ref_number = uuid.uuid4().hex
# e.g. "3f1a9c0e8b4d47c2a6f5d1e0c9b8a7d6"
# Never send the same refNumber twice to ezGate
Create order code sample
import uuid
import requests
API_KEY = "YOUR_API_KEY"
url = f"https://api.ezgate.org/api/Order/CreateOrder/{API_KEY}"
ref_number = uuid.uuid4().hex
# Origin must match the domain of your registered callback URL
# e.g. callback https://back.yourdomain.ir/app/v1/crypto/verify-payment
# Origin https://back.yourdomain.ir
ORIGIN = "https://back.yourdomain.ir"
response = requests.post(
url,
headers={
"accept": "*/*",
"Content-Type": "application/json",
"Origin": ORIGIN,
"Referer": f"{ORIGIN}/",
},
json={
"amount": 1,
"refNumber": ref_number,
"currencyId": 1,
"networkId": 19,
},
)
payload = response.json()
if payload.get("statusCode") != 200:
raise RuntimeError(payload.get("message") or "Could not create order")
order = payload["data"]
payment_url = order["paymentUrl"]
# Redirect your customer to payment_url
{
"statusCode": 200,
"message": "success",
"errors": null,
"data": {
"orderId": "55ebaf2b-04b4-415e-8b45-797c913c9a45",
"refNumber": "test",
"currency": {
"symbol": "USDT",
"persianName": "",
"name": "Tether",
"id": 1
},
"walletAddress": "0x4584b610A34c9898d52d4E571f8708740993fE1C",
"paymentUrl": "https://ezgate.org/pay/55ebaf2b-04b4-415e-8b45-797c913c9a45",
"expiresAt": "2026-08-27T15:36:13.89"
},
"count": 1
}
Request body
| Name | Type | Description |
|---|
| amount | number | Exact crypto amount your customer must pay |
| refNumber | string | Unique order reference; must not be reused |
| currencyId | number | From the previous API; the currencyId field |
| networkId | number | From the previous API; id inside networkDetails |
Response data fields
| Name | Type | Description |
|---|
| orderId | string | ezGate order id |
| refNumber | string | The value you sent |
| currency | object | Currency details for the order |
| walletAddress | string | Deposit address for this order |
| paymentUrl | string | Checkout URL; redirect your customer here |
| expiresAt | string | When the order expires |
You calculate and set the conversion rate to any cryptocurrency yourself; ezGate simply collects the crypto amount you announced from the customer.
Put the gateway ApiKey in place of {apiKey} at the end of the URL path; no Authorization header or apiKey in the body is needed.
In every request — including CreateOrder — send your site’s domain in the Origin (or Referer) header and make sure it matches the domain of the registered callback URL. Example: callback is https://back.yourdomain.ir/app/v1/crypto/verify-payment, so Origin must be https://back.yourdomain.ir. If Origin differs from the callback domain, the request fails with an error.
Payment result is delivered as a callback to the URL you saved in the gateway details (Gateway page). You do not need to wait after the redirect; the callback tells your server the outcome.
Request security: ezGate compares the request origin domain with your gateway's callback URL domain. If you send an Origin or Referer header, its domain must match your registered callback domain, otherwise the request fails with “Site origin does not match the site callback”. Server-to-server requests that do not send Origin/Referer are processed without this check.