> ## Documentation Index
> Fetch the complete documentation index at: https://docs.greip.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Payment Fraud Detection
> Prevent financial losses and protect your business by deploying AI-powered modules that analyze transaction patterns in real-time.
This method helps identify and block suspicious activities, mitigating the risk of fraudulent payments and ensuring a secure experience for both you and your customers.
export const MCPCallout = () => {
return
;
};
## Authentication
Include your API key in the `Authorization` header:
```http theme={null}
Authorization: Bearer
```
API v2 accepts the key only in this header, not in query parameters or request bodies. See [Authentication](/authentication).
Use `POST /score/payments`. The same request is supported at `POST /score/payment`.
### JSON body
The action your customer try to implement.
Accepts: `purchase`, `deposit`, or `withdrawal`.
The domain name of the website the customer trying to purchase from.
Sample value: `domain.com`
The name of the website the customer trying to purchase from.
Sample value: `Nike Store, California`
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`.
The identification code of the shipment.
The identification code of the transaction in your system.
The total amount of the transaction.
The currency in which the customer pay with.
Sample value: `GBP`
Set this to true if the customer is purchasing a digital product.
The promo code used by the customer to complete the checkout.
The identification number of the customer in your system.
The first name of the customer.
The last name of the customer (Family Name).
The Place of Birth of the customer.
The IP address of the customer.
The `ISO 3166-1 alpha-2` code format of the country where the customer live. [Learn more](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
The name of the region where the customer live.
The name of the city where the customer live.
The name of the zip code of customer location.
The "address line 1" of the customer.
The "address line 2" of the customer.
The customer latitude on the map (GPS Coordinates).
The customer longitude on the map (GPS Coordinates).
The device identification code of the customer.
The phone number of the customer (international format).
The registration date of the customer (UNIX Timestamp).
If you offer a Wallet feature in your website, then pass the user balance to this pararmeter.
The customer's date of birth.
Sample value: '1985-12-27\`
The email address of the customer.
Set this to true if the customer has 2FA enabled in his/her account.
Pass the [User Agent](https://en.wikipedia.org/wiki/User_agent) of the customer to this parameter.
The shipping country code of the customer (in `ISO 3166-1 alpha-2` format).
The shipping region name of the customer.
The shipping city name of the customer.
The zip code of the customer's shipping address.
The shipping "address 1" of the customer.
The shipping "address 2" of the customer.
The latitude of the customer's shipping address (GPS Coordinates).
The longitude of the customer's shipping address (GPS Coordinates).
The billing country code of the customer (in `ISO 3166-1 alpha-2` format).
The billing region name of the customer.
The billing city name of the customer.
The zip code of the customer's billing address.
The billing "address 1" of the customer.
The billing "address 2" of the customer.
The latitude of the customer's billing address (GPS Coordinates).
The longitude of the customer's billing address (GPS Coordinates).
The payment method used to complete this transaction.
Accepted values: `cards`, `cards_mada`, `applepay`, `stcpay`, `bank`, `crypto`, `wallet`, or `cod`.
The name on the card (Cardholder Name).
The card number (min: 6 digits).
The expiry date of the customer debit/credit card.
Sample value: 29/05
Set this to true if the customer passed the CVV/CSV verification process.
The format command is used to get a response in a specific format.
Expected values: `JSON`, `XML`, `CSV`, or `Newline`
For more information please refer to [Response format](/options/response-format).
The mode command is used in the development stage to simulate the integration process before releasing it to the production environment.
Expected values: `live`, or `test`.
For more information please refer to [Development environment](/options/development-environment).
Optional label for your own analytics or support correlation (for example a product or channel name).
```json Success theme={null}
{
"success": true,
"data": {
"score": 82,
"risk_level": "high",
"recommendation": "review",
"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`)."
}
],
"rules_checked": 21,
"rules_detected": 6,
"velocity": {
"ip_24h_count": 4,
"ip_7d_count": 12,
"email_24h_count": 1,
"email_7d_count": 2,
"phone_24h_count": 0,
"phone_7d_count": 3
},
"custom_rules_applied": { "total": 0, "rules": [] }
},
"execution_ms": 5
}
```
```json Error theme={null}
{
"success": false,
"code": 101,
"type": "invalid_key",
"description": "The API Key is missing or invalid."
}
```
### Response properties
`true` when the request succeeded; `false` on error.
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).
Overall risk band (`low`, `medium`, or `high`).
Suggested action (`accept`, `review`, or `reject`) derived from the risk assessment.
The Id of the detected rule. (`10.5` means it's `10.5% risky` to pass
this transaction).
Sample value: `PF10003`
The full description of the detected rule.
Sample value: `High purchase rate, according to "customer_id".`
Total rules checked against the transaction.
Total rules detected in the transaction.
Present when `customer_id` is set in the payment `data` object or when request `user_id` is provided. Counts recent scored payment requests for the same merchant scope (website domain and/or merchant id).
Scored payment requests sharing `customer_ip` in the last 24 hours.
Scored payment requests sharing `customer_ip` in the last 7 days.
Scored payment requests sharing `customer_email` in the last 24 hours.
Scored payment requests sharing `customer_email` in the last 7 days.
Scored payment requests sharing `customer_phone` and the same country code (`customer_country`, `billing_country`, or `shipping_country`) in the last 24 hours.
Scored payment requests sharing `customer_phone` and the same country code in the last 7 days.
The custom rules applied to this request, [learn
more](/knowledge-base/custom-rules/overview).
The total number of custom rules applied to this request.
The custom rules applied to this request, [learn
more](/knowledge-base/custom-rules/overview).
The rule ID as shown in the dashboard (e.g: `CR104`).
The rule title you set when creating the rule.
Time taken to process the request (milliseconds).
## OpenAPI
````yaml openapi/v2.json POST /score/payments
openapi: 3.0.3
info:
title: Greip API v2 (docs playground)
version: 2.0.0
servers:
- url: https://v2.greipapi.com
security: []
paths:
/score/payments:
post:
summary: Payment fraud detection
operationId: scorePayments
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: object
format:
type: string
mode:
type: string
source:
type: string
responses:
'200':
description: OK
security:
- bearerAuth: []
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.