التوثيق / مرجع الواجهة
كشف احتيال الدفع
تقيّم معاملة بدرجة من 0 إلى 100 لمخاطر الاحتيال بتمريرها على مكتبة من قواعد احتيال المدفوعات.
نظرة عامة#
scoring/payment دالة POST. ترسل كائن data يصف المعاملة: العملية action (purchase أو deposit أو withdrawal) والمبلغ والعملة وعناصر السلة وهوية العميل وعنوان IP والجهاز وبيانات التواصل وعنوانا الشحن والفوترة وpayment_type وبيانات البطاقة إن توفرت. كل الحقول اختيارية، لكن كلما أرسلت أكثر عمل عدد أكبر من القواعد. تحوي الاستجابة score وقائمة rules التي انطبقت (لكل قاعدة id مثل PF1003 ووصف) وrulesChecked وrulesDetected.
مسار التكامل#
- استدعِ الدالة من خادمك قبل تحصيل الدفعة أو تفويضها مباشرة، ومرّر كل ما تعرفه عن الطلب.
- اقرأ
scoreوقرّر بحسب النطاقات أدناه. - سجّل
rulesالمرجعة مع الطلب ليرى فريق الدعم سبب احتجازه. - يُستحسن إرسال
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.
الطلب#
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"
}
}'
<?php
$payload = [
'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',
],
];
$ch = curl_init('https://gurdx.cretip.com/api/scoring/payment');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY', 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($payload),
]);
$result = json_decode(curl_exec($ch), true);
if ($result['status'] === 'success' && $result['data']['score'] >= 60) {
// hold the order for manual review
}
const res = await fetch('https://gurdx.cretip.com/api/scoring/payment', {
method: 'POST',
headers: {
Authorization: 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
"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"
}
}),
});
const result = await res.json();
if (result.status === 'success' && result.data.score >= 60) {
// hold the order for manual review
}
import requests
res = requests.post(
"https://gurdx.cretip.com/api/scoring/payment",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"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",
},
},
)
result = res.json()
if result["status"] == "success" and result["data"]["score"] >= 60:
pass # hold the order for manual review
الاستجابة#
نجاح#
{
"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 |
— |
القواعد الممكنة#
| القاعدة | الوصف |
|---|---|
PF1001 | High purchase rate, according to customer_ip.
|
PF1002 | High purchase rate, according to customer_id.
|
PF1003 | Customer IP Address is probably VPN/Proxy/Bot/Hosting/Cloud. |
PF1004 | Customer Email Address is probably invalid, disposable or spam. |
PF1005 | Customer Phone Number is probably invalid or spam. |
PF1006 | Customer Latitude/Longitude is invalid. |
PF1007 | Customer card number (BIN/IIN) is invalid. |
PF1008 | Customer debit/credit card issued by a brand different from the one exist in payment_type parameter.
|
PF1009 | Customer country is a high-fraud country. |
PF1010 | Customer debit/credit card issued in a high-risk country. |
PF1011 | Customer is purchasing multiple times from multiple locations within the past 30 days. |
PF1012 | Customer debit/credit card is being used multiple times from multiple customer accounts (according to customer_id and card_number).
|
PF1013 | Customer device might not be a real device (according to customer_useragent).
|
PF1014 | Customer device is registered as a high-risk device (according to customer_useragent).
|
PF1015 | AI flagged the transaction as potentially fraudulent. |
PF1016 | AI flagged the transaction as potentially fraudulent due to high transaction amount. |
PF1017 | Mismatch between billing address and IP geolocation. |
PF1018 | Customer has multiple fraudulent transactions in the past 30 days. |
PF1019 | Unusual purchase amount compared to customer’s history. |
PF1020 | Transaction initiated from a newly created account. |
PF10021 | Multiple payment cards used by a single account within a short timeframe. |
PF10022 | Customer IP address were found in one of your blacklists. |
PF10023 | Customer email address were found in one of your blacklists. |
PF10024 | Customer phone number were found in one of your blacklists. |
PF10025 | Customer card number were found in one of your blacklists. |
PF10026 | Customer Id were found in one of your blacklists. |
GX2001 | Customer (id, email or phone) was previously confirmed fraudulent in your feedback. |
GX2002 | Customer shares a device, card or IP address with an identity previously confirmed fraudulent in your feedback. |
وجدت خطأ؟ أخبرنا عبر صفحة التواصل. تواصل معنا