ArcheaOne Documentation

ArcheaOne adds real-time fraud detection to your payment flow. Before a transaction is processed, you send it to ArcheaOne and get a fraud decision back in milliseconds: BLOCK, REVIEW or ALLOW.

You keep full ownership of your transactions, logins and account flows. At the moments where you want a risk decision, you send an event. ArcheaOne scores it with a rules engine and a machine-learning anomaly model working together, and returns a decision with reasons. The model can escalate an ALLOW to REVIEW, but never relaxes a rule decision.

Blocked activity also appears as an alert in your dashboard, and signed webhooks go out to your systems.

Common integration patterns

• Synchronous gate on money movement. Call assess/transaction before you commit the debit. On BLOCK, stop. On REVIEW, hold the transaction for manual release. On ALLOW, proceed.
• Asynchronous enrichment on login. Call assess/access after a login attempt without blocking on it, and let the webhook drive any follow-up, such as step-up MFA or a forced password reset.
• Passive observability on everything else. Send events through assess to build up a behavioural baseline, and start gating later.

1. Get an account. Request access and we will set up your organisation.
2. Create an API key. In the dashboard, go to API Keys → Create. Copy the full key right away, because only its prefix can be shown later.
3. Pick a mode.
   • Test mode (keys start with rsk_test_): sandbox traffic. Test calls don't count toward your monthly usage and have no monthly cap.
   • Live mode (keys start with rsk_live_): production traffic. Every successful live assessment counts toward your plan's monthly usage (see Usage and billing).
4. Send your first transaction (see Evaluate a transaction).
5. Check the dashboard. Open Fraud Alerts. A blocked event appears at the top of the list within a couple of seconds.
6. Optional: set up alert delivery by email, Slack or your own webhook (see Alerts and webhooks).

Base URL

https://api.archeaone.com/api/v1

Send your API key with every request, in either header:

x-api-key: rsk_test_...

Authorization: Bearer rsk_test_...

• The key identifies your organisation. Don't send an organizationId in the request body: unknown fields are rejected with 400. You may send an x-organization-id header, but it must match the key's organisation, or the call fails with 401.
• Only call the API from your backend. Never ship an API key in a mobile app or browser code.
• A missing, invalid, expired or revoked key returns 401.

Use this for money movement: transfers, payments, payouts, debits, credits and refunds.

Request body

All fields are required unless marked optional. Fields not listed here are rejected with 400. Put any extra context in metadata.

actor

device

simSwap (optional)

Payments and logins made soon after a customer's SIM card was swapped are a common sign of account takeover. If you already check SIM swap status, for example through the NIBSS SIM swap service, send the result here and ArcheaOne will take it into account. A recent swap adds the SIM_SWAP_RECENT reason code. It raises the risk but does not block on its own, so a customer who genuinely replaced a lost SIM is sent for review rather than refused. Works on transaction and login events.

"simSwap": {
  "lastSwappedAt": "2026-10-13T08:30:00Z",
  "source": "NIBSS"
}

Examples

curl -X POST "https://api.archeaone.com/api/v1/risk-assessment/assess/transaction" \
  -H "Content-Type: application/json" \
  -H "x-api-key: rsk_test_..." \
  -d '{
    "eventId": "evt_001",
    "eventType": "TRANSACTION",
    "timestamp": "2026-06-03T15:00:00.000Z",
    "transactionId": "txn_456",
    "accountId": "acc_demo_001",
    "amount": 50000,
    "currency": "NGN",
    "status": "PENDING",
    "transactionType": "TRANSFER",
    "actor": {
      "userId": "user_123",
      "userType": "CUSTOMER",
      "email": "customer@example.com"
    },
    "device": {
      "deviceId": "dev_abc123",
      "sessionId": "sess_xyz789",
      "deviceName": "iPhone 14",
      "deviceType": "MOBILE",
      "deviceToken": "token_abc",
      "os": "iOS 17",
      "location": {
        "latitude": 6.5244, "longitude": 3.3792,
        "country": "NG", "city": "Lagos"
      },
      "lastSeen": "2026-06-03T15:00:00.000Z"
    }
  }'

Response

The default response is kept small: it contains only what your application needs to act on a decision.

{
  "status": 200,
  "message": "Transaction risk assessment completed",
  "data": {
    "assessmentId": "RISK-...",
    "eventId": "evt_001",
    "userId": "user_123",
    "decision": "BLOCK",
    "riskScore": 87,
    "riskLevel": "CRITICAL",
    "reasons": [
      "Transaction from new country: RU"
    ],
    "reasonCodes": [
      "GEOGRAPHIC_ANOMALY", "UNUSUAL_AMOUNT"
    ],
    "assessedAt": "2026-06-03T15:00:00.000Z",
    "assessor": "SYSTEM",
    "metadata": {
      "processingTimeMs": 124
    }
  }
}

Don't branch on message; its wording differs between endpoints.

More operational detail (optional)

Append ?include=metadata to get a few more operational fields. It doesn't cost anything extra; it's the same single call.

"metadata": {
  "processingTimeMs": 124,
  "evaluatedRules": 2,
  "eventType": "TRANSACTION",
  "mode": "test",
  "profileAge": 42,
  "location": { "latitude": 6.5244, "longitude": 3.3792, "country": "NG", "city": "Lagos" },
  "deviceId": "dev_abc123"
}

evaluatedRules is the number of rules that fired. profileAge is the age of the end user's behaviour profile in days. location and deviceId echo what you sent.

Login and access events

Takes the same eventId, eventType ("ACCESS"), timestamp, actor, device and optional correlationId / metadata fields as a transaction, plus:

Any other event

Takes only the common fields (eventId, eventType, timestamp, actor, device, and optional correlationId / metadata). Put any event-specific details in metadata. Behavioural rules run for eventType values BEHAVIOR and ACCOUNT. Other event types are stored to build the user's history, but no built-in rules run on them, so they return ALLOW.

All three endpoints return the same response shape.

Reason codes

New codes may be added over time, so treat unknown codes as informational rather than as errors.

Every error returns the same JSON shape. message is a string, or for validation errors, an array of strings.

{
  "status": 400,
  "message": ["actor.userId should not be empty", "property organizationId should not exist"],
  "timestamp": "2026-06-03T15:00:00.000Z",
  "path": "/api/v1/risk-assessment/assess/transaction"
}

Rate limits

The assessment endpoints (assess, assess/transaction, assess/access) accept, per client IP address:

Going over any window returns 429. Back off and retry. If you need higher limits, contact support.

Timeouts and fallback

Set a client timeout on every call (the Python example uses 5 seconds) and decide in advance what happens if ArcheaOne is unreachable or returns 5xx: either let the transaction through (fail open) or hold it for review (fail closed). Most teams fail open for low-value transactions and fail closed for high-value ones.

One API call is one successful live-mode assessment: a 200 response from assess/transaction, assess/access or assess made with an rsk_live_ key.

Monthly limits by plan

Usage resets at 00:00 UTC on the 1st of each month. When you reach your limit, further live calls return 403 until the next month or until you upgrade. Retries of events already scored within 24 hours still return their result. There are no automatic overage charges. Your dashboard shows this month's usage and when it resets.

When an assessment returns BLOCK, ArcheaOne:

• creates a fraud alert in your dashboard;
• sends a signed webhook to each active endpoint subscribed to HIGH_RISK_DETECTED;
• emails your organisation's contact address when the risk level is HIGH or CRITICAL (you can turn this off in Settings).

Alerts from test-mode traffic appear in your dashboard and go only to webhooks you created with a test key. They never send email, so you can test safely without paging your production channels.

Repeated blocks for the same user and event type within a short cool-down window produce one alert, not many. Pattern detection can also raise alerts: critical patterns are sent as HIGH_RISK_DETECTED, and others as ALERT_CREATED.

Set up webhooks in the dashboard under Webhooks. Choose a generic JSON format for your own systems, or a Slack format for a Slack incoming-webhook URL.

Webhook request

POST <your URL>
Content-Type: application/json
X-Webhook-Event: HIGH_RISK_DETECTED
X-Webhook-Signature: <hex HMAC-SHA256 of the raw body>

{
  "event": "HIGH_RISK_DETECTED",
  "data": {
    "assessmentId": "RISK-...",
    "userId": "user_123",
    "riskScore": 87,
    "riskLevel": "CRITICAL",
    "severity": "CRITICAL",
    "alertType": "HIGH_RISK_TRANSACTION",
    "description": "Risk score 87/100 — decision: BLOCK",
    "decision": "BLOCK",
    "reasons": ["Transaction from new country: RU"],
    "reasonCodes": ["GEOGRAPHIC_ANOMALY"]
  },
  "timestamp": "2026-06-03T15:00:01.000Z",
  "webhookId": "..."
}

data may contain additional fields; ignore any you don't use.

Verifying signatures

The signature is an HMAC-SHA256 of the raw request body using your webhook secret. Compute it over the exact bytes you received, before parsing the JSON.

const crypto = require('crypto');

// Express: app.post('/archea', express.raw({ type: 'application/json' }), handler)
function isValid(rawBody, signatureHeader, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader || ''));
}

Delivery and retries

• Respond with any 2xx within 5 seconds. Anything else counts as a failure.
• Failed deliveries are tried 3 times in total: once immediately, then again after about 5 seconds and about 25 seconds.
• After 10 consecutive failures, the webhook is automatically disabled. Re-enable it in the dashboard once your endpoint is fixed.
• Use the Test button in the dashboard to send a TEST delivery.

Need help integrating? Email support.archeaone@cycloudforte.com.