هل تحتاج إلى إنشاء بطاقات افتراضية تلقائيًا للعملاء أو المشاريع أو حسابات الشركات؟ تتيح واجهة برمجة التطبيقات (API) من Buvei للمطورين دمج إصدار البطاقات الافتراضية في تطبيقاتهم الخاصة، مما يقلل العمل اليدوي ويسهّل توسيع نطاق إنشاء البطاقات.
يشرح هذا الدليل العملية كاملة، بدءًا من إعداد حسابك واختيار BIN للبطاقة، وصولًا إلى إصدار بطاقة افتراضية والتأكد من أنها أصبحت جاهزة للاستخدام.
ما الذي تحتاج إليه قبل إصدار بطاقة افتراضية؟
قبل البدء، تأكد من توفر ما يلي:
- حساب Buvei مع تفعيل إمكانية الوصول إلى API
- مفتاح API وAPI Secret
- عنوان IP ثابت للاتصالات الصادرة ومعتمد للوصول إلى API
- نقطة نهاية HTTPS لاستقبال إشعارات Webhook
- رصيد كافٍ في المحفظة لإصدار البطاقة المطلوبة
إذا كنت جديدًا على Buvei، فسجّل حسابًا وتعرّف على لوحة التحكم الخاصة بإدارة البطاقات قبل بدء عملية التكامل.
الخطوة 1: سجّل في Buvei وأضف أموالًا إلى محفظتك
إنشاء حساب Buvei
انتقل إلى Buvei.com، وأنشئ حسابًا، وأكّد عنوان بريدك الإلكتروني، ثم سجّل الدخول إلى لوحة التحكم.
تأكد من أن إمكانية الوصول إلى API متاحة لحسابك قبل المتابعة.
شحن محفظتك
افتح قسم Wallet واختر طريقة تمويل يدعمها حسابك. إذا كانت هذه الإمكانية متاحة، يمكنك إيداع USDT عبر شبكة TRC20 أو ERC20.
انسخ عنوان الإيداع، وتأكد من تطابق شبكة التحويل مع الشبكة المحددة، ثم انتظر وصول الأموال. تحقق من رصيدك المتاح قبل إصدار البطاقة.
تأكد من أن رصيد محفظتك يغطي مبلغ التمويل الأولي للبطاقة وأي رسوم مطبقة.
الخطوة 2: احصل على بيانات اعتماد API واضبط إعدادات الوصول
احصل على API Key وAPI Secret من قسم إعدادات API في حسابك على Buvei.
يُستخدم API Key للتعرّف على مشروعك، بينما يُستخدم API Secret لتوقيع الطلبات. حافظ على سرية API Secret، ولا تكشف عنه مطلقًا في كود الواجهة الأمامية أو المستودعات العامة.
بعد ذلك، قدّم عنوان IP الثابت للاتصالات الصادرة الذي يستخدمه تطبيقك للاتصال بـ Buvei، حتى تتم إضافته إلى قائمة العناوين المسموح بها. قد تُرفض الطلبات الواردة من عناوين IP غير المعتمدة.
ستحتاج أيضًا إلى نقطة نهاية HTTPS لاستقبال إشعارات Webhook. تتيح هذه الإشعارات لتطبيقك الاستجابة عند اكتمال إنشاء البطاقة.
الخطوة 3: صادِق على طلباتك واسترجع أرقام BIN المتاحة
قبل طلب إصدار بطاقة افتراضية، تأكد من ضبط المصادقة عبر API بشكل صحيح.
يجب أن يتضمن كل طلب بيانات اعتماد API الخاصة بك، وطابعًا زمنيًا، وقيمة nonce فريدة، وتوقيعًا صالحًا. قد يؤدي غياب معلومات المصادقة أو عدم صحتها إلى رفض الطلب، لذا تحقق من هذه التفاصيل قبل متابعة إصدار البطاقة.
العثور على BIN متاح للبطاقة
قبل إصدار البطاقة، تحقق من أرقام BIN المتاحة لمشروعك. راجع شبكة الدفع الخاصة بكل خيار، وبلد الإصدار، والعملة، وأي متطلبات إضافية خاصة بحامل البطاقة، ثم اختر الخيار الأنسب.
يحدد BIN خصائص مهمة للبطاقة، بما في ذلك شبكة الدفع، وبلد الإصدار، والعملة. كما توضح المعلومات المتاحة ما إذا كانت هناك حاجة إلى تفاصيل إضافية، مثل رقم الهاتف المحمول أو عنوان البريد الإلكتروني أو PIN أو عنوان الفوترة أو التحقق من هوية حامل البطاقة.
اختر BIN يتناسب مع الغرض الذي تريد استخدام البطاقة من أجله، واحتفظ بمعرّفه لاستخدامه في طلب الإصدار.
تحقق من متطلبات BIN الذي اخترته قبل المتابعة. قد تختلف متطلبات التحقق من BIN إلى آخر، كما تتحدد عملة البطاقة بناءً على BIN المحدد.
الخطوة 4: تحقق من متطلبات حامل البطاقة
قبل إرسال طلب إصدار البطاقة، راجع متطلبات BIN الذي اخترته.
تتطلب بعض أرقام BIN التحقق من هوية حامل البطاقة، بينما قد تتطلب أرقام أخرى بيانات اتصال محددة أو معلومات الفوترة. إذا كانت إجراءات KYC مطلوبة، فأكمل عملية التحقق المعمول بها وتأكد من الموافقة على حامل البطاقة.
بحسب BIN، قد تحتاج أيضًا إلى تقديم رقم هاتف محمول أو عنوان بريد إلكتروني أو PIN أو عنوان فوترة.
يساعدك إعداد هذه التفاصيل مسبقًا على تجنب حالات فشل الطلبات التي يمكن تفاديها. لا تفترض أن جميع البطاقات الافتراضية تخضع للمتطلبات نفسها.
الخطوة 5: أصدر بطاقة افتراضية عبر API من Buvei
بعد اختيار BIN مناسب وتجهيز المعلومات المطلوبة، يمكنك البدء في إصدار البطاقة. تأكد من استكمال جميع بيانات حامل البطاقة المطلوبة وتوفر رصيد كافٍ في محفظتك قبل إرسال الطلب.
يجب أن يتضمن الطلب BIN المحدد للبطاقة، ومبلغ التمويل الأولي، وبيانات حامل البطاقة المطلوبة. وقد تكون هناك حاجة إلى معلومات إضافية بحسب BIN. إذا كان التحقق من حامل البطاقة مطلوبًا، فتأكد من الموافقة على حامل البطاقة المعني قبل المتابعة.
تحقق من مبلغ التمويل الأولي
يجب إرسال مبلغ التمويل الأولي بأصغر وحدة للعملة. على سبيل المثال، تمثل القيمة 10,000 مبلغ 100.00 دولار أمريكي.
يتراوح النطاق الموثق بين 1.00 دولار أمريكي و40,000.00 دولار أمريكي. وقد تعتمد الخيارات المتاحة أيضًا على حسابك وBIN المحدد، لذا تحقق من المتطلبات المعمول بها قبل إرسال الطلب.
بعد الإرسال، تُرجع API معرّف البطاقة وحالتها الأولية. تتم عملية إنشاء البطاقة بشكل غير متزامن، لذا فإن نجاح الطلب لا يعني بالضرورة أن البطاقة أصبحت جاهزة للاستخدام.
تجنب تكرار إصدار البطاقات
إذا انتهت مهلة الطلب، فلا ترسل فورًا طلب إصدار جديدًا بالكامل.
عند توفر الدعم، يساعد مفتاح Idempotency على تحديد عملية الإصدار نفسها عند إعادة المحاولة، ويقلل خطر إنشاء بطاقات مكررة. أعد استخدام المفتاح نفسه للطلب نفسه، مع الالتزام بمتطلبات المصادقة الخاصة بـ Buvei.
إذا أعاد الطلب استجابة تفيد بوجود تعارض، فتحقق مما إذا كانت العملية الأصلية قد عولجت قبل إعادة المحاولة.
الخطوة 6: أكّد إنشاء البطاقة باستخدام Webhook
بعد إرسال طلب الإصدار، انتظر إشعار Webhook من Buvei الذي يحمل الرمز CARD_CREATED.
قد تظل البطاقة المطلوبة حديثًا في البداية بحالة انتظار الإنشاء أثناء تنفيذ عملية تجهيزها. وبمجرد أن ترسل Buvei حدث CARD_CREATED، تكون عملية التجهيز قد اكتملت.
ينبغي لتطبيقك التحقق من توقيع Webhook، والتأكد من نوع الحدث، وتحديد البطاقة المعنية، وتحديث سجلاته الداخلية. كما يجب أن يكون قادرًا على التعامل مع الإشعارات المكررة وحالات فشل التسليم المؤقتة.
بعد استلام الإشعار، تحقق من الحالة الحالية للبطاقة عبر خدمة تفاصيل البطاقة لدى Buvei، وتأكد من أنها مفعّلة قبل اعتبارها جاهزة للاستخدام.
الخطوة 7: استكشاف أخطاء API الشائعة في Buvei وإصلاحها
إذا فشلت عملية إصدار البطاقة، فتحقق من رسالة الخطأ التي تم إرجاعها وراجع المشكلات الشائعة التالية.
| المشكلة | ما الذي يجب التحقق منه |
|---|---|
| طلب غير صالح | المعلومات المطلوبة، ومتطلبات BIN، ومبلغ التمويل، وعنوان الفوترة |
| فشل المصادقة | بيانات اعتماد API، والطابع الزمني، وnonce، وتوقيع الطلب |
| تم رفض الوصول | قائمة عناوين IP المسموح بها وأذونات الحساب |
| تعارض الطلب | إعادة استخدام nonce أو استخدام مفتاح Idempotency مرتبط بتفاصيل طلب مختلفة |
| تجاوز الحد المسموح للطلبات | حدود استخدام API وتوقيت إعادة المحاولة |
| تأخر إنشاء البطاقة | تسليم Webhook والحالة الحالية للبطاقة |
إذا كان الطلب غير صالح، فراجع المعلومات المطلوبة وتفاصيل الخطأ لتحديد ما يحتاج إلى تصحيح. أما إذا كانت المشكلة متعلقة بالمصادقة أو الوصول، فتحقق من آلية توقيع الطلبات والطابع الزمني وإعدادات IP وأذونات الحساب.
إذا انتهت مهلة الطلب أو أعاد استجابة تفيد بوجود تعارض، فتأكد مما إذا كان طلب الإصدار الأصلي قد عولج قبل إرسال طلب آخر. يساعد ذلك على منع إنشاء بطاقات مكررة.
إذا بدا أن إنشاء البطاقة متأخر، فتحقق مما إذا كان إشعار Webhook قد وصل، وراجع الحالة الحالية للبطاقة. لا يعني تأخر الإشعار وحده أن عملية الإصدار قد فشلت.
الخاتمة
تتيح API من Buvei دمج إصدار البطاقات الافتراضية مباشرةً في سير العمل التجاري الحالي. ومن خلال اختيار BIN المناسب، وتجهيز المعلومات المطلوبة عن حامل البطاقة، والتحقق من الحالة النهائية لكل بطاقة، يستطيع المطورون جعل عملية الإصدار أكثر اتساقًا وأسهل في الإدارة.
وبمجرد إعداد التكامل بشكل صحيح، يمكن أن يساعد إنشاء البطاقات تلقائيًا وإشعارات Webhook الفرق على إدارة الاحتياجات المتزايدة للبطاقات مع تقليل العمل اليدوي.
