Sample API — v1

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

  1. 01

    Enroll each merchant with /v1/merchants.

  2. 02

    Stream or batch their transactions to Guardyen.

  3. 03

    Subscribe to the merchant.alert.created webhook.

Endpoints

POST/v1/merchants

Enroll a merchant for monitoring.

FieldTypeDescription
merchant_id*stringYour merchant reference.
legal_name*stringRegistered business name.
mcc*stringMerchant category code.
country*stringISO 3166 alpha-2.
expected_monthly_volumeintegerBaseline 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}/risk

Current AI risk profile.

FieldTypeDescription
id*stringMerchant 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}/alerts

List alerts for a merchant.

FieldTypeDescription
statusenumopen | acknowledged | closed
limitinteger1–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

CodeHTTPMeaning
MFI_DUPLICATE_MERCHANT409A merchant with this merchant_id is already enrolled.
MFI_BASELINE_PENDING425Not enough history yet to score this merchant.
MFI_INVALID_MCC400mcc 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" }
}