توثيق API — CryptoTopCard API البطاقات الافتراضية

المصادقة

مفاتيح API & المصادقة

تتطلب جميع طلبات API رمز Bearer. أنشئ مفتاح API من لوحة التحكم → الإعدادات → مفاتيح API.

أمان مفتاح API

لا تكشف مفتاحك في كود العميل أبداً. استخدم متغيرات البيئة. المفاتيح بادئة sk_live_ للإنتاج، sk_test_ للتجربة.

request-headers

Authorization: Bearer sk_live_your_api_key_here
Content-Type: application/json
X-Idempotency-Key: optional-unique-key-for-safe-retries

حدود المعدل

1,000

طلبات / دقيقة

50

إنشاء بطاقات / دقيقة

10,000

طلبات / ساعة

رموز الأخطاء

error-response.json

{
  "error": "insufficient_funds",
  "message": "Your wallet balance is too low to fund this card.",
  "code": 400,
  "request_id": "req_7f8a9b2c3d4e"
}

200

نجح الطلب

201

تم إنشاء المورد

400

معلمات طلب غير صالحة

401

مفتاح API مفقود أو غير صالح

404

المورد غير موجود

429

تم تجاوز حد المعدل

البطاقات

إدارة البطاقات

أنشئ وأدر وتحكم في بطاقات Visa & Mastercard الافتراضية. كل بطاقة معزولة برصيدها وحدودها ودورة حياتها.

POST /cards إصدار بطاقة افتراضية جديدة

جسم الطلب

المعلمة	النوع		الوصف
bin_id	string	required	معرّف BIN (مثل `491653`). استخدم `GET /bins` لعرض BINs المتاحة.
amount	number	required	مبلغ التمويل الأولي بالدولار. الحد الأدنى: $1.00، الحد الأقصى: $5,000.00
label	string	optional	تسمية مخصصة للبطاقة (حد أقصى 64 حرف)
spending_limit	number	optional	حد الإنفاق الشهري بالدولار. الافتراضي: الحد الأقصى لـ BIN.
allowed_categories	string[]	optional	فئات MCC للقائمة البيضاء (مثل `["advertising", "software"]`)
auto_freeze_at	number	optional	تجميد تلقائي عند انخفاض الرصيد دون هذا المبلغ
metadata	object	optional	أزواج مفتاح-قيمة للتتبع الداخلي (حد أقصى 20 مفتاح)

مثال على طلب

curl

curl -X POST https://api.cryptotopcard.com/v1/cards \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "bin_id": "491653",
    "amount": 500,
    "label": "Meta Ads Campaign #12",
    "spending_limit": 2000,
    "allowed_categories": ["advertising"],
    "metadata": {"campaign": "spring_2026"}
  }'

الاستجابة 201 Created

response.json

{
  "id": "card_8xK2m9Lp4q",
  "bin_id": "491653",
  "network": "visa",
  "last4": "2039",
  "status": "active",
  "balance": 500.00,
  "spending_limit": 2000.00,
  "label": "Meta Ads Campaign #12",
  "allowed_categories": ["advertising"],
  "auto_freeze_at": null,
  "metadata": { "campaign": "spring_2026" },
  "created_at": "2026-04-15T12:00:00Z",
  "expires_at": "2029-04-15T23:59:59Z"
}

GET /cards عرض جميع البطاقات مع الفلاتر والتصفح

معلمات الاستعلام

المعلمة	النوع		الوصف
status	string	optional	`active`, `frozen`, `terminated`
bin_id	string	optional	تصفية حسب BIN
label	string	optional	البحث حسب التسمية (تطابق جزئي)
sort	string	optional	`created_at`, `balance`, `last_used`. الافتراضي: `created_at`
order	string	optional	`asc` أو `desc`. الافتراضي: `desc`
page	integer	optional	رقم الصفحة. الافتراضي: `1`
per_page	integer	optional	عناصر لكل صفحة (1-100). الافتراضي: `25`

الاستجابة 200 OK

response.json

{
  "data": [
    {
      "id": "card_8xK2m9Lp4q",
      "bin_id": "491653",
      "network": "visa",
      "last4": "2039",
      "status": "active",
      "balance": 487.50,
      "label": "Meta Ads Campaign #12",
      "created_at": "2026-04-15T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 142,
    "total_pages": 6
  }
}

GET /cards/{card_id} الحصول على ملخص البطاقة (بدون بيانات حساسة)

يُرجع معلومات البطاقة بدون بيانات حساسة. استخدم /cards/{card_id}/details للحصول على PAN الكامل وCVV.

الاستجابة 200 OK

response.json

{
  "id": "card_8xK2m9Lp4q",
  "bin_id": "491653",
  "network": "visa",
  "last4": "2039",
  "status": "active",
  "balance": 487.50,
  "spending_limit": 2000.00,
  "total_spent": 12.50,
  "transaction_count": 3,
  "label": "Meta Ads Campaign #12",
  "metadata": { "campaign": "spring_2026" },
  "created_at": "2026-04-15T12:00:00Z",
  "expires_at": "2029-04-15T23:59:59Z",
  "last_used_at": "2026-04-15T14:32:00Z"
}

GET /cards/{card_id}/details الحصول على PAN الكامل وCVV وتاريخ الانتهاء

نقطة نهاية حساسة

يُرجع PAN الكامل وCVV وتاريخ الانتهاء. بيانات PCI حساسة — لا تسجلها أو تخزنها بدون تشفير. محدود بـ 30 طلب/دقيقة.

الاستجابة 200 OK

response.json

{
  "id": "card_8xK2m9Lp4q",
  "pan": "4916531288472039",
  "cvv": "847",
  "exp_month": 4,
  "exp_year": 2029,
  "holder_name": "ANONYMOUS",
  "billing_address": {
    "line1": "123 Privacy Street",
    "city": "Wilmington",
    "state": "DE",
    "zip": "19801",
    "country": "US"
  }
}

PATCH /cards/{card_id} تحديث إعدادات البطاقة

جسم الطلب

المعلمة	النوع		الوصف
label	string	optional	تحديث تسمية البطاقة
spending_limit	number	optional	تحديث حد الإنفاق الشهري
allowed_categories	string[]	optional	تحديث فئات MCC المسموحة
auto_freeze_at	number	optional	تعيين عتبة التجميد التلقائي. `0` للتعطيل.
metadata	object	optional	دمج مع البيانات الوصفية الحالية

الاستجابة 200 OK

يُرجع كائن البطاقة المحدّث.

POST /cards/{card_id}/freeze تعليق البطاقة مؤقتاً

يعلّق جميع المعاملات. يُحفظ الرصيد. يمكن إلغاء تجميد البطاقة لاحقاً.

الاستجابة 200 OK

response.json

{ "id": "card_8xK2m9Lp4q", "status": "frozen", "frozen_at": "2026-04-15T15:00:00Z" }

POST /cards/{card_id}/unfreeze إعادة تفعيل بطاقة مجمدة

يُعيد تفعيل المعاملات على بطاقة مجمدة. يُرجع كائن البطاقة مع status: "active".

DELETE /cards/{card_id} إنهاء البطاقة نهائياً

إجراء لا رجعة فيه

إنهاء البطاقة نهائي. يُعاد الرصيد المتبقي إلى محفظتك فوراً.

الاستجابة 200 OK

response.json

{
  "id": "card_8xK2m9Lp4q",
  "status": "terminated",
  "refunded_amount": 487.50,
  "terminated_at": "2026-04-15T16:00:00Z"
}

التمويل

تمويل البطاقات

أضف أو اسحب أموالاً من بطاقات فردية. الأموال تأتي من رصيد محفظتك.

POST /cards/{card_id}/fund إضافة أموال إلى بطاقة

جسم الطلب

المعلمة	النوع		الوصف
amount	number	required	المبلغ بالدولار للإضافة. الحد الأدنى: $1.00، الحد الأقصى: $5,000.00

الاستجابة 200 OK

response.json

{
  "id": "card_8xK2m9Lp4q",
  "previous_balance": 487.50,
  "funded_amount": 200.00,
  "new_balance": 687.50,
  "wallet_balance": 1312.50
}

POST /cards/{card_id}/withdraw سحب الأموال إلى المحفظة

جسم الطلب

المعلمة	النوع		الوصف
amount	number	required	المبلغ بالدولار لسحبه من البطاقة إلى المحفظة

الاستجابة 200 OK

يُرجع أرصدة البطاقة والمحفظة المحدّثة.

المعاملات

سجل المعاملات

اعرض جميع المعاملات عبر بطاقاتك. يشمل التفويضات والتسويات والمبالغ المستردة والرفض.

GET /transactions عرض جميع المعاملات مع الفلاتر

معلمات الاستعلام

المعلمة	النوع		الوصف
card_id	string	optional	تصفية حسب البطاقة
type	string	optional	`authorization`, `settlement`, `refund`, `decline`
from	string	optional	تاريخ البداية (ISO 8601)
to	string	optional	تاريخ النهاية (ISO 8601)
merchant	string	optional	البحث حسب اسم التاجر (تطابق جزئي)
min_amount	number	optional	الحد الأدنى لمبلغ المعاملة
max_amount	number	optional	الحد الأقصى لمبلغ المعاملة
page	integer	optional	رقم الصفحة. الافتراضي: `1`
per_page	integer	optional	عناصر لكل صفحة (1-100). الافتراضي: `50`

الاستجابة 200 OK

response.json

{
  "data": [
    {
      "id": "txn_a1b2c3d4",
      "card_id": "card_8xK2m9Lp4q",
      "type": "settlement",
      "amount": -12.50,
      "currency": "USD",
      "merchant": {
        "name": "FACEBK ADS",
        "category": "advertising",
        "mcc": "7311",
        "country": "US"
      },
      "balance_after": 487.50,
      "created_at": "2026-04-15T14:32:00Z"
    }
  ],
  "pagination": { "page": 1, "per_page": 50, "total": 328 }
}

GET /transactions/{txn_id} الحصول على تفاصيل المعاملة الكاملة

يُرجع كائن المعاملة الكامل بما في ذلك تفاصيل التاجر ورمز MCC وحالة 3DS وجدول التفويض.

المحفظة

المحفظة & الإيداعات

أدر محفظة حسابك. أودع العملات المشفرة، تحقق من الأرصدة وتتبع الإيداعات الواردة.

GET /wallet/balance الحصول على رصيد المحفظة والإحصائيات

الاستجابة 200 OK

response.json

{
  "balance": 1312.50,
  "currency": "USD",
  "pending_deposits": 500.00,
  "total_deposited": 15000.00,
  "total_spent": 13687.50,
  "cards_active": 8,
  "cards_total_balance": 2450.00
}

GET /wallet/deposit-address الحصول على عناوين إيداع العملات المشفرة

معلمات الاستعلام

المعلمة	النوع		الوصف
currency	string	optional	`btc`, `eth`, `sol`, `usdt`. اتركه للحصول على الكل.

الاستجابة 200 OK

response.json

{
  "addresses": {
    "btc": "bc1qxy2kgdygjrsqtzq2n0yrf...",
    "eth": "0x742d35Cc6634C0532925a3b...",
    "sol": "7xKXtg2CW87d97TXJSDpbD5j...",
    "usdt": "0x742d35Cc6634C0532925a3b..."
  },
  "networks": {
    "btc": "bitcoin",
    "eth": "ethereum",
    "sol": "solana",
    "usdt": "erc-20"
  },
  "min_deposit": {
    "btc": "0.0001",
    "eth": "0.005",
    "sol": "0.1",
    "usdt": "5.00"
  }
}

GET /wallet/deposits عرض سجل الإيداعات

معلمات الاستعلام

المعلمة	النوع		الوصف
status	string	optional	`pending`, `confirmed`, `expired`
currency	string	optional	تصفية حسب العملة المشفرة

الاستجابة 200 OK

response.json

{
  "data": [
    {
      "id": "dep_x9y8z7w6",
      "currency": "btc",
      "amount_crypto": "0.0075",
      "amount_usd": 500.00,
      "fee_usd": 10.00,
      "credited_usd": 490.00,
      "status": "confirmed",
      "tx_hash": "3a1b2c3d4e5f...",
      "confirmations": 6,
      "created_at": "2026-04-15T10:00:00Z",
      "confirmed_at": "2026-04-15T10:42:00Z"
    }
  ]
}

BINs

اختيار BIN

اعرض نطاقات BIN المتاحة مع إمكانياتها وحدودها ومعدلات القبول.

GET /bins عرض جميع BINs المتاحة

الاستجابة 200 OK

response.json

{
  "data": [
    {
      "id": "491653",
      "network": "visa",
      "type": "advertising",
      "issuer_country": "US",
      "3ds": true,
      "apple_pay": true,
      "google_pay": true,
      "max_transaction": 5000.00,
      "max_monthly": 50000.00,
      "acceptance_rate": 97.2,
      "best_for": ["meta_ads", "google_ads", "tiktok_ads"]
    },
    {
      "id": "531993",
      "network": "mastercard",
      "type": "everyday",
      "issuer_country": "US",
      "3ds": true,
      "apple_pay": true,
      "google_pay": true,
      "max_transaction": 1000.00,
      "max_monthly": 10000.00,
      "acceptance_rate": 95.8,
      "best_for": ["subscriptions", "saas", "shopping"]
    }
  ]
}

3D Secure

مصادقة 3D Secure

استرجع تحديات 3DS وأكواد OTP. جميع البطاقات مسجلة في 3DS 2.0 تلقائياً.

GET /3ds عرض تحديات 3DS المعلقة

معلمات الاستعلام

المعلمة	النوع		الوصف
card_id	string	optional	تصفية حسب البطاقة
status	string	optional	`pending`, `completed`, `expired`

الاستجابة 200 OK

response.json

{
  "data": [
    {
      "id": "3ds_m4n5o6p7",
      "card_id": "card_8xK2m9Lp4q",
      "merchant": "SPOTIFY",
      "amount": 9.99,
      "otp": "847291",
      "status": "pending",
      "expires_at": "2026-04-15T15:05:00Z",
      "created_at": "2026-04-15T15:00:00Z"
    }
  ]
}

GET /3ds/{challenge_id} الحصول على OTP 3DS محدد

يُرجع كائن تحدي 3DS الكامل بما في ذلك رمز OTP. تنتهي صلاحية OTP بعد 5 دقائق.

Webhooks

Webhooks & الأحداث

استلم إشعارات فورية عند وقوع الأحداث. الحمولات موقعة بـ HMAC-SHA256.

الأحداث المتاحة

card.createdتم إصدار بطاقة جديدة

card.frozenتم تجميد بطاقة

card.unfrozenتم إلغاء تجميد بطاقة

card.terminatedتم إنهاء بطاقة

card.fundedتمت إضافة أموال لبطاقة

transaction.authorizedتم تفويض المعاملة

transaction.settledتمت تسوية المعاملة

transaction.declinedتم رفض المعاملة

transaction.refundedتمت معالجة الاسترداد

3ds.challengeمطلوب تحقق 3DS

deposit.pendingتم اكتشاف إيداع مشفر

deposit.confirmedتم تأكيد إيداع مشفر

التحقق من التوقيع

verify-webhook.py

import hmac, hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

POST /webhooks تسجيل نقطة نهاية webhook

جسم الطلب

المعلمة	النوع		الوصف
url	string	required	عنوان URL لنقطة نهاية HTTPS لاستلام الأحداث
events	string[]	required	أنواع الأحداث للاشتراك. استخدم `["*"]` للكل.
secret	string	optional	مفتاح توقيع مخصص. يُنشأ تلقائياً إذا تم حذفه.

الاستجابة 201 Created

response.json

{
  "id": "wh_r5s6t7u8",
  "url": "https://yourapp.com/webhooks/ctc",
  "events": ["transaction.authorized", "transaction.declined"],
  "secret": "whsec_a1b2c3d4e5f6...",
  "active": true,
  "created_at": "2026-04-15T12:00:00Z"
}

GET /webhooks عرض webhooks المسجلة

يُرجع مصفوفة جميع نقاط نهاية webhook المسجلة مع اشتراكات الأحداث وحالتها.

DELETE /webhooks/{webhook_id} حذف webhook

يزيل webhook نهائياً. لن يتم تسليم أي أحداث أخرى إلى نقطة النهاية هذه.

SDKs

SDKs & المكتبات

مكتبات العملاء الرسمية لمجموعتك التقنية. تدعم جميع SDKs بيئات الإنتاج والتجربة.

Python

pip install cryptotopcard

Node.js

npm i cryptotopcard

Go

go get cryptotopcard

بدء سريع — Python

quickstart.py

from cryptotopcard import Client

client = Client("sk_live_your_api_key")

# إنشاء بطاقة
card = client.cards.create(
    bin_id="491653",
    amount=500,
    label="Ad Spend"
)
print(card.id, card.last4)

# الحصول على تفاصيل البطاقة الكاملة (PAN، CVV)
details = client.cards.details(card.id)
print(details.pan, details.cvv)

# تمويل البطاقة
client.cards.fund(card.id, amount=200)

# عرض المعاملات
txns = client.transactions.list(card_id=card.id)
for t in txns.data:
    print(t.merchant.name, t.amount)

بدء سريع — Node.js

quickstart.js

const { CryptoTopCard } = require('cryptotopcard');

const client = new CryptoTopCard('sk_live_your_api_key');

// إنشاء بطاقة
const card = await client.cards.create({
  binId: '491653',
  amount: 500,
  label: 'Ad Spend',
});

// الحصول على OTPs 3DS
const challenges = await client.threeds.list({
  cardId: card.id,
  status: 'pending',
});

// إعداد webhooks
await client.webhooks.create({
  url: 'https://yourapp.com/hooks',
  events: ['transaction.authorized', '3ds.challenge'],
});

API المرجع

مفاتيح API & المصادقة

أمان مفتاح API

إدارة البطاقات

نقطة نهاية حساسة

إجراء لا رجعة فيه

تمويل البطاقات

سجل المعاملات

المحفظة & الإيداعات

اختيار BIN

مصادقة 3D Secure

Webhooks & الأحداث

SDKs & المكتبات

Python

Node.js

Go

مرحباً بعودتك

إنشاء حساب

تم إنشاء الحساب