ایجاد فاکتور

اندپوینت

متد

POST

URL

https://crptox.com/api/v1/invoices

محیط

محیط درخواست به‌صورت خودکار بر اساس API Key مورد استفاده برای احراز هویت تعیین می‌شود.

Sandbox


                            crx_test_...

با API Key آزمایشی می‌توانید بدون استفاده از دارایی واقعی، روی شبکه‌های تست پشتیبانی‌شده فاکتور ایجاد کنید.

Live


                            crx_live_...

با API Key واقعی می‌توانید فاکتورهای عملیاتی را روی شبکه‌های اصلی پشتیبانی‌شده ایجاد کنید.

فیلدی با نام environment یا mode در بدنه درخواست ارسال نکنید. کلیدهای crx_test_ همیشه در Sandbox و کلیدهای crx_live_ همیشه در محیط Live اجرا می‌شوند.

انتخاب روش پرداخت

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

نمونه BASH

curl https://crptox.com/api/v1/payment-methods \
  -H "Authorization: Bearer YOUR_API_SECRET" \
  -H "Accept: application/json"

توصیه می‌شود به‌جای hard-code کردن شبکه‌ها و دارایی‌های پشتیبانی‌شده، از endpoint روش‌های پرداخت استفاده کنید.

بدنه درخواست

network

string الزامی

شبکه بلاکچینی که پرداخت این فاکتور باید روی آن انجام شود.


                                        tron


                                        ethereum

bsc


                                        polygon

شبکه انتخاب‌شده باید برای حساب مرچنت شما در محیط فعلی API Key در دسترس باشد.

asset

string الزامی

توکن یا دارایی قابل پرداخت برای این فاکتور.


                                        usdt


                                        usdc

دارایی انتخاب‌شده باید روی شبکه موردنظر فعال و برای حساب مرچنت شما قابل استفاده باشد.

amount

string الزامی

مبلغی که باید برای این فاکتور پرداخت شود.

برای حفظ دقت اعشاری، مقادیر مالی را به‌صورت string ارسال کنید.

description

string اختیاری

توضیح اختیاری برای فاکتور، مانند شماره سفارش یا شناسه مرجع مشتری.

expires_in

integer اختیاری

تعداد ثانیه‌هایی که پس از آن فاکتور منقضی می‌شود.

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

ترکیب‌های پشتیبانی‌شده شبکه و دارایی

مقادیر network و asset باید یک ترکیب پرداخت معتبر تشکیل دهند. ترکیب‌های زیر در حال حاضر پشتیبانی می‌شوند.

Network	Assets
`tron`	`usdt`
`ethereum`	`usdt` `usdc`
`bsc`	`usdt`
`polygon`	`usdt` `usdc`

USDT در هر چهار شبکه پشتیبانی می‌شود. USDC در حال حاضر فقط روی Ethereum و Polygon قابل استفاده است. برای دریافت روش‌های پرداخت در دسترس حساب خود، از Endpoint مربوط به Payment Methods استفاده کنید.

Idempotency

هنگام ایجاد فاکتور از هدر Idempotency-Key استفاده کنید تا در صورت تکرار درخواست، فاکتور تکراری به‌صورت ناخواسته ایجاد نشود.

HTTP Header TEXT

Idempotency-Key: unique-request-key

برای هر درخواست منطقی ایجاد فاکتور، یک Idempotency Key یکتا استفاده کنید. ارسال مجدد همان درخواست با همان کلید، نتیجه قبلی را برمی‌گرداند.

نمونه درخواست

درخواست BASH

curl -X POST https://crptox.com/api/v1/invoices \
  -H "Authorization: Bearer YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: order-1001" \
  -d '{
    "network": "bsc",
    "asset": "usdt",
    "amount": "10.000000",
    "description": "Order #1001",
    "expires_in": 1800
  }'

نمونه پاسخ

پاسخ JSON

{
  "invoice": {
    "uuid": "9f7c2c4a-0000-0000-0000-000000000000",
    "number": "INV-202610050001",
    "status": "pending",
    "amount": "10.000000",
    "asset": "usdt",
    "network": "bsc",
    "expires_at": "2026-10-05T20:30:00+00:00"
  },
  "payment": {
    "uuid": "1c4a0000-0000-0000-0000-000000000000",
    "address": "0xf6222331fe8cd2505561bce3dc4c5837d362b458",
    "amount": "10.000000",
    "asset": "usdt",
    "network": "bsc",
    "status": "pending",
    "expires_at": "2026-10-05T20:30:00+00:00"
  }
}

تست در Sandbox

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

1. از بخش Developer پنل مرچنت یک API Key آزمایشی ایجاد کنید.
2. در بخش Sandbox Wallets یک کیف پول فعال برای شبکه تست موردنظر اضافه کنید.
3. با API Key دارای پیشوند crx_test_ و یکی از روش‌های پرداخت موجود در Sandbox یک فاکتور ایجاد کنید.
4. مقدار موردنیاز از توکن تست را از یک کیف پول آزمایشی به آدرس پرداخت برگردانده‌شده توسط فاکتور ارسال کنید.
5. فاکتور را دوباره دریافت کنید و وضعیت پرداخت را تا رسیدن به وضعیت نهایی دنبال کنید.