POST/v1/cards/:id/topup

شحن بطاقة

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

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

إذا كانت إجابة المزود غير حاسمة، يعود الرد بـ 202 مع pending:true ويُحتجز المبلغ للمطابقة — ولا يُغلق الطلب بوصفه فاشلًا، لأن بطاقة دُفع ثمنها لا يجوز إعلانها مرفوضة. أعد المحاولة بنفس Idempotency-Key لتقرأ النتيجة المستقرة.

المعطيات

idstringمطلوب

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

amount_usdstringمطلوب

المبلغ كنصّ بالدولار الأمريكي، حتى أربع خانات عشرية، أكبر من صفر وأقل من أو يساوي 100000.

Idempotency-Keystringمطلوب

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

أمثلة الكود

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

الاستجابة

→ 200
{
  "data": {
    "id": "cm_card_01J8Z1A2BBCCDD",
    "status": "active",
    "replayed": false
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-08-06T12:00:00Z"
  }
}

الأخطاء

الحالة	الرمز
400	`validation_failed` المتن غير صالح أو يحمل حقلًا غير متوقع.
400	`invalid_amount` amount_usd ليس مبلغًا مبسّطًا مثل "20.00" بخانتين عشريتين على الأكثر في القيمة. لا يُقرَّب شيء، ولم يُخصم من المحفظة شيء.
400	`idempotency_key_required` لا توجد ترويسة Idempotency-Key، أو أنها أقصر من 8 أحرف. شحن البطاقة يخصم من محفظتك قبل سؤال المُصدِر، لذا يرفض هذا المسار العمل بلا مفتاح.
403	`test_key_not_allowed` مفتاح الاختبار (sk_test_) لا يحرّك المال: عمليات البطاقات تحتاج مفتاحًا حيًا. لم يُحجز شيء ولم يُمسّ رصيد المحفظة.
409	`cards_unavailable` شحن البطاقات متوقف مؤقتًا: مزوّد البطاقات لا يستطيع الخدمة الآن (الإصدار موقوف، أو المزوّد في صيانة، أو رصيده معروف أنه نفد). رُفض الطلب قبل أي خصم: لم يُمسّ رصيد المحفظة ولا يوجد مبلغ معلّق. لم يُستهلك مفتاح Idempotency-Key هذا: أعد المحاولة لاحقًا بالمفتاح نفسه. (المفتاح الذي له جواب مسجّل، مثل شحن معلّق سابق، يعود بذلك الجواب.)
409	`card_frozen_at_provider` يُبلغ المُصدِر بأن هذه البطاقة مجمّدة، فلا يقبل شحنها. رُفض الطلب قبل الخصم من محفظتك.
409	`card_deleted_at_provider` لم تعد هذه البطاقة موجودة لدى المُصدِر. رُفض الطلب قبل الخصم، فلم يُخصم منك شيء ولم تُغلق البطاقة عندنا أيضًا.
409	`card_suspended_by_provider` أوقف المُصدِر هذه البطاقة، ولا يرفع إيقافها سواه. رُفض الطلب قبل الخصم، ولا يوجد إجراء فك تجميد تصلح أن تستدعيه لها.
409	`already_in_flight` هناك طلب شحن آخر لهذه البطاقة لم يُحسم بعد.
409	`topup_refused` رفض محرّك الشحن لسبب يمرّره هذا المسار بكلمته الأصلية. لم يتحرك أي مبلغ؛ اقرأ الرسالة لتعرف الكلمة المستخدمة.
422	`insufficient_balance` رصيد محفظتك لدى هذا المتجر لا يغطي المبلغ.
404	`not_found` لا توجد بطاقة بهذا المعرّف تخصك لدى هذا المتجر.