تخطَّ إلى المحتوى
Gurdx

التوثيق / مرجع الواجهة

كشف احتيال الدفع

تقيّم معاملة بدرجة من 0 إلى 100 لمخاطر الاحتيال بتمريرها على مكتبة من قواعد احتيال المدفوعات.

نظرة عامة#

scoring/payment دالة POST. ترسل كائن data يصف المعاملة: العملية action (purchase أو deposit أو withdrawal) والمبلغ والعملة وعناصر السلة وهوية العميل وعنوان IP والجهاز وبيانات التواصل وعنوانا الشحن والفوترة وpayment_type وبيانات البطاقة إن توفرت. كل الحقول اختيارية، لكن كلما أرسلت أكثر عمل عدد أكبر من القواعد. تحوي الاستجابة score وقائمة rules التي انطبقت (لكل قاعدة id مثل PF1003 ووصف) وrulesChecked وrulesDetected.

مسار التكامل#

  1. استدعِ الدالة من خادمك قبل تحصيل الدفعة أو تفويضها مباشرة، ومرّر كل ما تعرفه عن الطلب.
  2. اقرأ score وقرّر بحسب النطاقات أدناه.
  3. سجّل rules المرجعة مع الطلب ليرى فريق الدعم سبب احتجازه.
  4. يُستحسن إرسال userID وcustomer_id ثابتين ليُتعرَّف على السلوك المتكرر عبر الطلبات.

لا ترسل رقم البطاقة الكامل إن أمكن تجنبه: تحتفظ Gurdx بالـ BIN وآخر أربعة أرقام وبصمة مفتاحية فقط، ولا تحفظ الرقم نفسه.

التصرف بحسب الدرجة#

هذه النطاقات نقطة بداية؛ اضبطها بحسب تحمّلك لرسوم الاسترداد.

  • من 0 إلى 30، خطورة منخفضة: وافق تلقائيًا.
  • من 30 إلى 60، خطورة متوسطة: اطلب تحققًا إضافيًا (3-D Secure أو رمز لمرة واحدة أو فحص هوية) أو احتجز للمراجعة.
  • من 60 إلى 100، خطورة عالية: ارفض أو اشترط موافقة يدوية.

تُطلِق Gurdx حدث fraud_payment عند 50 فأكثر ويصل إلى الويب هوك.

اضبط isDigitalProducts على true حين يحتوي الطلب على سلع تُسلَّم فورًا مثل رصيد الألعاب وبطاقات الهدايا والاشتراكات. فهي تُعاد بيعها بسرعة ويصعب استردادها، لذا تُطبَّق قواعد السلع الرقمية بصرامة أكبر. وحدّد action بصدق، فالسحب يُقيَّم بشكل مختلف عن الشراء.

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

rulesDetected مقابل rulesChecked يبيّن حجم الأدلة: درجة عالية من قاعدة واحدة تختلف عن درجة عالية ناتجة عن قواعد كثيرة. القسم المولَّد أدناه يسرد معرّف كل قاعدة.

ملاحظات#

  • تُحتسب طلبًا واحدًا؛ وضع الاختبار يُرجع بيانات وهمية مجانًا دون أحداث.
  • ليست ضمن الباقة القياسية؛ متاحة في التجربة والمميّزة والدفع حسب الاستخدام.
  • يمكن للقواعد المخصصة للمدفوعات اختبار أي حقل إدخال أو النتيجة المحسوبة واستبدال الدرجة؛ راجع القواعد المخصصة. كما تدخل قوائمك السوداء للعناوين والبريد والجوال والبطاقات في احتساب الدرجة.
  • الكائن data المفقود أو غير الصحيح يُرجع الخطأ 130 (invalid_payment_data) مع HTTP 200.

الطلب#

POST https://gurdx.cretip.com/api/scoring/payment
  • صادِق بمعامل key أو بترويسة Authorization: Bearer.
  • تُحتسب طلباً واحداً.
  • متاحة في: تجربة مجانية المميّزة الدفع حسب الاستخدام

المعاملات#

الاسمالنوعالوصف
data
مطلوب جسم
object —

جسم الطلب · data#

الاسمالنوعالوصف
action string The action your customer try to implement. Accepts: purchase, deposit, or withdrawal.
website_domain string The domain name of the website the customer trying to purchase from. Sample value: domain.com
website_name string The name of the website the customer trying to purchase from. Sample value: Nike Store, California
merchant_id string|integer If your a service provider with "sub-websites" (like Shopify), then provide a unique identification code indicating the website the customer trying to purchase from. Sample values: 12330098, 01as-aowq-029jd, or abcdefg.
shipment_id string|integer|number The identification code of the shipment.
transaction_id string|integer|number The identification code of the transaction in your system.
transaction_amount string|number|float The total amount of the transaction.
transaction_currency string The currency in which the customer pay with. Sample value: GBP
cart_items.item_id string|number|integer —
cart_items.item_name string —
cart_items.item_quantity string|integer —
cart_items.item_quantity integer —
cart_items.item_price string|float|integer —
cart_items.item_category_id string|number|integer —
cart_items string|integer|number —
isDigitalProducts boolean Set this to true if the customer is purchasing a digital product.
coupon string The promo code used by the customer to complete the checkout.
customer_id string|integer The identification number of the customer in your system.
customer_firstname string The first name of the customer.
customer_lastname string The last name of the customer (Family Name).
customer_pob string The Place of Birth of the customer.
customer_ip string The IP address of the customer.
customer_country string The ISO 3166-1 alpha-2 code format of the country where the customer live. Learn more
customer_region string The name of the region where the customer live.
customer_city string The name of the city where the customer live.
customer_zip string|integer|number The name of the zip code of customer location.
customer_street string The "address line 1" of the customer.
customer_street2 string The "address line 2" of the customer.
customer_latitude integer|float The customer latitude on the map (GPS Coordinates).
customer_longitude integer|float The customer longitude on the map (GPS Coordinates).
customer_device_id string|integer|number The device identification code of the customer.
customer_phone string|integer|number The phone number of the customer (international format).
customer_registration_date integer The registration date of the customer (UNIX Timestamp).
customer_balance string|integer|float If you offer a Wallet feature in your website, then pass the user balance to this pararmeter.
customer_dob string The customer's date of birth. Sample value: '1985-12-27`
customer_email string The email address of the customer.
customer_2fa boolean Set this to true if the customer has 2FA enabled in his/her account.
customer_useragent string Pass the User Agent of the customer to this parameter.
shipping_country string The shipping country code of the customer (in ISO 3166-1 alpha-2 format).
shipping_region string The shipping region name of the customer.
shipping_city string The shipping city name of the customer.
shipping_zip string|number|integer The zip code of the customer's shipping address.
shipping_street string The shipping "address 1" of the customer.
shipping_street2 string The shipping "address 2" of the customer.
shipping_latitude integer|number|float The latitude of the customer's shipping address (GPS Coordinates).
shipping_longitude integer|number|float The longitude of the customer's shipping address (GPS Coordinates).
billing_country string The billing country code of the customer (in ISO 3166-1 alpha-2 format).
billing_region string The billing region name of the customer.
billing_city string The billing city name of the customer.
billing_zip string|number|integer The zip code of the customer's billing address.
billing_street string The billing "address 1" of the customer.
billing_street2 string The billing "address 2" of the customer.
billing_latitude integer|float The latitude of the customer's billing address (GPS Coordinates).
billing_longitude integer|float The longitude of the customer's billing address (GPS Coordinates).
payment_type string The payment method used to complete this transaction. Accepted values: cards, cards_mada, applepay, stcpay, bank, crypto, wallet, or cod.
card_name string The name on the card (Cardholder Name).
card_number string|number|integer The card number (min: 6 digits).
card_expiry string The expiry date of the customer debit/credit card. Sample value: 29/05
cvv_result boolean Set this to true if the customer passed the CVV/CSV verification process.

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

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

curl -X POST "https://gurdx.cretip.com/api/scoring/payment" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
        "action": "purchase",
        "website_domain": "shop.example.com",
        "transaction_id": "ORD-10492",
        "transaction_amount": 149.99,
        "transaction_currency": "USD",
        "isDigitalProducts": true,
        "customer_id": "cus_83921",
        "customer_email": "user@example.com",
        "customer_phone": "+966501234567",
        "customer_ip": "203.0.113.42",
        "customer_country": "SA",
        "payment_type": "visa",
        "card_number": "4571736000000075"
    }
}'

الاستجابة#

نجاح#

{
    "data": {
        "score": 82,
        "rules": [
            {
                "id": "PF10003",
                "description": "Customer IP Address is probably VPN/Proxy/Bot/Hosting/Cloud."
            },
            {
                "id": "PF10004",
                "description": "Customer Email Address is probably invalid or spam."
            },
            {
                "id": "PF10001",
                "description": "High purchase rate, according to `customer_ip`."
            },
            {
                "id": "PF10002",
                "description": "High purchase rate, according to `customer_id`."
            },
            {
                "id": "PF10013",
                "description": "Customer device might not be a real device (according to `customer_useragent`)."
            },
            {
                "id": "PF10014",
                "description": "Customer device is registered as a high-risk device (according to `customer_useragent`)."
            }
        ],
        "rulesChecked": 21,
        "rulesDetected": 6,
        "custom_rules_applied": {
            "total": 0,
            "rules": []
        }
    },
    "status": "success",
    "executionTime": 5
}

خطأ#

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

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

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

الاسمالنوعالوصف
data.score float A risk-score from 0 to 100 indicating how risky this transaction is (10.5 means it's 10.5% risky to pass this transaction).
data.rules.id string The Id of the detected rule. (10.5 means it's 10.5% risky to pass this transaction). Sample value: PF10003
data.rules.description string The full description of the detected rule. Sample value: High purchase rate, according to "customer_id".
data.rules array —
data.rulesChecked integer Total rules checked against the transaction.
data.rulesDetected integer Total rules detected in the transaction.
data.custom_rules_applied.total integer The total number of custom rules applied to this request.
data.custom_rules_applied.rules.id string The rule ID as shown in the dashboard (e.g: CR104).
data.custom_rules_applied.rules.title string The rule title you set when creating the rule.
data.custom_rules_applied.rules object The custom rules applied to this request, learn more.
data.custom_rules_applied object The custom rules applied to this request, learn more.
data.status string The response status. Expected values: success, or error.
data.executionTime integer Time spent in milliseconds to process the data.
data object —

القواعد الممكنة#

القاعدةالوصف
PF1001High purchase rate, according to customer_ip.
PF1002High purchase rate, according to customer_id.
PF1003Customer IP Address is probably VPN/Proxy/Bot/Hosting/Cloud.
PF1004Customer Email Address is probably invalid, disposable or spam.
PF1005Customer Phone Number is probably invalid or spam.
PF1006Customer Latitude/Longitude is invalid.
PF1007Customer card number (BIN/IIN) is invalid.
PF1008Customer debit/credit card issued by a brand different from the one exist in payment_type parameter.
PF1009Customer country is a high-fraud country.
PF1010Customer debit/credit card issued in a high-risk country.
PF1011Customer is purchasing multiple times from multiple locations within the past 30 days.
PF1012Customer debit/credit card is being used multiple times from multiple customer accounts (according to customer_id and card_number).
PF1013Customer device might not be a real device (according to customer_useragent).
PF1014Customer device is registered as a high-risk device (according to customer_useragent).
PF1015AI flagged the transaction as potentially fraudulent.
PF1016AI flagged the transaction as potentially fraudulent due to high transaction amount.
PF1017Mismatch between billing address and IP geolocation.
PF1018Customer has multiple fraudulent transactions in the past 30 days.
PF1019Unusual purchase amount compared to customer’s history.
PF1020Transaction initiated from a newly created account.
PF10021Multiple payment cards used by a single account within a short timeframe.
PF10022Customer IP address were found in one of your blacklists.
PF10023Customer email address were found in one of your blacklists.
PF10024Customer phone number were found in one of your blacklists.
PF10025Customer card number were found in one of your blacklists.
PF10026Customer Id were found in one of your blacklists.
GX2001Customer (id, email or phone) was previously confirmed fraudulent in your feedback.
GX2002Customer shares a device, card or IP address with an identity previously confirmed fraudulent in your feedback.

وجدت خطأ؟ أخبرنا عبر صفحة التواصل. تواصل معنا