بنية تحتية لإصدار البطاقات
واجهة API للبطاقات الافتراضية — أصدر بطاقات Visa و Mastercard لعملائك.
تُصدر ScarabPay Business بطاقات افتراضية لعملائك، مموّلة من محفظة تاجر تشحنها أنت. كل حركة تُسجَّل بقيود مزدوجة متوازنة في دفتر لا يقبل إلا الإضافة، فتكون الأرقام التي تُبلّغ عنها هي نفسها الصفوف التي نحتفظ بها.
// Idempotency-Key: 8f3c1d90-...-b7a2
{
"product_id": "01HXYZP4K2M8N6Q1RSTVWXYZ01",
"customer_id": "01HABCD7F3G9J5K2LMNPQRSTVW",
"amount_minor": 250000
}Ledger · insert only
٠١
مسار المال
كيف تعمل واجهة API للبطاقات الافتراضية.
التمويل أولًا لأنه لا بد أن يكون كذلك: طلب إصدار على محفظة غير مموّلة يُرفض ولا يُدرج في طابور. وليست الخطوات أدناه مراحل في رسم تسويقي — كل واحدة منها نقطة نهاية تستدعيها أو حدث تستقبله.
-
موِّل المحفظة
تحتفظ محفظة التاجر برصيد واحد لكل عملة بوحدات صغرى صحيحة. تصل الإيداعات المشفّرة إلى عناوين دائمة لكل شبكة، وتُضاف إلى المحفظة بمجرد تأكيد الشبكة لها.
POST /deposit-addresses
-
أصدِر بطاقة لعميل
طلب واحد يحمل منتجًا وعميلًا مسجّلًا ومبلغ شحن أوّلي. يُحجز المبلغ ورسوم إصدار المنتج على المحفظة، ويُستدعى شريك الإصدار خارج معاملة قاعدة البيانات، ثم تُسجّل التسوية الحركة في الدفتر. البطاقات التي تُهيَّأ لا تزامنيًّا تُعيد 202 ببطاقة معلّقة.
POST /cards
-
استقبل النشاط لحظة وقوعه
تصلك التفويضات وتغيّرات دورة الحياة كأحداث ويب‑هوك موقّعة — إصدار، تفويض، إعادة شحن، تجميد، إلغاء تجميد، إنهاء. والنشاط نفسه قابل للقراءة لكل بطاقة على حدة، بترقيم بالمؤشر.
GET /cards/{card}/transactions
-
سوِّ الحسابات على الصفوف لا على المجاميع
التسوية هي قراءة الدفتر مرة أخرى. لا شيء يُحدَّث ولا شيء يُحذف، فيظل الرقم الذي أبلغت عنه في ربع سابق قابلًا للإرجاع إلى القيود التي أنتجته.
GET /deposits
٠٢
شركاء الإصدار
واجهة واحدة لإصدار البطاقات الافتراضية أمام عدة جهات إصدار.
تتكامل مرة واحدة. وخلف ذلك التكامل يُوجَّه كل منتج بطاقات إلى شريك إصدار مرخّص يُختار بحسب منطقته ومجموعة منتجاته. إضافة شريك أو استبداله عملية ترحيل لدينا لا لديك — فالطلب الذي ترسله لا يتغيّر.
هويّات الشركاء غير منشورة، ولا يُكشف اسم أي شريك عبر الواجهة البرمجية ولا في أي استجابة تصلك.
٠٣
المطوّرون
التكامل مع واجهة البطاقات الافتراضية، مصمَّم لإعادة المحاولة.
تُقاس الواجهة المالية بما يحدث في المحاولة الثانية. كل نقطة نهاية تُعدّل البيانات تشترط مفتاح تكرار، والمفتاح نفسه ينتقل إلى جهة الإصدار كمرجع للعميل، وإعادة الإرسال تنتهي إلى النتيجة الأصلية لا إلى حركة ثانية.
{
"data": {
"id": "01HKQW2N8V4X6Z9B3D5F7HJKMN",
"status": "active",
"masked_number": "••••••••••••4417",
"balance_minor": 250000,
"currency": "USD"
}
}Delivered to your endpoint
Every delivery carries a timestamped HMAC signature you verify with your endpoint secret.
REST وJSON، وغلاف واحد
أغلفة متوقّعة للنجاح والمعالجة والخطأ. المعرّفات العامة من نوع ULID، ولا تغادر المعرّفات التسلسلية الداخلية النظام أبدًا.
التكرار شرط لا خيار
يُرفض أي طلب يُعدّل البيانات بلا مفتاح تكرار. ويُرفض كذلك إعادة استخدام مفتاح مع حمولة مختلفة، بدل قبوله بصمت.
ويب‑هوك موقّعة ومعاد إرسالها
تُسلَّم أحداث البطاقات والتمويل بتوقيع HMAC على الوقت والمحتوى، ويُعاد إرسالها عند الإخفاق.
وحدات صغرى صحيحة من طرف إلى طرف
لا وجود لأي قيمة عشرية عائمة في مسار المال — لا في طلب ولا في استجابة ولا في صف من صفوف الدفتر.
٠٤
ما هو قائم اليوم
ميزات واجهة البطاقات الافتراضية: أربع عشرة عملية، ولا وعود مستقبلية.
أربع عشرة عملية موثّقة عبر أحد عشر مسارًا، تغطّي الإصدار وسجلّ حاملي البطاقات والتمويل. وما ليس في هذه القائمة ليس شيئًا يمكنك استدعاؤه.
| Cards | |
|---|---|
| POST /cards | Issues a card against a product, to a registry customer, with an initial load. Charges the load plus the product issue fee through hold → provider → settle. Returns 202 with a pending card when the issuer provisions asynchronously. |
| GET /cards/{card} | Returns the card's current state. Poll it while a new card provisions — pending resolves to active. |
| POST /cards/{card}/recharge | Loads more funds onto a live card from the wallet, as a new balanced movement. |
| POST /cards/{card}/freeze | Blocks spend on a card without moving money. Reversed by /unfreeze. |
| POST /cards/{card}/terminate | Ends a card permanently and returns its residual balance to the wallet. |
| GET /cards/{card}/transactions | Provider-reported activity for one card, cursor-paginated. |
| Cardholders | |
| POST /customers | Registers a cardholder identity once. Stored encrypted at rest and submitted to the issuer inside an issue request. |
| GET /customers/{customer} | Reads a registry customer. PAN and security code are never exposed and never persisted. |
| Funding | |
| POST /deposit-addresses | Creates a permanent per-network address that credits the merchant wallet on receipt. |
| GET /deposits | Received deposits, reconciled against the ledger. |
Unfreeze, list customers, update a customer and list deposit addresses complete the fourteen.
كل حركة تنتهي إلى قيود مجموعها صفر.
التفويض لا يُعدّل رصيدًا. بل يضع حجزًا على محفظة التاجر، ويستدعي المُصدر خارج معاملة قاعدة البيانات، ثم يسجّل الحركة كقيدين متساويين متعاكسين في دفتر لا يقبل إلا الإضافة. والتصحيحات تُسجَّل كقيود جديدة، لا كتعديلات.
الدفتر هو مصدر الحقيقة لكل رقم تعرضه المنصة، بما في ذلك الأرقام في لوحة التاجر نفسه.
Card number ending 4417
- Cardholder
- A. HADDAD
- Expires
- 04/29
Ledger excerpt · demonstration data
٠٥
شكل العمل
بطاقات افتراضية لشركات التقنية المالية والأعمال.
لا يوجد في هذه الواجهة حقل حدّ إنفاق، ولا قاعدة لفئات التجّار، ولا مفتاح قناة، والبناء حول واحد منها بناء حول شيء غير موجود. ما تتحكّم فيه هو مقدار تمويل البطاقة — يُحدَّد عند الإصدار، ويتغيّر بإعادة الشحن، ويُسترد عند الإنهاء. وتتفرّع عن ذلك ثلاثة أنماط.
01
بطاقة لكل عميل
تحتفظ منصّتك بمحفظة واحدة، ويحمل كل عميل نهائي بطاقة مموّلة منها. حدّ انكشافه هو الرصيد الذي شحنته، وهويّته سجلّ في سجل حاملي البطاقات لا حمولة تعيد إرسالها.
02
مدفوعات تُصدَر كبطاقات
ادفع لبائع أو متعاقد بإصدار بطاقة تحمل المبلغ المستحق. أضف إليها بإعادة شحن، وأنهِها عند انتهاء التعامل — فيعود المتبقي إلى محفظتك كحركة متوازنة.
03
بطاقة لكل مورّد
أصدِر بطاقة منفصلة لكل مورّد أو اشتراك وموّلها بما تساويه تلك العلاقة. الإنفاق فوق المبلغ المشحون لا يُفوَّض، ونشاط كل بطاقة قابل للقراءة على حدة.
الأسئلة الشائعة
ما هي واجهة API للبطاقات الافتراضية؟
هي واجهة REST تستدعيها منصتك لإصدار بطاقات Visa و Mastercard افتراضية لعملائك، وشحنها بالأموال، وإدارتها — تجميد وإلغاء تجميد وشحن وإنهاء — دون أن تبني نظام إصدار البطاقات بنفسك.
كيف تُموَّل البطاقات؟
لكل تاجر محفظة بالدولار. تموّلها بإيداع عملات مستقرة إلى عناوين دائمة لكل شبكة، وتُضاف بعد تأكيد الشبكة. يُخصم الشحن الأولي للبطاقة ورسوم إصدارها من هذه المحفظة.
كيف أتحكم بما يمكن للبطاقة صرفه؟
عبر رصيدها. تحدد المبلغ عند إصدار البطاقة، وتزيده بالشحن، وتوقف الصرف بالتجميد، وتنهي البطاقة لإعادة الرصيد المتبقي إلى محفظتك.
كيف أعرف ما يحدث على البطاقة؟
تصل أحداث البطاقات والتمويل إلى نقطة الاستقبال لديك كإشعارات webhook موقّعة بـ HMAC-SHA256، وتُعاد عند الفشل. ويمكن قراءة النشاط نفسه لكل بطاقة عبر API.
هل ScarabPay بنك؟
لا. لسنا بنكًا ولا نملك ترخيصًا مصرفيًا. تُصدر البطاقات عبر شركاء إصدار مرخّصين.
كيف أبدأ؟
تواصل معنا لطلب الوصول. يتم التحقق من نشاطك التجاري قبل الاستخدام الفعلي، وتتيح لك مفاتيح API التجريبية التكامل بأموال تجريبية في الأثناء.
كل ما في هذه الصفحة يعود إلى عملية في الواجهة.
اطّلع على ما تفعله الواجهة، أو اكتب إلينا بما تبنيه ونخبرك بصراحة إن كان يناسبك.