POST/v1/cards/issue

إصدار بطاقة

تنشئ بطاقة افتراضية وتشحنها في طلب واحد. يُخصم المبلغ من محفظتك لدى هذا المتجر، ولا تُنشأ البطاقة إلا بعد موافقة المُصدِر — والرفض يُرد تلقائيًا.

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

الطلب idempotent بالتصميم: أعد إرسال نفس Idempotency-Key فتحصل على النتيجة الأصلية بـ 200 دون خصم ثانٍ. تغيير المتن مع إعادة استخدام المفتاح يُرفض مباشرة بدلًا من إصدار بطاقة ثانية بصمت.

المعطيات

tierstringمطلوب

إما "basic" أو "plus". الفئة تحدد البرنامج والرسوم، لا شكل البطاقة.

countrystringمطلوب

رمز الدولة من حرفين لبرنامج البطاقة، مثل "US". مطلوب حرفان بالضبط.

load_usdstringمطلوب

المبلغ كنصّ بالنظام الدولي (مثال "50.00")، حتى أربع خانات عشرية، أكبر من صفر وأقل من أو يساوي 100000. رقم بدل نص يُرفض بوصف validation_failed عن قصد: الأرقام العشرية في JSON ليست طريقة انتقال المال هنا.

cardholder_namestringاختياري

اختياري: الاسم المطبوع على البطاقة، من 2 إلى 60 حرفًا.

Idempotency-Keystringمطلوب

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

أمثلة الكود

curl -X POST "https://samaprime.com/api/v1/cards/issue" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0e7f5c1e-2b3a-4f6d-9c8b-1a2b3c4d5e6f" \
  -d '{"tier":"example","country":"example","load_usd":"example","cardholder_name":"example"}'

الاستجابة

→ 201
{
  "data": {
    "id": "cm_card_01J8Z1A2BBCCDD",
    "last4": "1234",
    "status": "active"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-08-06T12:00:00Z"
  }
}

الأخطاء

الحالة	الرمز
400	`validation_failed` المتن غير صالح أو يحمل حقلًا لا يقبله هذا المسار — المخطط صارم، لذا لا يمكن اختيار المزود أو الـ BIN من هنا.
400	`invalid_amount` load_usd ليس مبلغًا مبسّطًا. يجب أن يكون نصًا مثل "20.00" بخانتين عشريتين على الأكثر في القيمة ("20.0000" مقبول، و"20.005" مرفوض)؛ أي رقم بدل نص، أو قيمة أدق من السنت، يُرفض قبل أن تُحسب أي تكلفة. لا يُقرَّب شيء.
400	`idempotency_key_required` لا توجد ترويسة Idempotency-Key، أو أنها أقصر من 8 أحرف. لم يُخصم شيء: إصدار البطاقة يخصم المال، لذا يرفض هذا المسار العمل من أصله بلا مفتاح تُقارَن به إعادة المحاولة.
403	`test_key_not_allowed` مفتاح الاختبار (sk_test_) لا يحرّك المال: عمليات البطاقات تحتاج مفتاحًا حيًا. لم يُحجز شيء ولم يُمسّ رصيد المحفظة.
403	`cards_not_enabled_for_store` إصدار البطاقات عبر الواجهة البرمجية غير مفعّل لهذا المتجر، ويفعّله مدير المنصة. لم يُخصم شيء، ولم يُستهلك مفتاح Idempotency-Key هذا: يمكن إرسال المفتاح نفسه بعد تفعيل الإصدار.
409	`cards_unavailable` إصدار البطاقات متوقف مؤقتًا: مزوّد البطاقات لا يستطيع الخدمة الآن (الإصدار موقوف، أو المزوّد في صيانة، أو رصيده معروف أنه نفد). رُفض الطلب قبل أي حجز أو خصم: لم يُمسّ رصيد المحفظة ولا يوجد طلب معلّق. لم يُستهلك مفتاح Idempotency-Key هذا: أعد المحاولة لاحقًا بالمفتاح نفسه.
400	`country_unavailable` لا يوجد برنامج بطاقة قابل للاختيار لهذه الدولة وهذه الفئة. هذا من إعدادات المنصة، وليس شيئًا تصلحه بتعديل المتن.
400	`no_provider` لا يوجد مزوّد مُعَدّ لهذه الفئة على المنصة من أصله، فلا يمكن شراء بطاقة منها. إعادة المحاولة لا تغيّر الجواب.
400	`below_minimum` المبلغ أقل من الحد الأدنى الذي تقبله هذه الفئة من البطاقات. ارفع load_usd.
400	`invalid_input` اجتاز الطلب تحقق المخطط ثم رفضه محرّك الإصدار: الفئة، أو الـ BIN الذي آل إليه الاختيار، أو المبلغ — غير قابل للاستخدام كما أُرسل.
400	`tier_unavailable` هذه الفئة من البطاقات غير متاحة حاليًا.
400	`bin_not_selectable` الـ BIN الذي اخترته المنصة لهذا الزوج معطّل أو غير معروف أو يخصّ مزوّدًا آخر. لا تُعِد إرسال الزوج نفسه؛ التصحيح مطلوب على جهة المنصة.
400	`provider_bin_unavailable` الـ BIN المختار غير متاح مؤقتًا لدى المُصدِر. قد ينجح زوجٌ من فئة ودولة ما لا ينجح هنا — ولم يُخصم منك شيء.
422	`insufficient_customer_balance` رصيد محفظتك لدى هذا المتجر لا يغطي المبلغ والرسوم. اشحن المحفظة ثم أعد الطلب؛ إعادة المحاولة على حالتها لا يمكن أن تنجح.
422	`provider_insufficient_funds` نفدت سيولة المنصة نفسها لدى المُصدِر. لم يُخصم منك شيء، ورفع هذه السيولة مسؤوليتنا نحن — فلا شيء لديك تعيد المحاولة من أجله.
500	`recording_failed` لا تُعِد المحاولة هنا. أنشأ المُصدِر البطاقة وفشل تسجيلها عندنا، فالمبلغ صُرف فعلًا والبطاقة محجوزة للمطابقة؛ والمحاولة الثانية تعني بطاقة ثانية.