Sample API — v1

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

  1. 01

    Send payment details to /v1/fraud/score before authorisation.

  2. 02

    Act on the recommendation: approve, review or decline.

  3. 03

    Send chargebacks and confirmed fraud to /v1/fraud/feedback.

Endpoints

POST/v1/fraud/score

Get an AI risk score for a payment.

FieldTypeDescription
payment_id*stringYour payment reference.
amount*integerAmount in minor units.
currency*stringISO 4217 code.
emailstringCustomer email.
ipstringCustomer IP address.
card_fingerprintstringTokenised card fingerprint.
device_idstringFrom 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/feedback

Tell the AI the true outcome.

FieldTypeDescription
payment_id*stringPayment you scored.
label*enumfraud | chargeback | legitimate
reason_codestringNetwork 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/rules

List 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.

FieldTypeDescription
if*stringCondition, e.g. "amount > 50000 AND new_device".
then*enumapprove | review | decline
activebooleanDefaults 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

CodeHTTPMeaning
FRD_INVALID_CARD400card_fingerprint is malformed.
FRD_SCORE_TIMEOUT504Scoring exceeded your timeout; fallback decision applied.
FRD_RULE_SYNTAX422The 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 }
}