مستندات API
ساخت فاکتور، استعلام وضعیت، تأیید یکبارمصرف و لغو. با تمام پارامترها، کدهای خطا و نمونه در چهار زبان.
آدرس پایه و احراز هویت
تمام درخواستها به آدرس زیر میروند و توکن در هدر Authorization بهصورت Bearer فرستاده میشود.
POST https://abangateway.ir/api/v1/invoices
Authorization: Bearer live_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/jsonتوکن دو حالت دارد و پیشوندش حالت را نشان میدهد: live_ برای واقعی و test_ برای محیط آزمایش. این دو کاملاً از هم جدا هستند — توکن آزمایشی هرگز نمیتواند فاکتور واقعی را بخواند و برعکس، و هر دو حالت ۴۰۴ میگیرند نه ۴۰۳. گفتن اینکه «این فاکتور هست ولی مال شما نیست» خودش افشای اطلاعات است.
ساخت فاکتور
POST/api/v1/invoices
یک فاکتور میسازد و لینک صفحهی پرداخت را برمیگرداند.
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
| amount_rial | integer | بله | مبلغ به ریال، بزرگتر از صفر |
| order_id | string | خیر | شناسهی سفارش خودتان، حداکثر ۱۲۸ کاراکتر |
| callback_url | string | خیر | آدرس دریافت وبهوک. اگر ندهید، آدرس پیشفرض حسابتان استفاده میشود |
| description | string | خیر | توضیح فاکتور، حداکثر ۱۰۰۰ کاراکتر |
| metadata | object | خیر | هرچه میخواهید؛ عیناً در وبهوک برمیگردد |
| expiry_minutes | integer | خیر | مهلت پرداخت، بین ۱ تا ۱۴۴۰ دقیقه. پیشفرض از تنظیمات حساب |
{
"invoice_id": "inv_a3f9k2m8p1q7r4s6",
"status": "pending",
"amount_rial": 150000000,
"payable_rial": 150000010,
"payable_toman": 15000001,
"fee_rial": 40000,
"order_id": "ORD-2291",
"card_number": "6037991234567890",
"card_holder": "سارا رضایی",
"card_last4": "7890",
"iban": "IR620540102680020817909002",
"payment_url": "https://abangateway.ir/pay/inv_a3f9k2m8p1q7r4s6",
"expires_at": "2026-08-01T15:30:00Z",
"paid_at": null,
"is_test": false
}استعلام وضعیت
GET/api/v1/invoices/{invoice_id}
وضعیت فعلی فاکتور را برمیگرداند. هر تعداد بار قابل فراخوانی است.
| وضعیت | معنی |
|---|---|
| pending | ساخته شده، هنوز پرداخت نشده |
| partially_paid | فاکتور چندتکه، بعضی تکهها پرداخت شده |
| paid | کامل پرداخت شده |
| expired | مهلت تمام شد |
| cancelled | لغو شده |
تأیید — یکبار و فقط یکبار
POST/api/v1/invoices/{invoice_id}/verify
پرداخت را تأیید و مصرف میکند. تنها اولین فراخوانی موفق است.
این عمداً یکبارمصرف است. اولین فراخوانی موفق verified: true برمیگرداند و هر فراخوانی بعدی ۴۰۹ میدهد. همین یک قاعده است که اجازه میدهد بعد از تایماوت با خیال راحت دوباره تلاش کنید، بدون اینکه سفارش دو بار تحویل داده شود.
{
"verified": true,
"invoice_id": "inv_a3f9k2m8p1q7r4s6",
"order_id": "ORD-2291",
"amount_rial": 150000000,
"paid_at": "2026-08-01T14:32:11Z"
}لغو
POST/api/v1/invoices/{invoice_id}/cancel
فاکتور پرداختنشده را لغو میکند و کارمزد رزروشده را آزاد میکند.
فاکتور پرداختشده لغو نمیشود و ۴۰۹ میگیرید. اگر واریزی بعد از لغو برسد، به صف بررسی دستی شما میرود و گم نمیشود.
محیط آزمایش
POST/api/v1/invoices/{invoice_id}/simulate-payment
فقط با توکن test_ — پرداخت را شبیهسازی میکند.
با توکن آزمایشی میتوانید کل چرخه را بدون کارت واقعی و بدون کارمزد اجرا کنید: فاکتور بسازید، پرداخت را شبیهسازی کنید، وبهوک بگیرید، verify کنید. با توکن واقعی این مسیر ۴۰۳ میدهد.
کدهای خطا
خطاها همیشه یک شکل دارند و code ماشینخوان است. روی message شرط نگذارید؛ متنش ممکن است عوض شود.
{
"error": {
"code": "insufficient_fee_wallet",
"message": "موجودی کیف پول کارمزد کافی نیست."
}
}| HTTP | code | چه شده |
|---|---|---|
| ۴۰۲ | not_yet_paid | هنوز واریزی برای این فاکتور تشخیص داده نشده |
| ۴۰۲ | insufficient_fee_wallet | کیف پول کارمزد خالی است؛ فاکتور جدید ساخته نمیشود |
| ۴۰۳ | sandbox_only | این مسیر فقط با توکن آزمایشی کار میکند |
| ۴۰۴ | invoice_not_found | فاکتور وجود ندارد یا مال این توکن نیست |
| ۴۰۹ | already_verified | قبلاً تأیید شده — دوباره تحویل ندهید |
| ۴۰۹ | invoice_not_payable | وضعیت فاکتور اجازهی این کار را نمیدهد |
| ۴۰۹ | no_card_registered | هیچ کارت فعالی روی حساب ثبت نشده |
| ۴۱۰ | invoice_expired | مهلت پرداخت تمام شده |
| ۴۲۲ | amount_not_allowed | مبلغ خارج از حد مجاز است |
| ۴۲۲ | unsafe_callback_url | آدرس بازگشت پذیرفته نشد |
| ۵۰۳ | capacity_full | ظرفیت همزمان روی این کارت پر است؛ کمی بعد دوباره تلاش کنید |
محدودیت نرخ
اگر بیش از حد درخواست بفرستید ۴۲۹ میگیرید، همراه با details.retry_after_seconds که میگوید چقدر صبر کنید. با backoff نمایی دوباره تلاش کنید، نه در حلقهی تنگ.