Tovanix
Tovanix

API البطاقات الافتراضية

أصدر بطاقات Visa / Mastercard الافتراضية وأدرها جماعيًا عبر API، بتمويل USDT، لفوترة الاشتراكات والإنفاق الإعلاني والمشتريات عبر الحدود، وفق سياسات الخدمات.

  • الاستعلام عن BIN: الأرقام المتاحة والمناطق المدعومة ونطاقات الحدود
  • الإصدار وشحن الرصيد: إنشاء بطاقات برقم BIN تختاره وشحنها عند الحاجة
  • إدارة البطاقات: التجميد وإلغاء التجميد والإغلاق وجلب بيانات البطاقة بأمان
  • المعاملات وWebhook: سجل لكل معاملة وأحداث تفويض وتسوية فورية

نظرة عامة

تتيح واجهة API المفتوحة للبطاقات الافتراضية فتح البطاقات وسرد أرقام BIN وقراءة تفاصيل البطاقة وجلب رموز 3DS OTP والاستعلام عن المعاملات والشحن والإلغاء — إضافةً إلى قراءة رصيد حسابك بالدولار والحصول على عنوان إيداع TRON ثابت مخصص. تعيد جميع نقاط النهاية بنية JSON موحّدة (code/message/data، و code=0 يعني النجاح).

العنوان الأساسي بوابتك، أصل هذا الموقع. بادئة البطاقة /api/v1/vcard والحساب /api/v1/account.

جميع المبالغ بالدولار الأمريكي USD؛ يُخصم فتح البطاقة والشحن من رصيدك بالدولار على المنصة (الدفع من الرصيد فقط). عند عدم كفاية الرصيد يُعاد خطأ.

المصادقة والتوقيع

تقبل القراءة، BIN والقوائم والمعاملات والطلبات والرصيد والعنوان، المفتاحين المباشرين. تتطلّب الأموال والبيانات الحسّاسة أيضًا HMAC والوقت وnonce: الإصدار والشحن والإلغاء والاسترجاع والتجميد وإلغاؤه وdetails وcode لـ3DS. تسرّب المفتاح العادي وحده لا يكفي لتحريك الأموال أو قراءة الحسّاس.

اللوحة → الأدوات والإعدادات → إدارة API → إنشاء، ثم انسخ المفتاحين؛ يظهر السري مرة واحدة.

لا يقبل الإصدار والشحن والإلغاء والاسترجاع والتجميد وإلغاؤه والتفاصيل وCVV و3DS إلا طلبات موقّعة؛ المفتاح العادي يعيد 401. لا يلزم للبقية المقروءة.

رصيد الحساب

GET /api/v1/account/balance

اقرأ رصيد الحساب الحالي بالدولار، مع إرفاق عنوان إيداع TRON الثابت المخصص قدر الإمكان (تكون deposit_address بقيمة null إذا كانت مجموعة العناوين غير متاحة مؤقتًا؛ ويُعاد الرصيد في كل الأحوال).

عنوان TRON ثابت

GET /api/v1/account/deposit-address

اجلب أو خصّص عنوان TRON ثابتًا (USDT/TRX·TRC20). دون طلب يُحوّل كل مبلغ إلى USD ويُضاف تلقائيًا، مناسب للشحن البرمجي. يبقى العنوان ثابتًا بعد التخصيص.

حقول الرد

أرسل USDT أو TRX إلى هذا العنوان؛ بعد تأكيد ماسح الكتل يُحوَّل المبلغ تلقائيًا إلى USD بالسعر اللحظي ويُضاف إلى رصيدك على المنصة — دون الحاجة إلى أي callback.

حالة الخدمة

GET /api/v1/vcard/info

يعيد حالة تفعيل البطاقات ورصيد USD.

حقول الرد

إذا تعذّرت قراءة رصيد الحساب، تعيد النقطة HTTP 503 بدلًا من balance: 0. عند 503 أعد المحاولة لاحقًا ولا تعامله كرصيد صفري.

أرقام BIN للبطاقات

GET /api/v1/vcard/bins

تعيد قائمة أرقام BIN للبطاقات. الرسوم أسعار نهائية تشمل هامش المنصة، وتُحسب وفق شريحة API المطابقة لاستهلاكك في آخر 30 يومًا (كلما زاد الإنفاق انخفضت النسبة). القيمة can_open=false تشير إلى أرقام BIN المتاحة للشحن فقط (للبطاقات القائمة، ولا يمكن فتح بطاقات جديدة بها).

فتح بطاقة موقّع

POST /api/v1/vcard/cards

إنشاء بطاقة جديدة. يخصم النظام من رصيد حسابك بالدولار (رسم الفتح + رسم الشحن + المبلغ المحمّل على البطاقة)؛ ويُعالَج الطلب بشكل غير متزامن عبر قائمة انتظار.

حقول الرد

بعد رد order_id وstatus=queued، استطلع التفاصيل حتى completed. يُستردّ الفشل تلقائيًا للرصيد.

عند انتهاء مهلة الطلب أو انقطاع الاتصال، قد يكون الخصم قد وقع فعلًا. لا تُعد المحاولة برقم طلب جديد: أعد الإرسال بالقيمة نفسها لـ out_trade_no (يُعاد الطلب القائم كما هو ولا يُخصم مرة أخرى)، أو استعلم عن النتيجة عبر GET /api/v1/vcard/orders/by-trade-no/:out_trade_no. الطلبات التي لا تحمل out_trade_no لا تتمتع بهذه الحماية، وقد تخصم إعادة المحاولة مرة ثانية.

قائمة البطاقات

GET /api/v1/vcard/cards

كل بطاقات الحساب بآخر 4 أرقام والرصيد وقابلية الاستخدام وحالة الإلغاء.

حقول الرد

تعيد قائمة البطاقات الحقول الواردة في الجدول أعلاه فقط. الحقلان can_return و fee_return يُعادان لبعض أرقام BIN فقط؛ فإذا غابا فاعتبر أن البطاقة لا تدعم إعادة الرصيد.

تفاصيل البطاقة موقّع

GET /api/v1/vcard/cards/:id/details

تعيد البيانات الحساسة لبطاقة واحدة بنصها الصريح: رقم البطاقة الكامل ورمز CVV وتاريخ الانتهاء واسم حامل البطاقة. لا يمكن الاستعلام إلا عن بطاقاتك أنت.

حقول الرد

ملاحظة: يسرد الجدول أعلاه الحقول التي تضمن المنصة إعادتها، وقد يتضمن الرد حقولًا أخرى وفق ما يُعاد فعليًا.

تعيد هذه النقطة رقم البطاقة الكامل ورمز CVV — استدعِها من خادم موثوق فقط، ولا تعرضها أبدًا في الواجهات الأمامية أو السجلات.

المعاملات

GET /api/v1/vcard/cards/:id/transactions

تعيد سجلات معاملات البطاقة وكشف حسابها (الاستهلاك والشحن وغيرهما)، وتُزامَن أحدث السجلات فوريًا مع كل استعلام.

حقول الرد

ملاحظة: يسرد الجدول أعلاه الحقول التي تضمن المنصة إعادتها، وقد يتضمن الرد حقولًا أخرى وفق ما يُعاد فعليًا.

رمز OTP موقّع

GET /api/v1/vcard/cards/:id/code

اجلب أحدث OTP لـ3DS للتحقّق من الدفع.

شحن موقّع

POST /api/v1/vcard/cards/:id/recharge

شحن بطاقة قائمة. يُخصم من رصيد الحساب بالدولار (مبلغ الشحن + رسم الشحن)؛ ويُعالَج بشكل غير متزامن عبر قائمة انتظار.

حقول الرد

عند انتهاء مهلة الطلب أو انقطاع الاتصال، قد يكون الخصم قد وقع فعلًا. لا تُعد المحاولة برقم طلب جديد: أعد الإرسال بالقيمة نفسها لـ out_trade_no (يُعاد الطلب القائم كما هو ولا يُخصم مرة أخرى)، أو استعلم عن النتيجة عبر GET /api/v1/vcard/orders/by-trade-no/:out_trade_no. الطلبات التي لا تحمل out_trade_no لا تتمتع بهذه الحماية، وقد تخصم إعادة المحاولة مرة ثانية.

إلغاء موقّع

POST /api/v1/vcard/cards/:id/cancel

تقديم طلب إلغاء بطاقة. الإلغاء غير متزامن: بعد تأكيد البنك (قد يستغرق أيامًا) يُعاد الرصيد المتبقي في البطاقة تلقائيًا إلى رصيد حسابك.

استرجاع الرصيد موقّع

POST /api/v1/vcard/cards/:id/return

إعادة الرصيد المتبقي في البطاقة إلى رصيد حسابك دون إلغاء البطاقة. يُخصم الرسم من المبلغ المُعاد ويُضاف الصافي تلقائيًا. مدعوم في بعض أرقام BIN فقط: يمكن الاستدعاء عندما تكون can_return بقيمة true في قائمة البطاقات؛ و fee_return هو رسم الإعادة لذلك الـ BIN.

لا تُقبل إلا عملية إعادة واحدة لكل بطاقة في الوقت نفسه. إعادة الإرسال أثناء وجود عملية سابقة قيد التنفيذ تعيد 400 — انتظر وصول الطلب إلى حالته النهائية بدلًا من تكرار الطلب نفسه.

تجميد / إلغاء التجميد موقّع

POST /api/v1/vcard/cards/:id/freeze

تجميد بطاقة أو فك تجميدها. كل عملية تحصّل رسمًا صغيرًا (انظر status_fee في قائمة البطاقات). يمكن الاستدعاء فقط عندما تكون can_freeze بقيمة true؛ وتُعاد 400 إذا كانت البطاقة في الحالة المطلوبة أصلًا أو كانت عملية سابقة ما زالت قيد التنفيذ.

الشحن التلقائي (قواعد الرصيد) موقّع

GET /api/v1/vcard/balance-rules

GET /api/v1/vcard/cards/:id/balance-rule

PUT /api/v1/vcard/cards/:id/balance-rule

DELETE /api/v1/vcard/cards/:id/balance-rule

POST /api/v1/vcard/cards/:id/balance-rule/resume

يشحن البطاقة تلقائيًا عندما ينخفض رصيدها عن مبلغ محدد، أو يرسل تذكيرًا فقط. لكل بطاقة قاعدة واحدة؛ ينشئها PUT أو يستبدلها. يستخدم الشحن التلقائي مسار الخصم نفسه الذي يستخدمه الشحن اليدوي (الحدود والرسوم نفسها)، ويعمل عند تغيّر رصيد البطاقة أو في فحص كل دقيقة.

حدود الأمان: عدد مرات الشحن اليومية (1–10، حسب المنطقة الزمنية لحسابك) وحد شهري للمبلغ إلزاميان. تتوقف القاعدة مؤقتًا وتُعلمك إذا جُمّدت البطاقة أو كانت قيد الإغلاق، أو رفض المُصدر بسبب الاحتيال، أو رُفضت 3 معاملات متتالية، أو لم يكفِ رصيد حسابك 3 مرات متتالية. استدعِ resume لاستئنافها (لا يمكنك استئناف القواعد التي أوقفتها المنصة).

لا يمكن لمفاتيح API التي لها حد إنفاق يومي إنشاء الشحن التلقائي أو استئنافه (403، الرمز 4035): تخصم المنصة الشحن التلقائي في الخلفية خارج حد المفتاح. القواعد التي تكتفي بالتذكير غير متأثرة.

الاشتراكات

GET /api/v1/vcard/subscriptions

خصومات متكررة تم التعرّف عليها من معاملات بطاقاتك النشطة (للقراءة فقط، تُحسب لحظيًا): الخصومات المتكررة من التاجر نفسه بفاصل أسبوع أو شهر أو سنة تقريبًا تُعد اشتراكًا. لإيقاف أحدها جمّد البطاقة أو أغلقها.

التجار المسموح بهم موقّع

GET /api/v1/vcard/merchant-locks

GET /api/v1/vcard/cards/:id/merchant-lock

PUT /api/v1/vcard/cards/:id/merchant-lock

DELETE /api/v1/vcard/cards/:id/merchant-lock

يحدد التجار الذين يُسمح باستخدام البطاقة معهم. إذا ظهرت معاملة من تاجر آخر تُجمَّد البطاقة تلقائيًا (رسم تجميد واحد) أو تتلقى تنبيهًا فقط. تُفحص المعاملات اللاحقة لحفظ الإعداد فقط، ويحدث التجميد بعد الواقعة — فقد تمت الموافقة على أول معاملة خارج القائمة.

مجموعات البطاقات

GET /api/v1/vcard/groups

POST /api/v1/vcard/groups

PUT /api/v1/vcard/groups/:gid

DELETE /api/v1/vcard/groups/:gid

POST /api/v1/vcard/cards/group

نظّم البطاقات في مجموعات، ولكل مجموعة ميزانية شهرية اختيارية: تنبيه عند 80% وآخر عند التجاوز، ولا تُمنع المعاملات أبدًا. تنتمي البطاقة إلى مجموعة واحدة على الأكثر؛ group_id بقيمة 0 يزيلها من مجموعتها. حتى 20 مجموعة.

الكشف الشهري

GET /api/v1/vcard/bill/export

معاملات البطاقات لشهر واحد، لبطاقة واحدة أو مجموعة إن شئت، من الأقدم إلى الأحدث. تُدرج فقط المعاملات خلال فترة امتلاكك للبطاقة؛ إذا تجاوزت 20000 صف تتلقى 400 — صدّرها حسب البطاقة أو المجموعة.

قائمة الطلبات

GET /api/v1/vcard/orders

قائمة طلبات إصدار/شحن/إلغاء مقسّمة صفحات.

تفاصيل الطلب

GET /api/v1/vcard/orders/:id

استعلم عن طلب واحد لاستطلاع الإصدار/الشحن.

كائن طلب بحقول القائمة نفسها تمامًا.

ابحث برقم طلبك

GET /api/v1/vcard/orders/by-trade-no/:out_trade_no

تستعلم عن طلب بقيمة out_trade_no التي أُرسلت عند فتح البطاقة أو شحنها. الرد مطابق لـ«تفاصيل الطلب». تعيد 404 إذا كان الرقم غير موجود.

تعديل الملاحظة

PUT /api/v1/vcard/cards/:id/remark

عيّن ملاحظة للبطاقة بحد 60 حرفًا.

إشعارات Webhook

عند وقوع الأحداث (فتح بطاقة / شحنها / إلغاؤها، معاملة جديدة، رمز 3DS جديد) ترسلها المنصة إلى نقطتك عبر HTTP POST (بصيغة JSON) — دون حاجة إلى الاستعلام الدوري. اضبط ذلك من لوحة التحكم ← البطاقات الافتراضية ← تكامل API (مفتاح التفعيل + عنوان نقطة النهاية + سر التوقيع Secret + الأحداث المشترك فيها؛ ترك الأحداث دون تحديد = الاشتراك في الكل).

عقد التسليم: يجب أن تكون نقطة النهاية عنوان https متاحًا للعموم؛ الحمولة كائن JSON مسطّح وجميع قيمه سلاسل نصية؛ الرد بـ 2xx يعتبر التسليم ناجحًا، وإلا تعيد المنصة المحاولة بتراجع أسّي 30s → 1m → 2m → 5m → 10m حتى 10 محاولات. تحمل إعادة المحاولات notify_id نفسه — أزل التكرار اعتمادًا عليه لضمان عدم تكرار التنفيذ.

حقول عامة لكل حدث؛ الخاصّة أدناه:

تحقّق: استبعد الفارغ و"sign"، ورتّب المفاتيح ASC واربط k=v&k2=v2، واحسب HMAC-SHA256 سداسيًا صغيرًا بـ Secret وقارن sign. اشترط sign_ts ضمن ±5 دقائق وnonce جديدًا؛ ارفض بـ401 عند فشل أي فحص.

الأحداث وحقولها:

الأسئلة الشائعة

متى تصبح البطاقة قابلة للاستخدام، وأين يمكن الإنفاق بها؟

عادةً يعيد الإصدار بيانات البطاقة خلال ثوانٍ. تُستخدم لمدفوعات Visa / Mastercard عبر الإنترنت، مثل اشتراكات الذكاء الاصطناعي والإعلانات والتجارة عبر الحدود؛ ويعتمد القبول على BIN والمصدر والمنطقة وسياسة البائع.

كيف أشخّص معاملة مرفوضة؟

استعلم من واجهة سجل المعاملات عن رمز سبب رفض التفويض؛ أكثر الأسباب شيوعًا عدم كفاية الرصيد أوتقييد فئة البائع أوحظر من ضوابط المخاطر. تُرسل أحداث التفويض والتسوية أيضًا عبر Webhook للمطابقة المالية.

صفحات ذات صلة: البطاقات الافتراضية · وثائق الواجهة البرمجية · مدفوعات مشفّرة متعددة السلاسل

جارٍ التحميل…