‏API درگاه › صورت‌حساب

تأیید مصرف

OpenAPI
POST/gateway-api/v1/invoices/{invoice_id}/consume

پرداخت را تأیید می‌کند: صورت‌حساب paid به success می‌رسد و consumed_at می‌گیرد. بعد از ثبت سفارش در سامانهٔ خودتان آن را بزنید. درخواست بدنه ندارد.

صورت‌حساب paid باید تا ۳۰ دقیقه پس از paid_at مصرف شود؛ بعد از آن 409 invoice_not_consumable می‌گیرید و رینگ‌پی مبلغ را به مشتری برمی‌گرداند.

POST /gateway-api/v1/invoices/{invoice_id}/consume
curl -X POST "$RINGPAY_BASE_URL/gateway-api/v1/invoices/86Rf07xd4z/consume" \
  -H "Authorization: Bearer $RINGPAY_API_KEY"
Response 200
{
  "already_consumed": false,
  "amount": "4900000",
  "consumed_at": "2026-11-07T09:06:00Z",
  "created_at": "2026-11-07T09:00:00Z",
  "external_id": "shop-1",
  "external_order_id": "order-1042",
  "id": "86Rf07xd4z",
  "merchant_id": "khb",
  "paid_at": "2026-11-07T09:05:00Z",
  "payer_mobile": "+989121234567",
  "payment_due_at": "2026-11-07T10:00:00Z",
  "status": "success"
}

پارامترها

  • invoice_idstringالزامی

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

پاسخ

موجودیت صورت‌حساب با status: "success" و فیلد اضافهٔ already_consumed. تکرار درخواست برای صورت‌حسابی که قبلاً مصرف شده امن است: همان 200 با already_consumed: true برمی‌گردد و چیزی تغییر نمی‌کند. هر وضعیت دیگری 409 invoice_not_consumable می‌گیرد.

خطاها

کدهای مشترک و رفتار هر کد در خطاها آمده.

  • invalid_access_key401

    کلید فرستاده نشده، نامعتبر است، منقضی شده یا باطل شده.

  • access_denied403

    کلید دسترسی این API را ندارد (gateway_access برای درگاه، merchant_access برای پذیرنده‌ها)، یا درخواست از IPی بیرون از فهرست مجاز کلید آمده.

  • invoice_not_found404

    صورت‌حساب نیست، مال پذیرندهٔ شبکهٔ دیگری است یا صورت‌حساب حضوری است.

  • invoice_not_consumable409

    صورت‌حساب paid نیست، یا ۳۰ دقیقهٔ تأیید مصرف گذشته.

  • internal_error500

    خطای رینگ‌پی. کمی بعد همان درخواست را تکرار کنید.

صفحه‌ها

endpointها