فحص البطاقة BIN

تحدد مُصدِر بطاقة الدفع وعلامتها ونوعها ودولتها من أرقامها الأولى وتخبرك هل الـ BIN صالح.

نظرة عامة#

الـ BIN (رقم تعريف المصرف، ويسمى أيضًا IIN) هو أول ستة إلى ثمانية أرقام من رقم البطاقة. يستقبله lookup/bin في المعامل bin ويُرجع isValid وreason عند عدم الصلاحية وblacklisted وكائن info يضم شبكة البطاقة (الاسم والعلامة والنوع والعملة ومؤشرا الدفع المسبق والتجارية) وصيغة رقم البطاقة والمصرف المُصدِر (الاسم والمدينة والموقع والهاتف والإحداثيات) ودولة الإصدار.

أرسل الأرقام الأولى فقط، ولا ترسل رقم بطاقة كاملًا إلى هذه الدالة أبدًا.

متى تستخدمه#

• للتحقق من البطاقة عند الدفع قبل استدعاء بوابة الدفع.
• لمقارنة دولة البطاقة بدولة فوترة العميل أو دولة IP.
• لاكتشاف البطاقات المسبقة الدفع أو التجارية إن كانت سياستك تعاملها بشكل مختلف.
• لتوجيه المدفوعات حسب الشبكة أو المُصدِر.

قراءة النتيجة#

• isValid: false تعني أن الرقم ليس BIN معروفًا، وreason يوضح السبب. اعتبر تكرار BIN غير صالح من عميل واحد اختبارًا للبطاقات.
• info.country.alpha2 هي دولة إصدار البطاقة. الاختلاف عن دولة العميل إشارة خطر كلاسيكية لكنه شائع عند المسافرين، فوازنه بأدلة أخرى.
• بطاقات info.scheme.isPrepaid أصعب في التتبع وأكثر استخدامًا في الإساءة، وisCommercial تدل على بطاقات الشركات.
• info.scheme.type يفرّق بين الخصم والائتمان، وقد يؤثر ذلك في تسعير المخاطرة.
• blacklisted يعكس قوائمك السوداء.

التغطية#

الكائن info موجود دائمًا. فإن كان الـ BIN في بياناتنا المرجعية تحصل على الشبكة ونوع البطاقة (debit أو credit أو charge) والعلامة/الفئة (Classic وPlatinum وInfinite وWorld Elite...) ومؤشرَي الدفع المسبق والتجارية واسم المصرف المُصدِر وموقعه وهاتفه. وتُعرَف بطاقات مدى السعودية بنطاقاتها، بما فيها بطاقات الخصم المشتركة مع Visa وMastercard. وإن لم يكن لدينا سجل للـ BIN تحصل مع ذلك على الشبكة وصيغة البطاقة المستنتجتين من الرقم نفسه، وتكون حقول المصرف والدولة null، وتعكس isValid الشبكة وفحص Luhn عند إرسال رقم كامل. وتُنسَّق أسماء المُصدِرين بحروف عنوانية.

ملاحظات#

• تُحتسب طلبًا واحدًا. وضع الاختبار يُرجع بيانات وهمية مجانًا دون أحداث.
• مشمولة في كل الباقات بما فيها القياسية.
• يمكن لـالقواعد المخصصة في مجموعة BIN اختبار الشبكة ونوع البطاقة والدفع المسبق والتجارية ودولة الإصدار والمصرف، وتعليم الـ BIN كصالح أو غير صالح؛ وتظهر القواعد المطبقة في custom_rules_applied.
• يُطلَق حدث invalid_bin عند اعتبار الـ BIN غير صالح ويصل إلى الويب هوك.
• القيمة المفقودة أو غير الصحيحة تُرجع الخطأ 120 (invalid_bin_number) مع HTTP 200. وتجري دالة كشف احتيال الدفع هذا الفحص بنفسها عند تمرير رقم بطاقة.

الطلب#

• صادِق بمعامل key أو بترويسة Authorization: Bearer.
• تُحتسب طلباً واحداً.
• متاحة في: تجربة مجانية القياسية المميّزة الدفع حسب الاستخدام

المعاملات#

تقبل كل خدمة أيضاً format, lang, mode, userID, callback. راجع الخيارات.

أمثلة برمجية#

curl -G "https://gurdx.cretip.com/api/lookup/bin" \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "bin=45717360"

<?php

$response = file_get_contents('https://gurdx.cretip.com/api/lookup/bin?'.http_build_query(['key' => 'YOUR_API_KEY', 'bin' => '45717360']));
$result = json_decode($response, true);

if ($result['status'] === 'success') {
    print_r($result['data']);
} else {
    echo $result['code'].': '.$result['description'];
}

const params = new URLSearchParams({"key":"YOUR_API_KEY","bin":"45717360"});
const res = await fetch(`https://gurdx.cretip.com/api/lookup/bin?${params}`);
const result = await res.json();

if (result.status === 'success') {
  console.log(result.data);
} else {
  console.error(result.code, result.description);
}

import requests

res = requests.get("https://gurdx.cretip.com/api/lookup/bin", params={"key": "YOUR_API_KEY", "bin": "45717360"})
result = res.json()

if result["status"] == "success":
    print(result["data"])
else:
    print(result["code"], result["description"])

الاستجابة#

نجاح#

{
    "data": {
        "reason": "",
        "isValid": true,
        "blacklisted": false,
        "bin": "456789",
        "info": {
            "scheme": {
                "name": "Visa",
                "coName": "Mada",
                "isLuha": true,
                "isPrepaid": false,
                "isCommercial": false,
                "type": "debit",
                "brand": "Traditional",
                "currency": "SAR"
            },
            "detected_digits": "4",
            "syntax": {
                "gaps": [
                    4,
                    8,
                    12
                ],
                "lengths": [
                    16,
                    18,
                    19
                ],
                "code": {
                    "name": "CVV",
                    "size": 3
                }
            },
            "bank": {
                "id": "588847",
                "identifier": "80",
                "name": "AL RAJHI BANKING AND INVESTMENT CORP.",
                "city": "Riyadh",
                "url": "https://www.alrajhibank.com.sa",
                "phone": "+96611211600",
                "logo": "https://gurdx.io/img/banks/al-rajhi.jpg",
                "latitude": "25",
                "longitude": "45"
            },
            "country": {
                "alpha2": "SA",
                "name": "Saudi Arabia",
                "code": "966",
                "numeric": "682",
                "emoji": "🇸🇦",
                "continent": "Asia",
                "languageCode": "ar",
                "languageNative": "العربية"
            }
        },
        "custom_rules_applied": {
            "total": 0,
            "rules": []
        }
    },
    "status": "success",
    "executionTime": 2
}

خطأ#

تُسلَّم الأخطاء بحالة HTTP 200 — افحص دائماً حقل status.

{
    "status": "error",
    "code": 101,
    "type": "invalid_key",
    "description": "The API Key is missing or invalid."
}

حقول الاستجابة#