گیت‌میکس
مستندات

مستندات API تراکنش‌ها

راهنمای جامع استفاده از API ایجاد تراکنش و دریافت وضعیت تراکنش

تنظیم هدر x-api-key

برای احراز هویت درخواست‌های API، باید هدرx-api-keyرا تنظیم کنید. مقدار این هدر کلید API شماست که پس از ساخت فروشگاه به شما اختصاص داده می‌شود.

headers: { 'x-api-key': 'YOUR_API_KEY_HERE' }

ایجاد تراکنش

برای ایجاد تراکنش، یک درخواستPOSTبه آدرس زیر ارسال کنید:

POST https://dummyapi.example.com/invoices

۱ساختار درخواست (JSON)

فیلدنوع دادهضروریتوضیحات
storeIdعدد مثبتبلهشناسه عددی فروشگاه
gatewayIdعدد مثبتخیرشناسه عددی درگاه پرداخت (در صورت عدم ارسال کاربر لیست درگاه‌ها را مشاهده می‌کند)
statusenumخیریکی از: pending،processing،paid،cancelled،review(وضعیت اولیه لینک پرداخت)
deadlineAtعدد مثبتخیرمهلت پرداخت (میزان اعتبار لینک پرداخت به دقیقه)
amountعدد مثبتبلهمبلغ تراکنش (با توجه به واحد پول انتخاب شده)
descriptionرشته توضیحات (حداکثر 250 کاراکتر)خیرتوضیحات تراکنش که در صفحه رسید به کاربر نشان داده می‌شود
currencyenumبلهیکی از:USD،IRR،TMN،POL،TRX،TON،BNB
callbackUrlرشته (URL)بلهتغییر وضعیت تراکنش توسط ما به این آدرس به صورت زنده با درخواست POST اعلام می‌شود
successRedirectUrlرشته (URL)بلهدر صورت خاموش بودن نمایش رسید، کاربر پس از پرداخت موفق به این آدرس هدایت می‌شود
failRedirectUrlرشته (URL)بلهدر صورت خاموش بودن نمایش رسید، کاربر پس از پرداخت ناموفق به این آدرس هدایت می‌شود
customerPhoneNumberرشتهخیرشماره موبایل کاربر (در صورت عدم ارسال، فرم ورود شماره موبایل نمایش داده می‌شود)
customerIpرشته (حداکثر 50 کاراکتر)خیرآدرس IP
customerEmailرشته (حداکثر 320 کاراکتر)خیرایمیل کاربر
scoreعددخیرامتیاز کاربر (برای نمایش درگاه های خاص خصوصی به کاربران وفادار)

۲مثال درخواست

ایجاد تراکنش
const url = 'https://dummyapi.example.com/invoices';
const options = {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    'x-api-key': 'DUMMY_KEY'
  },
  body: JSON.stringify({
    storeId: 1,
    amount: 2,
    currency: 'USD',
    callbackUrl: 'https://dummy-callback.example.com',
    successRedirectUrl: 'https://dummy-success.example.com',
    failRedirectUrl: 'https://dummy-fail.example.com'
  })
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

مثال پاسخ موفق

  {
    "storeId": 1,
    "amount": 2,
    "currency": "USD",
    "callbackUrl": "https://mybot.com/pay/callback",
    "successRedirectUrl": "https://mybot.com/pay?status=success",
    "failRedirectUrl": "https://mybot.com/pay?status=failed",
    "txid": 29477,
    "createdAt": "2025-03-12T01:22:19.914+03:30",
    "updatedAt": "2025-03-12T01:22:19.914+03:30",
    "id": 29
  }

حالا شما باید کاربر را به آدرس تراکنش ساخته شده هدایت کنید (در اینجا شناسه ۲۹):

GET https://dummyapi.example.com/payment/29

دریافت وضعیت تراکنش

برای دریافت وضعیت یک تراکنش، یک درخواستGETبه آدرس زیر ارسال کنید (در آنtxid در URL قرار می‌گیرد):

GET https://dummyapi.example.com/invoices/28442

۱مثال درخواست

دریافت وضعیت
const url = 'https://dummyapi.example.com/invoices/28442';
const options = {
  method: 'GET',
  headers: {
    'x-api-key': 'DUMMY_KEY'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

مثال پاسخ موفق

{
  "id": 27,
  "txid": "28442",
  "otp": null,
  "storeId": 3,
  "gatewayId": 4,
  "status": "paid",
  "kycStatus": "unverified",
  "deadlineAt": "20",
  "currency": "TMN",
  "amount": 80000,
  "payable": 800000,
  "paymentRef": null,
  "callbackUrl": "https://dummy-callback.example.com",
  "callbackStatus": "successful",
  "successRedirectUrl": "https://dummy-success.example.com",
  "failRedirectUrl": "https://dummy-fail.example.com",
  "customerIp": "103.214.7.180",
  "customerFingerprint": "b9a5d08fca003fcb997b3c343c0e1ad2",
  "customerPhoneNumber": null,
  "customerEmail": null,
  "score": 0,
  "createdAt": "2025-03-11T17:11:21.637+03:30",
  "updatedAt": "2025-03-11T19:55:42.850+03:30",
  "description": null,
  "store": {
    "id": 3,
    "userId": 1,
    "name": "Dummy Store",
    "url": "https://dummy-store.example.com",
    "token": "DUMMY_KEY",
    "status": "active",
    "createdAt": "2025-02-07T09:48:24.016+03:30",
    "updatedAt": "2025-02-07T09:48:24.016+03:30",
    "returnType": "origin"
  },
  "gateway": {
    "id": 4,
    "storeId": 3,
    "name": "Dummy Gateway",
    "accountNumber": "0000000000000000",
    "publicAddress": "Dummy Public",
    "privateKey": null,
    "accessToken": null,
    "type": "shetab",
    "kyc": false,
    "noVpn": false,
    "status": "active",
    "minScore": 0,
    "createdAt": "2025-03-11T16:08:34.539+03:30",
    "updatedAt": "2025-03-11T16:54:11.108+03:30"
  },
  "transactionHistories": [
    {
      "id": 25,
      "transactionId": 27,
      "status": "cancelled",
      "description": null,
      "createdAt": "2025-03-11T17:40:45.054+03:30",
      "updatedAt": "2025-03-11T17:40:45.054+03:30"
    },
    {
      "id": 27,
      "transactionId": 27,
      "status": "paid",
      "description": null,
      "createdAt": "2025-03-11T19:53:38.158+03:30",
      "updatedAt": "2025-03-11T19:53:38.158+03:30"
    }
  ]
}

مثال پاسخ خطا

{
  "errors": [
    {
      "message": "Transaction not found or invalid api key"
    }
  ]
}

اعتبارسنجی Callback

هنگامی که سرور callback ارسال می‌کند، payload شامل اطلاعات تراکنش به همراهhash تولید شده با استفاده از HMAC-SHA1 و token است. برای اطمینان از اینکه این callback از سرور معتبر ارسال شده، کلاینت باید دوباره HMAC را با استفاده از token محاسبه کرده و مقدار به‌دست‌آمده را باhashدریافتی مقایسه کند.

Callback Verification
import crypto from 'crypto';

/**
 * Verifies the authenticity of a callback by comparing hashes
 * @param {Object} data - The callback payload with transaction data and hash
 * @param {string} token - Your secret token shared with the server
 * @returns {boolean} - True if callback is verified as authentic
 */
function verifyCallback(data, token) {
  const { hash, ...payload } = data;
  const payloadString = JSON.stringify(payload);
  const computedHash = crypto.createHmac('sha1', token)
                           .update(payloadString)
                           .digest('hex');
  return computedHash === hash;
}

// Example usage:
// Assuming req.body contains the callback payload 
if (verifyCallback(req.body, 'YOUR_SECRET_TOKEN')) {
  console.log("Callback is authentic");
} else {
  console.error("Invalid callback signature");
}