مستندات 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 | عدد مثبت | خیر | شناسه عددی درگاه پرداخت (در صورت عدم ارسال کاربر لیست درگاهها را مشاهده میکند) |
| status | enum | خیر | یکی از: pending،processing،paid،cancelled،review(وضعیت اولیه لینک پرداخت) |
| deadlineAt | عدد مثبت | خیر | مهلت پرداخت (میزان اعتبار لینک پرداخت به دقیقه) |
| amount | عدد مثبت | بله | مبلغ تراکنش (با توجه به واحد پول انتخاب شده) |
| description | رشته توضیحات (حداکثر 250 کاراکتر) | خیر | توضیحات تراکنش که در صفحه رسید به کاربر نشان داده میشود |
| currency | enum | بله | یکی از: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");
}