Payment Fraud Detection API
Plug and protect. Score every payment in real time with Guardyen's AI and get a clear approve, review or decline recommendation in under 40ms.
Quick start
- 01
Send payment details to /v1/fraud/score before authorisation.
- 02
Act on the recommendation: approve, review or decline.
- 03
Send chargebacks and confirmed fraud to /v1/fraud/feedback.
Endpoints
POST
/v1/fraud/scoreGet an AI risk score for a payment.
| Field | Type | Description |
|---|---|---|
| payment_id* | string | Your payment reference. |
| amount* | integer | Amount in minor units. |
| currency* | string | ISO 4217 code. |
| string | Customer email. | |
| ip | string | Customer IP address. |
| card_fingerprint | string | Tokenised card fingerprint. |
| device_id | string | From the Guardyen JS device SDK. |
Request
curl -X POST https://api.guardyen.com/v1/fraud/score \
-H "Authorization: Bearer gy_test_sk_..." \
-H "Content-Type: application/json" \
-d '{"payment_id":"pay_7731","amount":12900,"currency":"USD","email":"jo@example.com","ip":"203.0.113.9"}'Response 200
{
"score_id": "fs_01HF4A2B",
"risk_score": 74,
"recommendation": "review",
"signals": ["ip_country_mismatch", "new_device", "velocity_high"],
"latency_ms": 28
}POST
/v1/fraud/feedbackTell the AI the true outcome.
| Field | Type | Description |
|---|---|---|
| payment_id* | string | Payment you scored. |
| label* | enum | fraud | chargeback | legitimate |
| reason_code | string | Network chargeback reason code. |
Request
curl -X POST https://api.guardyen.com/v1/fraud/feedback \
-H "Authorization: Bearer gy_test_sk_..." \
-H "Content-Type: application/json" \
-d '{"payment_id":"pay_7731","label":"chargeback","reason_code":"10.4"}'Response 200
{ "received": true }GET
/v1/fraud/rulesList your custom rules.
Request
curl -X GET https://api.guardyen.com/v1/fraud/rules \
-H "Authorization: Bearer gy_test_sk_..." \
-H "Content-Type: application/json"Response 200
{
"rules": [
{ "id": "rule_1", "if": "risk_score >= 85", "then": "decline", "active": true }
]
}PUT
/v1/fraud/rules/{id}Create or update a rule.
| Field | Type | Description |
|---|---|---|
| if* | string | Condition, e.g. "amount > 50000 AND new_device". |
| then* | enum | approve | review | decline |
| active | boolean | Defaults to true. |
Request
curl -X PUT https://api.guardyen.com/v1/fraud/rules/rule_2 \
-H "Authorization: Bearer gy_test_sk_..." \
-H "Content-Type: application/json" \
-d '{"if":"amount > 50000 AND new_device","then":"review"}'Response 200
{ "id": "rule_2", "active": true }Error codes
| Code | HTTP | Meaning |
|---|---|---|
| FRD_INVALID_CARD | 400 | card_fingerprint is malformed. |
| FRD_SCORE_TIMEOUT | 504 | Scoring exceeded your timeout; fallback decision applied. |
| FRD_RULE_SYNTAX | 422 | The rule condition could not be parsed. |
Webhook
Event fraud.review.required is sent to your webhook endpoint.
Payload
{
"type": "fraud.review.required",
"data": { "payment_id": "pay_7731", "risk_score": 74 }
}