Docs / API reference

Payment Fraud Detection

Scores a transaction from 0 to 100 for fraud risk by running it through a library of payment-fraud rules.

Overview#

scoring/payment is a POST method. You send a data object describing the transaction: the action (purchase, deposit or withdrawal), the amount and currency, the cart items, the customer's identity, IP, device and contact details, the shipping and billing addresses, the payment_type and, if you have them, card details. Every field is optional, but the more you send, the more rules can run. The response contains the score, the list of rules that fired (each with an id such as PF10003 and a description), rulesChecked and rulesDetected.

Integration workflow#

Call the method from your server right before you capture or authorize the payment, passing everything you know about the order.
Read score and decide using the bands below.
Log the returned rules with the order, so support staff can see why an order was held.
Optionally send a stable userID and customer_id so repeat behavior is recognized across orders.

Never send a full card number if you can avoid it: Gurdx keeps only the BIN, the last four digits and a keyed hash, never the number itself.

Acting on the score#

These bands are a starting point; tune them to your chargeback tolerance.

0 to 30, low risk: approve automatically.
30 to 60, medium risk: step up (3-D Secure, a one-time code, an ID check) or hold for review.
60 to 100, high risk: decline or require manual approval.

Gurdx raises a fraud_payment event at 50 and above, which is delivered to your webhooks.

Set isDigitalProducts to true when the order contains instantly delivered goods such as game credits, gift cards or subscriptions. They are resold quickly and hard to recover, so the digital-goods rules are applied more strictly. Pick action honestly, since a withdrawal is judged differently from a purchase.

Reading the result#

rulesDetected against rulesChecked tells you how much evidence there was: a high score from one rule is different from a high score built from many. The generated section below lists every rule id.

Notes#

Counts as one request; Test mode returns fake data, is free and raises no events.
Not part of the Standard plan; available on trial, Premium and pay-as-you-go.
Custom rules for payments can test any input field or the computed result and can overwrite the score; see Custom rules. Your blacklists of IPs, emails, phones and cards also feed the scoring.
A missing or invalid data object returns error 130 (invalid_payment_data) with HTTP 200.

Request#

POST https://gurdx.cretip.com/api/scoring/payment

Authenticate with the key parameter or an Authorization: Bearer header.
Counts as 1 request.
Available on: Free trial Premium Pay-as-you-go

Parameters#

Name	Type	Description
`data` required body	`object`	—

Request body · `data`#

Name	Type	Description
`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.

Every method also accepts format, lang, mode, userID. See Options.

Code samples#

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

Response#

Success#

{
    "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
}

Error#

Errors are delivered with HTTP 200 — always check the status field.

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

Response fields#

Name	Type	Description
`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`	—

Possible rules#

Rule	Description
`PF10001`	High purchase rate, according to `customer_ip`.
`PF10002`	High purchase rate, according to `customer_id`.
`PF10003`	Customer IP Address is probably VPN/Proxy/Bot/Hosting/Cloud.
`PF10004`	Customer Email Address is probably invalid, disposable or spam.
`PF10005`	Customer Phone Number is probably invalid or spam.
`PF10006`	Customer Latitude/Longitude is invalid.
`PF10007`	Customer card number (BIN/IIN) is invalid.
`PF10008`	Customer debit/credit card issued by a brand different from the one exist in `payment_type` parameter.
`PF10009`	Customer country is a high-fraud country.
`PF10010`	Customer debit/credit card issued in a high-risk country.
`PF10011`	Customer is purchasing multiple times from multiple locations within the past 30 days.
`PF10012`	Customer debit/credit card is being used multiple times from multiple customer accounts (according to `customer_id` and `card_number`).
`PF10013`	Customer device might not be a real device (according to `customer_useragent`).
`PF10014`	Customer device is registered as a high-risk device (according to `customer_useragent`).
`PF10015`	AI flagged the transaction as potentially fraudulent.
`PF10016`	AI flagged the transaction as potentially fraudulent due to high transaction amount.
`PF10017`	Mismatch between billing address and IP geolocation.
`PF10018`	Customer has multiple fraudulent transactions in the past 30 days.
`PF10019`	Unusual purchase amount compared to customer’s history.
`PF10020`	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.

Found a mistake? Tell us on the contact page. Contact