NAV
json

پیش‌گفتار

این صفحه حاوی مستندات مربوط به API سواپ‌ولت است که به شما کمک می‌کند تا بتوانید بیشترین بهره را از حساب کاربری سواپ‌ولت خود ببرید. (نیاز داره که یه خلاصه‌ای از اینکه چه کارهایی می‌تونن باهاش انجام بدن رو داشته باشه)

لطفاً پیش از استفاده از APIها، اطمینان حاصل کنید که قوانین استفاده از سواپ‌ولت و هم‌چنین قوانین استفاده از API سواپ‌ولت را مطالعه کرده و پذیرفته‌اید. همچنین با عضویت در کانال رسمی اطلاع‌رسانی سواپ‌ولت، به صورت مستمر تغییرات ایجاد شده در APIها را رصد کنید تا در صورت نیاز، تغییرات لازم را اعمال کنید.

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

دریافت توکن

برای استفاده از APIها، نیاز دارید تا ابتدا توکن خود را از طریق بات تلگرامی سواپ‌ولت دریافت کنید. برای این کار، به قسمت تنظیمات ← توسعه‌دهندگان ← ایجاد کلید توسعه بروید؛ کلید خود را از پیام داخل بات دریافت کنید و در ادامه برای استفاده از APIها، از این توکن استفاده کنید.

دقت کنید که این بخش هنوز در وب‌اپلیکشن وجود ندارد و باید از طریق بات تلگرامی اقدام به دریافت توکن کنید. در صورتی که پیام مورد نظر را در ربات مشاهده نمی‌کنید یک پیام /start برای بات ارسال کنید.

همچنین برای منقضی کردن کردن توکن خود، می‌توانید در بات به قسمت تنظیمات ← توسعه‌دهندگان ← * منقضی کردن توکن* بروید؛ با این کار توکن قبلی شما منقضی می‌شود و یک توکن جدید جایگزین قبلی در پیام ارسالی می‌شود.

این توکن باید در Header درخواست‌های شما به صورت Authorization: Apikey <YourToken> ارسال شود.

پیشنهاد می‌کنیم تنها در صورتی که با روش‌های امن ذخیره‌ی گذرواژه در کد آشنایی دارید، اقدام به استفاده از توکن بکنید.

استفاده از API

با استفاده از این API می‌توانید از درست بودن توکن و روش استفاده از آن اطمنان حاصل پیدا کنید.

curl 'https://swapwallet.app/api/v1/utils/authentication/check' -H 'Authorization: Apikey <token>'

در صورت فراخوانی درست، پاسخ به این صورت خواهد بود:

{
  "status": "OK"
}

در صورت وجود خطا، پاسخ به این صورت خواهید بود:

{
  "status": "ERROR",
  "errorMessage": "UNAUTHORIZED"
}

HTTP Request

GET https://swapwallet.app/api/v1/utils/authentication/check

خروجی

پارامتر نوع توضیحات نمونه
status string وضعیت درخواست OK, ERROR

کسب و کار

برای استفاده از درگاه پرداخت ابتدا نیاز است تا یک کسب و کار ایجاد کنید، در زمان فراخوانی درگاه پرداخت باید یوزنیم کسب و کار خود را ارسال کنید

برای ایجاد کسب و کار خود از پنل فروشندگان به آدرس زیر استفاده کنید: https://pay.swapwallet.app

برای ورود به پنل از فیلترشکن روشن استفاده کرده و با استفاده از Login with Telegram می‌توانید به پنل خود دسترسی داشته باشید یوزرنیم باید از حروف و اعداد ایجاد شده باشد و برای هر کسب و کار یکتا است، برای کسب و کار خود یک نام مناسب انتخاب کنید چرا که کاربر در زمان پرداخت این نام را مشاهده خواهد کرد.

مشاهده‌ی موجودی کسب و کار

در زمان انجام پرداخت‌ها، مبلغ واریزی توسط کاربر به موجودی کسب و کار شما اضافه خواهد شد، در صورت نیاز می‌توانید با استفاده از این API، آخرین وضعیت موجودی حساب کسب و کار خود را دریافت کنید


curl 'https://swapwallet.app/api/v1/payment/application/{application-username}/balance'

در صورت فراخوانی درست، پاسخ به این صورت خواهد بود:

{
  "status": "OK",
  "result": {
    "totalValue": {
      "available": [
        {
          "number": "5380",
          "unit": "IRT"
        },
        {
          "number": "0.09",
          "unit": "USD"
        }
      ],
      "onHold": [
        {
          "number": "0",
          "unit": "IRT"
        },
        {
          "number": "0",
          "unit": "USD"
        }
      ]
    },
    "tokens": [
      {
        "name": "USDT",
        "available": {
          "amount": {
            "number": "0.09",
            "unit": "USDT"
          },
          "values": [
            {
              "number": "5380",
              "unit": "IRT"
            },
            {
              "number": "0.09",
              "unit": "USD"
            }
          ]
        }
      }
    ]
  }
}

درخواست تسویه حساب

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


curl -X POST 'https://swapwallet.app/api/v1/payment/application/{application-username}/settle-all'

در صورت فراخوانی درست، پاسخ به این صورت خواهد بود:

{
  "status": "OK"
}

HTTP Request

POST https://swapwallet.app/api/v1/payment/application

درگاه پرداخت

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

برای مثال شما می‌توایند رسیدی ایجاد کنید از ارز TON و با ارزش 10 USD که در این صورت با توجه به قیمت بازار مقدار رمزارز TON که باید کاربر بپردازد مشخص خواهد شد. همچنین می‌توانید رسیدی ایجاد کنید از ارز TON و با ارزش 10 TON که در این صورت مقدار ارزش رمزارز TON که کاربر باید پرداخت کند از قبل مشخص خواهد بود.

پرداخت با مقدار معین

در این روش شما ارز قابل پرداخت و ارزش مورد نیاز برای پرداخت را با استفاده از یک کوین مشخص می‌کنید، با این روش شما مطمئن خواهید بود که دقیقا مقداری که درخواست کرده بودید را از کاربر دریافت خواهید کرد.


curl -X POST 'https://swapwallet.app/api/v1/payment/my_application_username/invoice' -d '{
    "amount": {
        "number": "100",
        "unit": "TON"
    },
    "autoConversionToken": "TON",
    "ttl": 3600,
    "externalId": "your-unique-internal-inovice-id",
    "description": "PS5 Game | OverWatch3",
    "customData": "user-id=1000,order-id=12345 or {\"user-id\":12345,\"order-id\":12345}",
    "returnUrl": "https://t.me/gamee?start=checkme-12345",
    "userLanguage": "EN"
}'

در صورت فراخوانی درست، پاسخ به این صورت خواهد بود:

{
  "status": "OK",
  "result": {
    "id": "7b899cd7-8be9-4b1e-900d-120194b3939c",
    "supportCode": "AI-JK3PKDV-3E80",
    "status": "ACTIVE",
    "description": "PS5 Game | OverWatch3",
    "customData": "user-id=1000,order-id=12345 or {\"user-id\":12345,\"order-id\":12345}",
    "userLanguage": "EN",
    "returnUrl": "https://t.me/gamee?start=checkme-12345",
    "externalId": "your-unique-internal-inovice-id",
    "amount": {
      "number": "100",
      "unit": "TON"
    },
    "value": {
      "number": "270.5",
      "unit": "USD"
    },
    "feePayer": "APPLICATION",
    "feeAmount": {
      "number": "0",
      "unit": "TON"
    },
    "paymentLinks": [
      {
        "type": "TELEGRAM_BOT",
        "url": "https://t.me/SwapWalletBot?start=AI-7b899cd7-8be9-4b1e-900d-120194b3939c"
      },
      {
        "type": "TELEGRAM_WEBAPP",
        "url": "https://t.me/SwapWalletBot/app?startapp=AI-7b899cd7-8be9-4b1e-900d-120194b3939c"
      },
      {
        "type": "WEBSITE",
        "url": "https://swapwallet.app/payment?id=7b899cd7-8be9-4b1e-900d-120194b3939c"
      }
    ],
    "paidAt": null,
    "expiredAt": "2024-03-08T14:37:23.986097732Z",
    "createdAt": "2024-03-06T12:37:23.986382578Z"
  }
}

HTTP Request

POST https://swapwallet.app/api/v1/payment/{application-username}/invoice

ورودی

پارامتر نوع توضیحات نمونه
amount money ارزش رسید درخواستی، واحد می‌تواند کریپتو یا فیات باشد USD / IRT / USDT / BNB / TON / ETH / ...
autoConversionToken token ارز قابل پرداخت، ارزی که کاربر می‌تواند با آن پرداخت را انجام دهد USDT / BNB / TON / ETH / ...
ttl number [60-864000] مدت زمان اعتبار رسید پرداخت به ثانیه 3600
externalId string [max: 255] در صورت وجود داشتن،‌شناسه‌ی یکتای پرداخت شما، این فیلد باعث میشود که جلوی ایجاد چند رسید برای یک سفارش گرفته شود 6CF313C7-53D9-43C1-B26F-D1911CBA726D
customData string [max: 512] دیتای اضافه مورد نیاز برای سیستم، میتوانید دیتای خود را با فرمت مورد نظر در رسید قرار دهید و در صورت نیاز در بازدید‌های بعدی از آن استفاده کنید 6CF313C7-53D9-43C1-B26F-D1911CBA726D
description string [max: 255] توضیح در مورد رسید، پیشهاد می‌شود این مقدار را متن مفهوم برای اوپراتور پر کنید، این متن در پنل رسید‌ها می‌تواند برای یافتن رسید استفاده شود، مثلا نام خریدار، شناسه یا شماره موبایل او، محصولی که خریداری کرده یا مواردی از این چنین میتواند مفید باشد 6CF313C7-53D9-43C1-B26F-D1911CBA726D
userLanguage Language در صورتی که کاربر زبان پیش‌فرض برای خود مشخص نکرده باشد، این زبان برای پنل کاربری پرداخت مورد استفاده قرار خواهد گرفت، اگر نمیدانید زبان کاربر شما چیست این فیلد را خالی بگذارید 6CF313C7-53D9-43C1-B26F-D1911CBA726D
returnUrl url در صورت وجود داشتن، در انتها کاربر به این لینک بازگرداده خواهد شد https://t.me/gamee?start=checkme-12345

خروجی

پارامتر نوع توضیحات نمونه
id string شناسه‌ی پرداخت 64ceb56e6fc9d9d195049a79
supportCode string کد پیگیری سفارش AI-JK3PKDV-3E80
status string وضعیت پرداخت ACTIVE, SUCCESS, EXPIRED, CANCLED
externalId string [max: 255] در صورت وجود داشتن،‌شناسه‌ی یکتای پرداخت شما، این فیلد باعث میشود که جلوی ایجاد چند رسید برای یک سفارش گرفته شود 6CF313C7-53D9-43C1-B26F-D1911CBA726D
customData string [max: 512] دیتای اضافه مورد نیاز برای سیستم، میتوانید دیتای خود را با فرمت مورد نظر در رسید قرار دهید و در صورت نیاز در بازدید‌های بعدی از آن استفاده کنید 6CF313C7-53D9-43C1-B26F-D1911CBA726D
description string [max: 255] توضیح در مورد رسید، پیشهاد می‌شود این مقدار را متن مفهوم برای اوپراتور پر کنید، این متن در پنل رسید‌ها می‌تواند برای یافتن رسید استفاده شود، مثلا نام خریدار، شناسه یا شماره موبایل او، محصولی که خریداری کرده یا مواردی از این چنین میتواند مفید باشد 6CF313C7-53D9-43C1-B26F-D1911CBA726D
userLanguage Language در صورتی که کاربر زبان پیش‌فرض برای خود مشخص نکرده باشد، این زبان برای پنل کاربری پرداخت مورد استفاده قرار خواهد گرفت، اگر نمیدانید زبان کاربر شما چیست این فیلد را خالی بگذارید 6CF313C7-53D9-43C1-B26F-D1911CBA726D
returnUrl url در صورت وجود داشتن، در انتها کاربر به این لینک بازگرداده خواهد شد https://t.me/gamee?start=checkme-12345
amount money مقدار مورد نیاز برای پرداخت رسید، این مبلغ میتواند با مقدار مشخص شده توسط شما متفاوت باشد {"number": "100", "unit": "TON"}
value money ارزش دلاری رسید {"number": "270.5", "unit": "USD"}
feePayer string پرداخت کننده‌ی کارمزد، میتوانید پرداخت‌کننده را خودتان یا مشتریان مشخص کنید APPLICATION / USER
feeAmount money مقدار کارمزد مشخص شده، در صورتی که پرداخت‌کننده‌ی کارمزد خودتان باشید این مبلغ بعد از واریز از مبلغ اصلی کثر خواهد شد و در غیر این صورت موقع پرداخت به مبلغ اصلی اضافه خواهد شد و توسط کاربر پرداخت می‌شود {"number": "0", "unit": "TON"}
paymentLinks object لینک‌هایی پرداخت که می‌توانید برای کاربر ارسال کنید را مشخص میکند، در تلگرام پیشنهاد می‌شود از لینک دارکت استفاده کنید و در صورتی که وبسایت دارید از لینک وبسایت، تفاوت لینک‌ها را میتوانید در بات دمو مشاهده کنید {object}
paidAt datetime (ISO-8601) در صورت پرداخت شدن رسید، زمان پرداخت شدن رسید را مشخص میکند 2024-03-08T14:37:23.986097732Z / null
expiredAt datetime (ISO-8601) زمان منقضی شدن رسید را مشخص میکند 2024-03-08T14:37:23.986097732Z
createdAt datetime (ISO-8601) زمان ایجاد شدن رسید را مشخص میکند 2024-03-08T14:37:23.986097732Z

پرداخت با ارزش معین

در این روش شما کوین و ارزش مورد نظر (به دلار یا ریال) برای پرداخت را تایین می‌کنید، با این روش شما مقدار کوین مورد نیاز برای انتقال توسط سواپ‌ولت و با استفاده از قیمت آخرین تبادلات بازار مشخص خواهد شد. این روش به شما کمک می‌کند که با تغیرات ارزش بازارهای مختلف، با کاربرهای خود تبادلات عادلانه داشته باشید.

این روش دقیقا مانند قبل است با این تفاوت که مقدار مشخص شده در amount را می‌توانید به واحد‌های دیگر مثل دلار یا ریال وارد کنید

curl -X POST 'https://swapwallet.app/api/v1/payment/my_application_username/invoice' -d '{
    "amount": {
        "number": "10",
        "unit": "USD"
    },
    "autoConversionToken": "TON",
    "ttl": 180000,
    "externalId": "your-unique-internal-inovice-id-2",
    "description": "PS5 Game | OverWatch3",
    "customData": "user-id=1000,order-id=12345 or {\"user-id\":12345,\"order-id\":12345}",
    "returnUrl": "https://t.me/gamee?start=checkme-12345",
    "userLanguage": "EN"
}'

در صورت فراخوانی درست، پاسخ به این صورت خواهد بود:


{
  "status": "OK",
  "result": {
    "id": "366ec085-a206-40af-a37b-ff7c40ccbf52",
    "supportCode": "AI-7Y0OZQ4-MFJC",
    "status": "ACTIVE",
    "description": "PS5 Game | OverWatch3",
    "customData": "user-id=1000,order-id=12345 or {\"user-id\":12345,\"order-id\":12345}",
    "userLanguage": "EN",
    "returnUrl": "https://t.me/gamee?start=checkme-12345",
    "externalId": "your-unique-internal-inovice-id-2",
    "amount": {
      "number": "3.78",
      "unit": "TON"
    },
    "value": {
      "number": "10",
      "unit": "USD"
    },
    "feePayer": "APPLICATION",
    "feeAmount": {
      "number": "0",
      "unit": "TON"
    },
    "paymentLinks": [
      {
        "type": "TELEGRAM_BOT",
        "url": "https://t.me/SwapWalletBot?start=AI-366ec085-a206-40af-a37b-ff7c40ccbf52"
      },
      {
        "type": "TELEGRAM_WEBAPP",
        "url": "https://t.me/SwapWalletBot/app?startapp=AI-366ec085-a206-40af-a37b-ff7c40ccbf52"
      },
      {
        "type": "WEBSITE",
        "url": "https://swapwallet.app/payment?id=366ec085-a206-40af-a37b-ff7c40ccbf52"
      }
    ],
    "paidAt": null,
    "expiredAt": "2024-03-08T15:06:53.186196792Z",
    "createdAt": "2024-03-06T13:06:53.186520211Z"
  }
}

HTTP Request

POST https://swapwallet.app/api/v1/payment/{application-username}/invoice

ورودی

پارامتر نوع توضیحات نمونه
amount money ارزش رسید درخواستی، واحد می‌تواند کریپتو یا فیات باشد USD / IRT / USDT / BNB / TON / ETH / ...
autoConversionToken token ارز قابل پرداخت، ارزی که کاربر می‌تواند با آن پرداخت را انجام دهد USDT / BNB / TON / ETH / ...
ttl number [60-864000] مدت زمان اعتبار رسید پرداخت به ثانیه 3600
externalId string [max: 255] در صورت وجود داشتن،‌شناسه‌ی یکتای پرداخت شما، این فیلد باعث میشود که جلوی ایجاد چند رسید برای یک سفارش گرفته شود 6CF313C7-53D9-43C1-B26F-D1911CBA726D
customData string [max: 512] دیتای اضافه مورد نیاز برای سیستم، میتوانید دیتای خود را با فرمت مورد نظر در رسید قرار دهید و در صورت نیاز در بازدید‌های بعدی از آن استفاده کنید 6CF313C7-53D9-43C1-B26F-D1911CBA726D
description string [max: 255] توضیح در مورد رسید، پیشهاد می‌شود این مقدار را متن مفهوم برای اوپراتور پر کنید، این متن در پنل رسید‌ها می‌تواند برای یافتن رسید استفاده شود، مثلا نام خریدار، شناسه یا شماره موبایل او، محصولی که خریداری کرده یا مواردی از این چنین میتواند مفید باشد 6CF313C7-53D9-43C1-B26F-D1911CBA726D
userLanguage Language در صورتی که کاربر زبان پیش‌فرض برای خود مشخص نکرده باشد، این زبان برای پنل کاربری پرداخت مورد استفاده قرار خواهد گرفت، اگر نمیدانید زبان کاربر شما چیست این فیلد را خالی بگذارید 6CF313C7-53D9-43C1-B26F-D1911CBA726D
returnUrl url در صورت وجود داشتن، در انتها کاربر به این لینک بازگرداده خواهد شد https://t.me/gamee?start=checkme-12345

خروجی

پارامتر نوع توضیحات نمونه
id string شناسه‌ی پرداخت 64ceb56e6fc9d9d195049a79
supportCode string کد پیگیری سفارش AI-JK3PKDV-3E80
status string وضعیت پرداخت ACTIVE, SUCCESS, EXPIRED, CANCLED
externalId string [max: 255] در صورت وجود داشتن،‌شناسه‌ی یکتای پرداخت شما، این فیلد باعث میشود که جلوی ایجاد چند رسید برای یک سفارش گرفته شود 6CF313C7-53D9-43C1-B26F-D1911CBA726D
customData string [max: 512] دیتای اضافه مورد نیاز برای سیستم، میتوانید دیتای خود را با فرمت مورد نظر در رسید قرار دهید و در صورت نیاز در بازدید‌های بعدی از آن استفاده کنید 6CF313C7-53D9-43C1-B26F-D1911CBA726D
description string [max: 255] توضیح در مورد رسید، پیشهاد می‌شود این مقدار را متن مفهوم برای اوپراتور پر کنید، این متن در پنل رسید‌ها می‌تواند برای یافتن رسید استفاده شود، مثلا نام خریدار، شناسه یا شماره موبایل او، محصولی که خریداری کرده یا مواردی از این چنین میتواند مفید باشد 6CF313C7-53D9-43C1-B26F-D1911CBA726D
userLanguage Language در صورتی که کاربر زبان پیش‌فرض برای خود مشخص نکرده باشد، این زبان برای پنل کاربری پرداخت مورد استفاده قرار خواهد گرفت، اگر نمیدانید زبان کاربر شما چیست این فیلد را خالی بگذارید 6CF313C7-53D9-43C1-B26F-D1911CBA726D
returnUrl url در صورت وجود داشتن، در انتها کاربر به این لینک بازگرداده خواهد شد https://t.me/gamee?start=checkme-12345
amount money مقدار مورد نیاز برای پرداخت رسید، این مبلغ میتواند با مقدار مشخص شده توسط شما متفاوت باشد {"number": "100", "unit": "TON"}
value money ارزش دلاری رسید {"number": "270.5", "unit": "USD"}
feePayer string پرداخت کننده‌ی کارمزد، میتوانید پرداخت‌کننده را خودتان یا مشتریان مشخص کنید APPLICATION / USER
feeAmount money مقدار کارمزد مشخص شده، در صورتی که پرداخت‌کننده‌ی کارمزد خودتان باشید این مبلغ بعد از واریز از مبلغ اصلی کثر خواهد شد و در غیر این صورت موقع پرداخت به مبلغ اصلی اضافه خواهد شد و توسط کاربر پرداخت می‌شود {"number": "0", "unit": "TON"}
paymentLinks object لینک‌هایی پرداخت که می‌توانید برای کاربر ارسال کنید را مشخص میکند، در تلگرام پیشنهاد می‌شود از لینک دارکت استفاده کنید و در صورتی که وبسایت دارید از لینک وبسایت، تفاوت لینک‌ها را میتوانید در بات دمو مشاهده کنید {object}
paidAt datetime (ISO-8601) در صورت پرداخت شدن رسید، زمان پرداخت شدن رسید را مشخص میکند 2024-03-08T14:37:23.986097732Z / null
expiredAt datetime (ISO-8601) زمان منقضی شدن رسید را مشخص میکند 2024-03-08T14:37:23.986097732Z
createdAt datetime (ISO-8601) زمان ایجاد شدن رسید را مشخص میکند 2024-03-08T14:37:23.986097732Z

دریافت وضعیت سفارش

بعد از ایجاد درخواست و ارسال لینک پرداخت برای کاربر، می‌توانید با استفاده از این API وضعیت پرداخت را بررسی کنید. برای

اینکار موقع ساخت لینک پرداخت مقدار id را در دیتابیس خود ذخیره کنید، سپس به سادگی می‌توانید با استفاده از این API وضعیت

این سفارش‌ها را مشخص کنید.


curl 'https://swapwallet.app/api/v1/payment/my_application_username/invoice/366ec085-a206-40af-a37b-ff7c40ccbf52'

در صورت فراخوانی درست، پاسخ به این صورت خواهد بود:


{
  "status": "OK",
  "result": {
    "id": "366ec085-a206-40af-a37b-ff7c40ccbf52",
    "supportCode": "AI-7Y0OZQ4-MFJC",
    "status": "ACTIVE",
    "description": "PS5 Game | OverWatch3",
    "customData": "user-id=1000,order-id=12345 or {\"user-id\":12345,\"order-id\":12345}",
    "userLanguage": "EN",
    "returnUrl": "https://t.me/gamee?start=checkme-12345",
    "externalId": "your-unique-internal-inovice-id-2",
    "amount": {
      "number": "3.78",
      "unit": "TON"
    },
    "value": {
      "number": "10",
      "unit": "USD"
    },
    "feePayer": "APPLICATION",
    "feeAmount": {
      "number": "0",
      "unit": "TON"
    },
    "paymentLinks": [
      {
        "type": "TELEGRAM_BOT",
        "url": "https://t.me/SwapWalletBot?start=AI-366ec085-a206-40af-a37b-ff7c40ccbf52"
      },
      {
        "type": "TELEGRAM_WEBAPP",
        "url": "https://t.me/SwapWalletBot/app?startapp=AI-366ec085-a206-40af-a37b-ff7c40ccbf52"
      },
      {
        "type": "WEBSITE",
        "url": "https://swapwallet.app/payment?id=366ec085-a206-40af-a37b-ff7c40ccbf52"
      }
    ],
    "paidAt": null,
    "expiredAt": "2024-03-08T15:06:53.186197Z",
    "createdAt": "2024-03-06T13:06:53.186520Z"
  }
}

HTTP Request

GET https://swapwallet.app/api/v1/payment/{application-username}/invoice/{invoice-id}

ورودی

پارامتر نوع توضیحات نمونه
application-username string نام کاربری کسب و کار شما my_application_username
id string شناسه‌ی پرداخت 64ceb56e6fc9d9d195049a79

خروجی

پارامتر نوع توضیحات نمونه
id string شناسه‌ی پرداخت 64ceb56e6fc9d9d195049a79
supportCode string کد پیگیری سفارش AI-JK3PKDV-3E80
status string وضعیت پرداخت ACTIVE, SUCCESS, EXPIRED, CANCLED
externalId string [max: 255] در صورت وجود داشتن،‌شناسه‌ی یکتای پرداخت شما، این فیلد باعث میشود که جلوی ایجاد چند رسید برای یک سفارش گرفته شود 6CF313C7-53D9-43C1-B26F-D1911CBA726D
customData string [max: 512] دیتای اضافه مورد نیاز برای سیستم، میتوانید دیتای خود را با فرمت مورد نظر در رسید قرار دهید و در صورت نیاز در بازدید‌های بعدی از آن استفاده کنید 6CF313C7-53D9-43C1-B26F-D1911CBA726D
description string [max: 255] توضیح در مورد رسید، پیشهاد می‌شود این مقدار را متن مفهوم برای اوپراتور پر کنید، این متن در پنل رسید‌ها می‌تواند برای یافتن رسید استفاده شود، مثلا نام خریدار، شناسه یا شماره موبایل او، محصولی که خریداری کرده یا مواردی از این چنین میتواند مفید باشد 6CF313C7-53D9-43C1-B26F-D1911CBA726D
userLanguage Language در صورتی که کاربر زبان پیش‌فرض برای خود مشخص نکرده باشد، این زبان برای پنل کاربری پرداخت مورد استفاده قرار خواهد گرفت، اگر نمیدانید زبان کاربر شما چیست این فیلد را خالی بگذارید 6CF313C7-53D9-43C1-B26F-D1911CBA726D
returnUrl url در صورت وجود داشتن، در انتها کاربر به این لینک بازگرداده خواهد شد https://t.me/gamee?start=checkme-12345
amount money مقدار مورد نیاز برای پرداخت رسید، این مبلغ میتواند با مقدار مشخص شده توسط شما متفاوت باشد {"number": "100", "unit": "TON"}
value money ارزش دلاری رسید {"number": "270.5", "unit": "USD"}
feePayer string پرداخت کننده‌ی کارمزد، میتوانید پرداخت‌کننده را خودتان یا مشتریان مشخص کنید APPLICATION / USER
feeAmount money مقدار کارمزد مشخص شده، در صورتی که پرداخت‌کننده‌ی کارمزد خودتان باشید این مبلغ بعد از واریز از مبلغ اصلی کثر خواهد شد و در غیر این صورت موقع پرداخت به مبلغ اصلی اضافه خواهد شد و توسط کاربر پرداخت می‌شود {"number": "0", "unit": "TON"}
paymentLinks object لینک‌هایی پرداخت که می‌توانید برای کاربر ارسال کنید را مشخص میکند، در تلگرام پیشنهاد می‌شود از لینک دارکت استفاده کنید و در صورتی که وبسایت دارید از لینک وبسایت، تفاوت لینک‌ها را میتوانید در بات دمو مشاهده کنید {object}
paidAt datetime (ISO-8601) در صورت پرداخت شدن رسید، زمان پرداخت شدن رسید را مشخص میکند 2024-03-08T14:37:23.986097732Z / null
expiredAt datetime (ISO-8601) زمان منقضی شدن رسید را مشخص میکند 2024-03-08T14:37:23.986097732Z
createdAt datetime (ISO-8601) زمان ایجاد شدن رسید را مشخص میکند 2024-03-08T14:37:23.986097732Z

دریافت وضعیت آخرین سفارش‌ها

با استفاده از این API می‌توانید لیست تمامی سفارش‌های ایجاد شده توسط سرویس خود را دریافت کنید. این روش از قابلیت pagination پشتبانی می‌کند، با استفاده از دو مقدار limit و page می‌توانید تمامی سفارش‌ها را دریافت کنید. مقدار page از صفر شروع می‌شود.


curl 'https://swapwallet.app/api/v1/payment/swapmarket/invoice?page=0&limit=100'

در صورت فراخوانی درست، پاسخ به این صورت خواهد بود:

{
  "status": "OK",
  "result": {
    "page": 0,
    "perPage": 1,
    "totalItems": 14,
    "totalPages": 14,
    "data": [
      {
        "id": "366ec085-a206-40af-a37b-ff7c40ccbf52",
        "supportCode": "AI-7Y0OZQ4-MFJC",
        "status": "ACTIVE",
        "description": "PS5 Game | OverWatch3",
        "customData": "user-id=1000,order-id=12345 or {\"user-id\":12345,\"order-id\":12345}",
        "userLanguage": "EN",
        "returnUrl": "https://t.me/gamee?start=checkme-12345",
        "externalId": "your-unique-internal-inovice-id-2",
        "amount": {
          "number": "3.78",
          "unit": "TON"
        },
        "value": {
          "number": "10",
          "unit": "USD"
        },
        "feePayer": "APPLICATION",
        "feeAmount": {
          "number": "0",
          "unit": "TON"
        },
        "paymentLinks": [
          {
            "type": "TELEGRAM_BOT",
            "url": "https://t.me/SwapWalletBot?start=AI-366ec085-a206-40af-a37b-ff7c40ccbf52"
          },
          {
            "type": "TELEGRAM_WEBAPP",
            "url": "https://t.me/SwapWalletBot/app?startapp=AI-366ec085-a206-40af-a37b-ff7c40ccbf52"
          },
          {
            "type": "WEBSITE",
            "url": "https://swapwallet.app/payment?id=366ec085-a206-40af-a37b-ff7c40ccbf52"
          }
        ],
        "paidAt": null,
        "expiredAt": "2024-03-08T15:06:53.186197Z",
        "createdAt": "2024-03-06T13:06:53.186520Z"
      }
    ]
  }
}

HTTP Request

GET https://swapwallet.app/api/v1/payment/{application-username}/invoice?page={page}&limit={limit}

پارامتر نوع توضیحات نمونه
application-username string نام کاربری کسب و کار شما my_application_username
page int [0, ) شماره صفحه 0, 1, 2
limit int [1, 100] تعداد نتایج در هر صفحه 10, 100

وب‌‌هوک

با استفاده از وب‌هوک می‌توانید از آخرین‌ آپدیت‌ها و تغییرات در وضعیت سفارش‌ها مطلع شوید. در این روش دیگر نیاز به دریافت اطلاعات به صورت دوره‌ای یا استفاده از returnUrl نیست و فرایند سفارش نیز با سرعت بالا انجام خواهد شد

پیشنهاد می‌شود در زمان توسعه‌ی سرویس از سرویس https://webhook.site استفاده کنید

دقت کنید که برای دریافت وب‌هوک‌ها، باید آدرس وبهوک خود را در تنظیمات مربوط به کسب‌ و کار مشخص کرده باشید.

در صورت پرداخت موفق از طرف کاربر، یک درخواست مشابه دریافت خواهید کرد

{
  "requestId": "11c659b1-c89f-4409-8772-fb9b940a8d7b",
  "hmac": "88bb447b4a4a1b9a2c38a2ff88b25c169dce75d73d957be9fe37cf33b167c7d7",
  "event": {
    "time": "2024-03-05T18:30:18.925949Z",
    "type": "INVOICE",
    "invoice": {
      "id": "91d97577-ba7e-4826-9535-cbefd77b03e8",
      "supportCode": "AI-M6R2OLC-6ZOW",
      "status": "PAID",
      "description": "PS5 Game | OverWatch3",
      "customData": "your-unique-internal-inovice-id-2",
      "userLanguage": "EN",
      "returnUrl": "https://t.me/gamee?start=checkme-12345",
      "externalId": "your-unique-internal-inovice-id-2",
      "amount": {
        "number": "3.78",
        "unit": "TON"
      },
      "value": {
        "number": "10",
        "unit": "USD"
      },
      "feePayer": "APPLICATION",
      "feeAmount": {
        "number": "0",
        "unit": "TON"
      },
      "paymentLinks": [
        {
          "type": "TELEGRAM_BOT",
          "url": "https://t.me/SwapWalletBot?start=AI-366ec085-a206-40af-a37b-ff7c40ccbf52"
        },
        {
          "type": "TELEGRAM_WEBAPP",
          "url": "https://t.me/SwapWalletBot/app?startapp=AI-366ec085-a206-40af-a37b-ff7c40ccbf52"
        },
        {
          "type": "WEBSITE",
          "url": "https://swapwallet.app/payment?id=366ec085-a206-40af-a37b-ff7c40ccbf52"
        }
      ],
      "paidAt": "2024-03-05T16:59:11.984465Z",
      "expiredAt": "2024-03-05T17:00:02.210824Z",
      "createdAt": "2024-03-05T16:59:02.213808Z"
    }
  }
}

مشخصات وب‌هوک

خروجی

پارامتر نوع توضیحات نمونه
requestId string شناسه‌ی درخواست، این شناسه تنها برای دیباگ مورد استفاده قرار خواهد گرفت 11c659b1-c89f-4409-8772-fb9b940a8d7b
hmac string مشخص کننده‌ی hmac با استفاده از الگوریتم h256 و با استفاده از کلید api-key شماست 88bb447b4a...
id string شناسه‌ی پرداخت 64ceb56e6fc9d9d195049a79
supportCode string کد پیگیری سفارش AI-JK3PKDV-3E80
status string وضعیت پرداخت ACTIVE, SUCCESS, EXPIRED, CANCLED
externalId string [max: 255] در صورت وجود داشتن،‌شناسه‌ی یکتای پرداخت شما، این فیلد باعث میشود که جلوی ایجاد چند رسید برای یک سفارش گرفته شود 6CF313C7-53D9-43C1-B26F-D1911CBA726D
customData string [max: 512] دیتای اضافه مورد نیاز برای سیستم، میتوانید دیتای خود را با فرمت مورد نظر در رسید قرار دهید و در صورت نیاز در بازدید‌های بعدی از آن استفاده کنید 6CF313C7-53D9-43C1-B26F-D1911CBA726D
description string [max: 255] توضیح در مورد رسید، پیشهاد می‌شود این مقدار را متن مفهوم برای اوپراتور پر کنید، این متن در پنل رسید‌ها می‌تواند برای یافتن رسید استفاده شود، مثلا نام خریدار، شناسه یا شماره موبایل او، محصولی که خریداری کرده یا مواردی از این چنین میتواند مفید باشد 6CF313C7-53D9-43C1-B26F-D1911CBA726D
userLanguage Language در صورتی که کاربر زبان پیش‌فرض برای خود مشخص نکرده باشد، این زبان برای پنل کاربری پرداخت مورد استفاده قرار خواهد گرفت، اگر نمیدانید زبان کاربر شما چیست این فیلد را خالی بگذارید 6CF313C7-53D9-43C1-B26F-D1911CBA726D
returnUrl url در صورت وجود داشتن، در انتها کاربر به این لینک بازگرداده خواهد شد https://t.me/gamee?start=checkme-12345
amount money مقدار مورد نیاز برای پرداخت رسید، این مبلغ میتواند با مقدار مشخص شده توسط شما متفاوت باشد {"number": "100", "unit": "TON"}
value money ارزش دلاری رسید {"number": "270.5", "unit": "USD"}
feePayer string پرداخت کننده‌ی کارمزد، میتوانید پرداخت‌کننده را خودتان یا مشتریان مشخص کنید APPLICATION / USER
feeAmount money مقدار کارمزد مشخص شده، در صورتی که پرداخت‌کننده‌ی کارمزد خودتان باشید این مبلغ بعد از واریز از مبلغ اصلی کثر خواهد شد و در غیر این صورت موقع پرداخت به مبلغ اصلی اضافه خواهد شد و توسط کاربر پرداخت می‌شود {"number": "0", "unit": "TON"}
paymentLinks object لینک‌هایی پرداخت که می‌توانید برای کاربر ارسال کنید را مشخص میکند، در تلگرام پیشنهاد می‌شود از لینک دارکت استفاده کنید و در صورتی که وبسایت دارید از لینک وبسایت، تفاوت لینک‌ها را میتوانید در بات دمو مشاهده کنید {object}
paidAt datetime (ISO-8601) در صورت پرداخت شدن رسید، زمان پرداخت شدن رسید را مشخص میکند 2024-03-08T14:37:23.986097732Z / null
expiredAt datetime (ISO-8601) زمان منقضی شدن رسید را مشخص میکند 2024-03-08T14:37:23.986097732Z
createdAt datetime (ISO-8601) زمان ایجاد شدن رسید را مشخص میکند 2024-03-08T14:37:23.986097732Z
json