مستندات API

آدرس پایه و احراز هویت

تمام درخواست‌ها به آدرس زیر می‌روند و توکن در هدر Authorization به صورت Bearer فرستاده می‌شود.

POST https://api.abangateway.ir/api/v1/invoices
Authorization: Bearer ag_live_xxxx…xxxx
Content-Type: application/json

توکن دو حالت دارد و پیشوندش حالت را نشان می‌دهد: ag_live_ برای واقعی و ag_test_ برای محیط آزمایش. بعد از پیشوند دقیقا ۴۸ کاراکتر میآید، و کلید کامل فقط همان لحظه ساخت در پنل نشان داده میشود. این دو کاملاً از هم جدا هستند — توکن آزمایشی هرگز نمی‌تواند فاکتور واقعی را بخواند و برعکس، و هر دو حالت ۴۰۴ می‌گیرند نه ۴۰۳. گفتن اینکه «این فاکتور هست ولی مال شما نیست» خودش افشای اطلاعات است.

کلید نماینده: فروشگاهی که نمایندگی درگاه دارد میتواند برای هر نماینده کلید جدا بسازد تا نماینده آن را در سایت خودش بگذارد. شکلش همین است (ag_live_ یا ag_test_) و همه مسیرهای این صفحه با آن کار میکنند، با این فرق ها: هر فاکتوری که با آن ساخته شود فروش همان نماینده است و فیلد agent لازم نیست؛ فقط فاکتورهای همان نماینده را میبیند و بقیه برایش ۴۰۴ است؛ order_id در فضای خود نماینده یکتاست، پس سفارش ۱۰۴۳ دو نماینده با هم قاطی نمیشود؛ و وبهوک فقط به callback_url همان فاکتور میرود و با کلید امضای خود نماینده امضا میشود. اگر نماینده یا نمایندگی فروشگاه خاموش شود، این کلید ۴۰۳ میگیرد.

بسته PHP و لاراول

اگر با PHP کار میکنید، بسته رسمی همه درخواست های این صفحه، چک امضای وبهوک و خطاهای کلاس بندی شده را آماده دارد. PHP 7.4 به بالا کافی است و در لاراول ۱۰ تا ۱۳ خودش ثبت میشود: تنظیمات، یک مسیر آماده برای وبهوک و رویداد پرداخت.

composer require abangateway/abangateway-php-package

use AbanGateway\Client;

$aban = new Client(getenv('ABANGATEWAY_KEY'));

$invoice = $aban->invoiceForOrder('ORD-1043', [
    'amount_toman' => 150000,
    'callback_url' => 'https://shop.example/aban/webhook',
]);

header('Location: ' . $invoice->paymentUrl);

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

بسته PHP آبان گیت ویراهنمای کامل، نمونه لاراول و جدول خطاها

ساخت فاکتور

{
  "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
}

استعلام وضعیت

تأیید — یک‌بار و فقط یک‌بار

این عمداً یک‌بارمصرف است. اولین فراخوانی موفق verified: true برمی‌گرداند و هر فراخوانی بعدی ۴۰۹ می‌دهد. همین یک قاعده است که اجازه می‌دهد بعد از تایم‌اوت با خیال راحت دوباره تلاش کنید، بدون اینکه سفارش دو بار تحویل داده شود.

{
  "verified": true,
  "invoice_id": "inv_a3f9k2m8p1q7r4s6",
  "order_id": "ORD-2291",
  "amount_rial": 150000000,
  "paid_at": "2026-08-01T14:32:11Z"
}

لغو

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

محیط آزمایش

با توکن آزمایشی می‌توانید کل چرخه را بدون کارت واقعی و بدون کارمزد اجرا کنید: فاکتور بسازید، پرداخت را شبیه‌سازی کنید، وب‌هوک بگیرید، verify کنید. با توکن واقعی این مسیر ۴۰۳ می‌دهد.

کدهای خطا

خطاها همیشه یک شکل دارند و code ماشین‌خوان است. روی message شرط نگذارید؛ متنش ممکن است عوض شود.

{
  "error": {
    "code": "insufficient_fee_wallet",
    "message": "موجودی کیف پول کارمزد کافی نیست."
  }
}

محدودیت نرخ

سقف درخواست روی کل فروشگاه است، نه روی هر کلید: همه کلیدهای آزمایشی و واقعی یک فروشگاه با هم یک سهم دارند، الان ۱۲۰ درخواست در دقیقه، و هر کلید نماینده سهم جدای خودش را دارد. اگر بیش از حد درخواست بفرستید ۴۲۹ میگیرید با کد rate_limited، همراه با error.details.retry_after_seconds و هدر Retry-After که میگویند چند ثانیه صبر کنید. با backoff نمایی دوباره تلاش کنید، نه در حلقه تنگ.