POST/v1/cards/:id/freeze

تجميد بطاقة

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

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

المعطيات

idstringمطلوب

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

Idempotency-Keystringمطلوب

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

أمثلة الكود

curl -X POST "https://samaprime.com/api/v1/cards/smsord_01J8X9AABBCCDD/freeze" \
  -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": "frozen"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-08-06T12:00:00Z"
  }
}

الأخطاء

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