POST/v1/cards/:id/close

إغلاق بطاقة

تغلق البطاقة نهائيًا وتعيد ما تبقى من رصيدها إلى محفظتك لدى هذا المتجر.

الصلاحية المطلوبة: cards.writeحد الطلبات: 10 rps

الإغلاق idempotent ويُخبر بنفسه: يوضح الرد مقدار ما أُعيد إلى رصيدك، ومقدار ما استوعبته المنصة كرسوم، وهل هذا الطلب مجرد إعادة لإغلاق سابق (already_refunded). أي إغلاق لا يُعرف مقدار ما يُردّ منه يُرفض بدلًا من أن تُخمَّن له قيمة.

المعطيات

idstringمطلوب

معرّف البطاقة.

Idempotency-Keystringمطلوب

مطلوبة، 8 أحرف على الأقل. تُردّ أموال البطاقة مرة واحدة في عمرها كله، والمفتاح هو ما يجعل إعادة المحاولة ترجع لك الاسترداد نفسه لا استردادًا ثانيًا.

أمثلة الكود

curl -X POST "https://samaprime.com/api/v1/cards/smsord_01J8X9AABBCCDD/close" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0e7f5c1e-2b3a-4f6d-9c8b-1a2b3c4d5e6f"

الاستجابة

→ 200
{
  "data": {
    "id": "cm_card_01J8Z1A2BBCCDD",
    "status": "closed",
    "credited_usd": "31.0100",
    "absorbed_fee_usd": "0.0000",
    "already_refunded": false
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-08-06T12:00:00Z"
  }
}

الأخطاء

الحالة	الرمز
404	`not_found` لا توجد بطاقة بهذا المعرّف تخصك لدى هذا المتجر.
409	`provider_error` رفض المُصدِر الإغلاق. البطاقة بقيت مفتوحة ولم يُرد شيء.
409	`refund_amount_unknown` أُغلقت البطاقة لدى المُصدِر لكن تعذّر قياس المبلغ الواجب إرجاعه، فلم يُضَف إلى رصيدك شيء ولم تُخمَّن صفر بدلًا منه. البطاقة مُغلقة والمبلغ معلّق؛ هذا يحتاج مراجعة الدعم، لا إعادة محاولة.
409	`close_refused` رُفض الإغلاق لسبب يمرّره هذا المسار بكلمته الأصلية. بقيت البطاقة مفتوحة ولم يُضَف إلى رصيدك شيء.
400	`idempotency_key_required` لا توجد ترويسة Idempotency-Key، أو أنها أقصر من 8 أحرف. الإغلاق يرد مالًا إلى محفظتك، فلن يعمل بلا مفتاح يجعل إعادة الطلب ترجع الاسترداد نفسه مرة واحدة.
403	`test_key_not_allowed` مفتاح الاختبار (sk_test_) لا يحرّك المال: عمليات البطاقات تحتاج مفتاحًا حيًا. لم يُحجز شيء ولم يُمسّ رصيد المحفظة.