API Reference

1// POST /v1/transactions/score (API key; server-to-server only)
2const response = await fetch('https://api.maiguard.com/v1/transactions/score', {
3  method: 'POST',
4  headers: {
5    'Content-Type': 'application/json',
6    'Authorization': 'Bearer pk_live_<your-key>',
7    'Idempotency-Key': 'order-987654-score-v1',  // optional; dedup 24 h
8  },
9  body: `{
10  "amount": 50000.50,
11  "userId": "cust_61e46cf7",
12  "currency": "NGN",
13  "occurredAt": "2026-05-29T10:30:00.000Z",
14  "ipAddress": "197.210.84.42",
15  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
16  "deviceId": "7ec1a4175dd3776f4cb534b1287749811b5512ad60f5d0ba1f10c7974ffd2edc",
17  "deviceSessionId": "ds_g7xSevOyd2oUAQCfVuya0g",
18  "location": {
19    "latitude": 6.4474,
20    "longitude": 3.3903
21  },
22  "metadata": {
23    "countryCode": "NG",
24    "receiverId": "rcv_beneficiary_001",
25    "product": "Collections",
26    "paymentMethod": "card",
27    "environment": "LIVE",
28    "type": "purchase",
29    "merchantId": "merchant_456",
30    "category": "electronics",
31    "orderId": "ord_987654",
32    "channel": "web"
33  }
34}`,
35});

1// POST /v1/transactions/batch-score
2// Sync (≤100 items): immediate results. Async: ?async=true or >100 → 202 + jobId
3const response = await fetch('https://api.maiguard.com/v1/transactions/batch-score?async=false', {
4  method: 'POST',
5  headers: {
6    'Content-Type': 'application/json',
7    'Authorization': 'Bearer pk_live_<your-key>',
8  },
9  body: `{
10  "transactions": [
11    { "amount": 5000, "userId": "user_01", "currency": "NGN", "includeMatchedConditions": true },
12    { "amount": 25000, "userId": "user_02", "currency": "USD" }
13  ],
14  "idempotencyKeys": ["idem-01", "idem-02"]
15}`,
16});

1// POST /v1/events/login — call on every login attempt (success or failed)
2// MaiGuard stores counters in Redis; auto-attached to the next score for this userId.
3
4// Failed attempt:
5await fetch('https://api.maiguard.com/v1/events/login', {
6  method: 'POST',
7  headers: {
8    'Content-Type': 'application/json',
9    'Authorization': 'Bearer pk_live_<your-key>'
10  },
11  body: JSON.stringify({
12    userId: 'cust_abc123xyz',
13    outcome: 'failed',
14    ipAddress: '203.0.113.42',
15    deviceId: 'dev_fingerprint_abc789',
16    occurredAt: new Date().toISOString()
17  })
18});
19
20// Successful login:
21await fetch('https://api.maiguard.com/v1/events/login', {
22  method: 'POST',
23  headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer pk_live_<your-key>' },
24  body: JSON.stringify({ userId: 'cust_abc123xyz', outcome: 'success', occurredAt: new Date().toISOString() })
25});

1// PUT /v1/customers/:customerId/onboard (same ID as userId in scoring)
2const response = await fetch('https://api.maiguard.com/v1/customers/customer_001/onboard', {
3  method: 'PUT',
4  headers: {
5    'Content-Type': 'application/json',
6    'Authorization': 'Bearer pk_live_<your-key>',
7  },
8  body: `{
9  "riskProfile": "medium",
10  "partnerOnboardedAt": "2025-06-01T00:00:00.000Z",
11  "countryCode": "NG",
12  "entityType": "individual",
13  "displayName": "Amara Osei",
14  "kycStatus": "verified",
15  "kycTier": 2,
16  "pep": false,
17  "expectedVolume": 5000000,
18  "expectedVolumePeriod": "monthly"
19}`,
20});

// GET /v1/transactions (API key or JWT: transactions.view)
const response = await fetch('https://api.maiguard.com/v1/transactions?page=1&limit=20&decision=BLOCK&riskScoreMin=70&environment=LIVE&sortBy=createdAt&sortOrder=desc', {
  headers: {
    'Authorization': 'Bearer pk_live_<your-key>',
  },
});