آموزش‌ها

مستندات API

اتصال درگاه ایزی گیت به وب‌سایت شما

آموزش اتصال درگاه ایزی گیت

قسمت ۱

دریافت ارزها و شبکه‌های قابل پذیرش

در این قسمت لیست ارز و شبکه‌هایی را می‌گیرید که برای درگاه سایتتان فعال شده‌اند.

برای پذیرش پرداخت در سایتتان، ابتدا باید بدانید مشتری‌تان می‌تواند با کدام ارز و روی کدام شبکه پرداخت کند.

این لیست را قبلاً در داشبورد، صفحه Gateway، برای همان درگاه انتخاب کرده‌اید. API زیر همان تنظیمات را برمی‌گرداند.

  1. 1

    ApiKey را از داشبورد بردارید

    وارد داشبورد ایزی گیت شوید و به صفحه Gateway بروید. ApiKey همان درگاهی که می‌خواهید به سایتتان وصل کنید را کپی کنید.

    این کلید را محرمانه نگه دارید و ترجیحاً از سرور خودتان صدا بزنید تا در مرورگر مشتری‌تان دیده نشود.

  2. 2

    لیست ارز و شبکه را بگیرید

    یک درخواست GET به آدرس زیر بزنید و ApiKey را به‌صورت query parameter ارسال کنید.

    پاسخ، آرایه‌ای از ارزهاست؛ هر ارز شبکه‌های فعال خودش را در networkDetails دارد. همین‌ها را در صفحه پرداخت سایتتان به مشتری‌تان نشان دهید.

GEThttps://api.ezgate.org/api/PortalWallet/GetPortalCurrenciesByToken
نمونه Python
import requests

API_KEY = "YOUR_API_KEY"
url = "https://api.ezgate.org/api/PortalWallet/GetPortalCurrenciesByToken"

response = requests.get(
    url,
    params={"ApiKey": API_KEY},
    headers={"accept": "*/*"},
)
payload = response.json()

if payload.get("statusCode") != 200:
    raise RuntimeError(payload.get("message") or "Could not load currencies")

currencies = payload.get("data") or []
نمونه پاسخ
{
  "statusCode": 200,
  "message": "عملیات با موفقیت انجام شد",
  "errors": null,
  "data": [
    {
      "currencyId": 1,
      "currencySymbol": "USDT",
      "currencyTitle": "Tether",
      "currencyPersianName": "تتر",
      "currencyLogoUrl": "https://chante.app/images2/USDT.png",
      "decimals": 2,
      "buyPriceIncreasePercent": 0,
      "sellPriceIncreasePercent": 0,
      "hasMemo": false,
      "networkDetails": [
        {
          "id": 15,
          "name": "ترون TRX (TRC-20)",
          "symbol": "TRX",
          "networkFee": 4
        },
        {
          "id": 19,
          "name": "بایننس اسمارت چین BSC (BEP20)",
          "symbol": "BNB",
          "networkFee": 2
        }
      ]
    }
  ],
  "count": 1
}

فیلدهای هر ارز

نامنوعتوضیح
currencyIdnumberشناسه ارز
currencySymbolstringنماد ارز؛ مثلاً USDT
currencyTitlestringنام انگلیسی ارز
currencyPersianNamestringنام فارسی ارز
currencyLogoUrlstringآدرس لوگوی ارز
decimalsnumberتعداد رقم اعشار مجاز برای مبلغ
buyPriceIncreasePercentnumberدرصد افزایش قیمت خرید که در داشبورد تنظیم شده
sellPriceIncreasePercentnumberدرصد افزایش قیمت فروش که در داشبورد تنظیم شده
hasMemobooleanاگر true باشد شبکه به memo یا تگ نیاز دارد
networkDetailsarrayشبکه‌هایی که این ارز روی آن‌ها برای درگاه شما فعال است

فیلدهای هر شبکه (networkDetails)

نامنوعتوضیح
idnumberشناسه شبکه؛ همان networkId مرحله بعد
namestringنام نمایشی شبکه
symbolstringنماد شبکه؛ مثلاً TRX یا BNB
networkFeenumberکارمزد شبکه

قسمت ۲

ساخت سفارش و هدایت مشتری به پرداخت

در این قسمت سفارش را می‌سازید و مشتری‌تان را به صفحه پرداخت می‌فرستید.

وقتی مشتری‌تان ارز و شبکه را انتخاب کرد، با یک درخواست POST سفارش را در ایزی گیت ایجاد کنید.

توکن دسترسی را در هدر Authorization به‌صورت Bearer بفرستید. ApiKey همان درگاه را هم در بدنه درخواست بگذارید.

  1. 1

    فیلدهای درخواست را آماده کنید

    amount مبلغ دقیق رمزارزی است که مشتری‌تان باید بپردازد؛ نه مبلغ فیات.

    currencyId و networkId را از پاسخ API مرحله قبل بردارید (currencyId هر ارز و id داخل networkDetails).

    apiKey را از داشبورد، صفحه Gateway، کپی کنید.

  2. 2

    refNumber یکتا بسازید

    refNumber شناسه سفارش شما نزد ایزی گیت است و نباید تکراری باشد. اگر یک مقدار را دوباره بفرستید، ساخت سفارش شکست می‌خورد.

    بهترین کار استفاده از UUID است. می‌توانید شناسه داخلی سفارشتان را هم به‌عنوان پیشوند به آن بچسبانید تا بعداً در حسابداری خودتان پیدایش کنید.

  3. 3

    مشتری‌تان را به paymentUrl بفرستید

    در پاسخ موفق، فیلد مهم paymentUrl است. کافی است مشتری‌تان را به همین لینک هدایت کنید؛ صفحه پرداخت ایزی گیت بقیه کار را انجام می‌دهد.

    پس از پرداخت یا انقضا، وضعیت سفارش با callback به همان آدرسی اعلام می‌شود که در داشبورد، صفحه Gateway، بخش جزئیات تنظیم کرده‌اید.

POSThttps://api.ezgate.org/api/Order

تولید refNumber یکتا

قبل از ساخت سفارش، یک refNumber تولید کنید و همان را در دیتابیس خودتان کنار سفارش ذخیره کنید تا با callback بعداً تطبیق بدهید.

نمونه Python
import uuid

# Recommended: UUID hex is unique without a central counter
ref_number = uuid.uuid4().hex
# e.g. "3f1a9c0e8b4d47c2a6f5d1e0c9b8a7d6"

# Or prefix it with your own internal order id
internal_id = 1842
ref_number = f"{internal_id}-{uuid.uuid4().hex[:12]}"
# e.g. "1842-9c0e8b4d47c2"

# Never send the same refNumber twice to ezGate
نمونه Python
import uuid
import requests

ACCESS_TOKEN = "YOUR_ACCESS_TOKEN"
API_KEY = "YOUR_API_KEY"
url = "https://api.ezgate.org/api/Order"

ref_number = uuid.uuid4().hex

response = requests.post(
    url,
    headers={
        "accept": "*/*",
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "Content-Type": "application/json",
    },
    json={
        "amount": 1,
        "refNumber": ref_number,
        "currencyId": 1,
        "networkId": 19,
        "apiKey": API_KEY,
    },
)
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": "عملیات با موفقیت انجام شد",
  "errors": null,
  "data": {
    "orderId": "a0d38e98-5738-4329-8c46-a1c2096e70bf",
    "refNumber": "testtest",
    "currency": {
      "symbol": "USDT",
      "persianName": "تتر",
      "name": "USDT",
      "id": 2
    },
    "walletAddress": "0x4584b610A34c9898d52d4E571f8708740993fE1C",
    "paymentUrl": "https://ezgate.org/pay/a0d38e98-5738-4329-8c46-a1c2096e70bf",
    "expiresAt": "2026-08-18T11:30:45.8066667"
  },
  "count": 1
}

بدنه درخواست

نامنوعتوضیح
amountnumberمبلغ دقیق رمزارز که مشتری‌تان باید پرداخت کند
refNumberstringشناسه یکتای سفارش؛ نباید تکراری باشد
currencyIdnumberاز API مرحله قبل؛ فیلد currencyId
networkIdnumberاز API مرحله قبل؛ فیلد id داخل networkDetails
apiKeystringApiKey درگاه از داشبورد، صفحه Gateway

فیلدهای data در پاسخ

نامنوعتوضیح
orderIdstringشناسه سفارش در ایزی گیت
refNumberstringهمان مقداری که ارسال کردید
currencyobjectاطلاعات ارز سفارش
walletAddressstringآدرس ولت اختصاصی این سفارش
paymentUrlstringلینک صفحه پرداخت؛ مشتری‌تان را به اینجا هدایت کنید
expiresAtstringزمان انقضای سفارش

هدر Authorization را به‌صورت Bearer YOUR_ACCESS_TOKEN بفرستید.

نتیجه پرداخت با callback به URLای می‌رسد که در جزئیات درگاه (صفحه Gateway) ثبت کرده‌اید. نیازی نیست بعد از هدایت مشتری‌تان منتظر بمانید؛ callback وضعیت را به سرور شما اعلام می‌کند.