Merchant Fraud Intelligence API
Enroll your merchants and let Guardyen's AI watch their behaviour around the clock. Get alerts when volumes, refunds, ticket sizes or descriptors change in suspicious ways.
Quick start
- 01
Enroll each merchant with /v1/merchants.
- 02
Stream or batch their transactions to Guardyen.
- 03
Subscribe to the merchant.alert.created webhook.
Endpoints
POST
/v1/merchantsEnroll a merchant for monitoring.
| Field | Type | Description |
|---|---|---|
| merchant_id* | string | Your merchant reference. |
| legal_name* | string | Registered business name. |
| mcc* | string | Merchant category code. |
| country* | string | ISO 3166 alpha-2. |
| expected_monthly_volume | integer | Baseline in minor units. |
Request
curl -X POST https://api.guardyen.com/v1/merchants \
-H "Authorization: Bearer gy_test_sk_..." \
-H "Content-Type: application/json" \
-d '{"merchant_id":"m_2041","legal_name":"Northwind Goods Ltd","mcc":"5732","country":"CY"}'Response 200
{ "merchant_id": "m_2041", "status": "monitoring", "baseline_ready_in_days": 7 }GET
/v1/merchants/{id}/riskCurrent AI risk profile.
| Field | Type | Description |
|---|---|---|
| id* | string | Merchant reference (path). |
Request
curl -X GET https://api.guardyen.com/v1/merchants/m_2041/risk \
-H "Authorization: Bearer gy_test_sk_..." \
-H "Content-Type: application/json"Response 200
{
"merchant_id": "m_2041",
"risk_level": "elevated",
"risk_score": 63,
"drivers": ["refund_rate_up_3x", "new_high_risk_countries"]
}GET
/v1/merchants/{id}/alertsList alerts for a merchant.
| Field | Type | Description |
|---|---|---|
| status | enum | open | acknowledged | closed |
| limit | integer | 1–100, default 20. |
Request
curl -X GET https://api.guardyen.com/v1/merchants/m_2041/alerts \
-H "Authorization: Bearer gy_test_sk_..." \
-H "Content-Type: application/json"Response 200
{
"alerts": [
{ "id": "al_551", "type": "volume_spike", "severity": "high", "opened_at": "2026-11-10T08:12:00Z" }
]
}Error codes
| Code | HTTP | Meaning |
|---|---|---|
| MFI_DUPLICATE_MERCHANT | 409 | A merchant with this merchant_id is already enrolled. |
| MFI_BASELINE_PENDING | 425 | Not enough history yet to score this merchant. |
| MFI_INVALID_MCC | 400 | mcc is not a valid merchant category code. |
Webhook
Event merchant.alert.created is sent to your webhook endpoint.
Payload
{
"type": "merchant.alert.created",
"data": { "merchant_id": "m_2041", "alert_id": "al_551", "type": "volume_spike", "severity": "high" }
}