Build on the Kupinga anti-fraud platform.

Overview

A staging-first integration package for banks and PSPs who want to validate the platform before signing the production contract.

Everything in this documentation is sized for a senior integration engineer who has the staging URL https://staging.kupinga.net, a contact email, and one to two days to prove the integration end-to-end.

What you can do with this API

• Score transactions in real time — submit a transaction, get back an approve / decline / challenge decision in under 300 ms (p50). Per-channel routes for POS, ATM, USSD, internet banking, and mobile app.
• Look up decisions later — every decision is durable and addressable by UUID. Supports ETag / If-None-Match for cheap revalidation.
• Search customers — by name, email, or hashed BVN. Pull the customer 360 view (profile, KYC tier, screening status, registered accounts).
• Subscribe to events — webhook delivery of decision.created, case.created, case.resolved, and alert.created with HMAC signing and automatic retry.

5-line quickstart

The fastest path from zero to a live decision against staging:

# 1. Log in as the integration user the platform admin provisioned for you.
curl -X POST https://staging.kupinga.net/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"tester@example.com","password":"$YOUR_PASSWORD"}'
#    => returns {"access_token":"eyJ...","refresh_token":"...","expires_in":900,...}

# 2. Mint a server-to-server API key (use the access_token from step 1).
curl -X POST https://staging.kupinga.net/api/v1/api-keys \
  -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name":"smoke-test","merchant_id":"DEMO_MERCHANT","tier":"standard","scopes":["evaluate","decisions:read"]}'
#    => returns {"key":"af_live_...","api_key":{...}}  -- save "key" NOW, you cannot read it again.

# 3. Score a transaction.
curl -X POST https://staging.kupinga.net/api/v1/evaluate \
  -H 'Authorization: Bearer $API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'X-Idempotency-Key: 11111111-1111-1111-1111-111111111111' \
  -d '{"external_id":"smoke-001","merchant_id":"DEMO_MERCHANT","amount":12500,"currency":"NGN","channel":"pos","card_bin":"506099","terminal_id":"DEMO0001","entry_mode":"chip","emv_cryptogram_present":true}'
#    => returns {"transaction_id":"...","decision_id":"...","outcome":"approve","risk_score":...}

# 4. Read the decision back.
curl https://staging.kupinga.net/api/v1/decisions/$DECISION_ID \
  -H 'Authorization: Bearer $API_KEY'

# 5. (Optional) request a webhook subscription by emailing the contact below
#    with your callback URL, the events you want, and the IP range we should
#    expect deliveries from.

Endpoint map

Decision outcomes

risk_score ranges 0–100. The thresholds that map score → outcome are owned by the platform's rules + ML pipeline; clients should trust the outcome field rather than re-deriving from the score.

Conventions used in these docs

• Code blocks are copy-ready. The copy button in the top-right corner of each block writes the entire block to your clipboard.
• Endpoint chips show the HTTP method (colour-coded) + path + required scope. Scope names map to the permission catalogue at internal/auth/permissions.go.
• Hashes are 64-character lowercase hex (HMAC-SHA256 or SHA-256, depending on the field). Always send hashes, never raw PII.
• Times are RFC 3339 in UTC unless noted otherwise.
• Press ⌘ K (or Ctrl K) any time to search this site.

Tenant setup

What the platform operator does before handing you credentials. You don't run any of this — it lives here so you know what's already done on your behalf.

The deliverable

The operator hands you a single email containing:

1. The staging base URL: https://staging.kupinga.net
2. A maker username + initial password
3. A checker username + initial password
4. The merchant identifier you'll send on every transaction
5. The list of feature flags / scopes you're contracted for
6. A link to this onboarding package

Pre-flight

Before provisioning, the operator confirms with the contract:

• Signed DPA (data-processing agreement) on file
• Production tier (starter / standard / premium / unlimited) negotiated
• Channels in scope (POS-only / multi-channel)
• Webhook URLs collected (callback host, optional IP range the platform will deliver from)
• Production go-live date

The staging tier is always standard regardless of production tier — enough headroom to load-test without distorting the production cost picture.

Step 1 — provision the tenant row

The platform is single-tenant on the data plane (tenant_id = 1). "Tenant" here means a merchant scope. Values set at this step:

• merchant_id — an opaque short string (e.g. BANK_ALPHA_NG). You'll send this on every /evaluate call.
• Feature flags — screening (sanctions + PEP), ml_scoring (model registry), webhooks_self_service (admin-only today).

Step 2 — initial users

The operator creates two accounts in the admin console (/admin/users):

• One maker (role analyst / senior_analyst) — mints API keys, runs smoke tests, configures webhooks.
• One checker (role compliance_officer / admin) — approves key rotations and webhook changes.

The maker-checker separation is enforced at the DB layer for sensitive operations (block lifts, screening approvals, outbox replays).

Initial passwords MUST be at least 16 characters, generated by a CSPRNG (e.g. openssl rand -base64 24), communicated out-of-band (encrypted email, password-manager share — never plaintext SMS), and force a change at first login.

Step 3 — enable contracted features

Canonical catalogue lives at internal/auth/permissions.go.

Step 4 — IP allowlisting (optional)

If you provided an IP range:

• Mint the API key with allowed_cidrs populated (IPv4 + IPv6, up to 50 entries, CIDR or bare IP).
• Document the range in the runbook.
• Confirm API_KEYS_ENFORCE_ALLOWLIST=true on the tenant's fraud-engine config if you want the gateway to reject mismatches; otherwise mismatches are audited but not blocked.

Without an allowlist any IP can present the API key. Most banks require allowlisting before production sign-off; staging usually runs without it for convenience.

Step 5 — webhook scaffolding (optional)

If the contract includes webhooks, the operator pre-creates a draft subscription:

• POST /admin/webhooks with status: draft, the client's target URL, and a secret_ref pointing to a Vault path.
• Seed the HMAC secret in Vault at the secret_ref path.

You then PATCH /admin/webhooks/{id} with status: active once your endpoint is verified.

Step 6 — welcome email

Subject: Antifraud staging access — <CLIENT_NAME>

Hi <NAME>,

Your staging access is provisioned. Endpoint:

  https://staging.kupinga.net

Credentials (please change at first login):

  Maker  : <MAKER_EMAIL>     / <INITIAL_PASSWORD>
  Checker: <CHECKER_EMAIL>   / <INITIAL_PASSWORD>

Your merchant_id is: <MERCHANT_ID>
This goes in every /evaluate request body.

Feature scope: <FEATURE_LIST>
Production tier: <TIER>

Integration package (Postman collection, examples, full docs):
  <link to /developers/>

Test plan we expect green before production cutover:
  - Postman collection passes top-to-bottom in Runner
  - Webhook signing verified against your verifier
  - Idempotency verified under retry storm
  - Capacity test at your contracted tier RPS, 5 minutes sustained

Reach out at integration@<your-domain> if anything is unclear.

— Antifraud platform team

Step 7 — log the provisioning event

Audit row in users.access_log:

INSERT INTO users.access_log
  (kind, actor_user_id, target, payload, created_at)
VALUES
  ('tenant.provisioned', <YOUR_USER_ID>,
   '<MERCHANT_ID>', '{"client":"<CLIENT_NAME>","tier":"<TIER>"}'::jsonb,
   NOW());

This is what the audit team reviews on production cutover. Don't skip it.

Creating API keys

API keys are how your server identifies itself to ours. JWTs (from /auth/login) are for the integration engineer's interactive testing; API keys are for the production rig.

1. Get a JWT first

API-key creation is gated by api_keys:write and runs behind the JWT-authenticated admin surface — you can't create a key with a key. Log in first.

curl -X POST https://staging.kupinga.net/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"tester@example.com","password":"$YOUR_PASSWORD"}'

Response (truncated):

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "rt_eyJ...",
  "token_type": "Bearer",
  "expires_in": 900,
  "user": {
    "id": "0f0e0d0c-0b0a-0908-0706-050403020100",
    "email": "tester@example.com",
    "role": "admin",
    "status": "active"
  }
}

The access token is good for 15 minutes (expires_in: 900). Refresh tokens last 7 days — rotate through /auth/refresh.

2. Create the key

curl -X POST https://staging.kupinga.net/api/v1/api-keys \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-rig-primary",
    "merchant_id": "BANK_ALPHA_NG",
    "tier": "standard",
    "scopes": ["evaluate", "decisions:read", "customers:read"],
    "expires_at": "2027-05-25T00:00:00Z",
    "allowed_cidrs": ["203.0.113.0/24", "198.51.100.42"]
  }'

Request fields

Response shape

{
  "key": "af_live_4e6b7f3a2c8d1e5f9a0b6c2d4e8f1a3b5c7d9e0f...",
  "api_key": {
    "id": "5d8c9b0a-1234-5678-90ab-cdef01234567",
    "key_prefix": "af_live_4e6b7f3a",
    "name": "production-rig-primary",
    "merchant_id": "BANK_ALPHA_NG",
    "scopes": ["evaluate", "decisions:read", "customers:read"],
    "tier": "standard",
    "is_active": true,
    "expires_at": "2027-05-25T00:00:00Z",
    "last_used_at": null,
    "revoked_at": null,
    "created_at": "2026-05-25T11:42:13.041Z"
  },
  "created_at": "2026-05-25T11:42:13.041Z",
  "warning": "store this key securely — it cannot be retrieved again"
}

The key_prefix field is what shows up in audit logs and the admin console — useful for spotting which key generated a particular log line without exposing the whole secret.

3. Stash the key securely

Drop the raw key into a secret manager (HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager — anything the rest of your platform already uses). Read it into the runtime from there, not from a config file checked into git.

export ANTIFRAUD_API_KEY="$(vault kv get -field=key secret/antifraud/staging)"

Then never echo / log / commit the value. The audit team will look for it on every routine review; finding it in a git history is a contract-violation event.

4. Scopes

Scopes pin what the key can do. The platform's permission catalogue is enumerated in internal/auth/permissions.go. The subset you typically need on a client integration:

Scopes follow least-privilege: if your integration only ever scores transactions and never reads them back, ask for evaluate alone. Adding customers:read "just in case" gets flagged in our reviews.

5. Tier guidance

Tier is enforced at the gateway. Exceeding it returns 429 with Retry-After. See rate limits & errors for the response shape.

6. Listing your keys

curl https://staging.kupinga.net/api/v1/api-keys \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Returns every key you created (admins see every key in the system). Each entry has the same api_key shape from step 2. The raw key is never in this response. Use last_used_at to spot keys that have gone stale and can be revoked.

7. Rotation

Rotate keys quarterly at minimum. Recommended flow:

1. Mint a new key with the same scopes and tier (different name, e.g. production-rig-primary-v2).
2. Deploy to half your fleet. Observe traffic on the new key_prefix in last_used_at.
3. Deploy to the rest of the fleet.
4. Wait 24 hours.
5. Revoke the old key.

The 24-hour overlap window covers nodes that missed the rollout. Without it, those nodes start returning 401 the moment the old key dies. If a key is suspected compromised, skip the overlap and revoke immediately.

8. Revoking a key

curl -X DELETE \
  https://staging.kupinga.net/api/v1/api-keys/{public_id} \
  -H "Authorization: Bearer $ACCESS_TOKEN"

public_id is the id field from the create response (a UUID, not the key_prefix).

A revoked key returns 401 invalid_credentials on every subsequent request. Revocation is immediate; no caching, no propagation delay.

Authentication

Two credential types, one wire format. Both present as Authorization: Bearer <token>.

The platform's auth middleware tries JWT verification first; if that fails, it tries API-key verification. Most production traffic hits the API-key path on the first attempt.

API key (server-to-server)

curl https://staging.kupinga.net/api/v1/evaluate \
  -H "Authorization: Bearer af_live_4e6b7f3a2c8d1e5f9a0b..." \
  -H "Content-Type: application/json" \
  -d '{"external_id":"...","merchant_id":"BANK_ALPHA_NG","amount":12500,"currency":"NGN","channel":"pos","card_bin":"506099"}'

That's all. No nonce, no signature header, no body hashing — TLS 1.2+ is the transport security. The platform refuses cleartext HTTP (requireSecureTransport middleware responds 403).

Recommended client patterns

• Store the key in your secret manager, not in source control. Read it at boot via the secret manager's SDK (Vault Agent, AWS Secrets Manager, GCP Secret Manager).
• Pin the key into one process, not the whole node. A per-process env variable beats a shared /etc/antifraud/key file.
• Mask the key in your logs. Print only the prefix (af_live_4e6b7f3a) when you need to identify which key issued a request.
• Watch last_used_at. A production key untouched for 7 days is probably orphaned.

IP allowlisting

Each API key carries an optional allowed_cidrs list — a set of CIDR ranges (IPv4 or IPv6, or single addresses normalised to /32 / /128). At authentication time the gateway compares the caller IP to that list:

• Empty list — any source IP can present the key. Default for new keys unless you ask otherwise.
• Non-empty list, IP in range — request proceeds normally.
• Non-empty list, IP not in range — gateway returns 401 invalid_credentials, the exact same shape as a wrong-key response. We deliberately do not distinguish the two cases; a stolen key cannot be probed against the allowlist boundary to confirm validity.

Enforcement is gated per-environment by API_KEYS_ENFORCE_ALLOWLIST. Until that switch is on in your environment, the gateway records mismatches in the audit log but does not block.

JWT (interactive)

# Login — exchanges email+password for an access+refresh pair
curl -X POST https://staging.kupinga.net/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"tester@example.com","password":"$YOUR_PASSWORD"}'

# Refresh — burns the supplied refresh token and returns a new pair
curl -X POST https://staging.kupinga.net/api/v1/auth/refresh \
  -H 'Content-Type: application/json' \
  -d '{"refresh_token":"rt_eyJ..."}'

# Logout — invalidates the refresh token
curl -X POST https://staging.kupinga.net/api/v1/auth/logout \
  -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"refresh_token":"rt_eyJ..."}'

Login response

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "rt_eyJ...",
  "token_type": "Bearer",
  "expires_in": 900,
  "user": {
    "id": "5d8c9b0a-1234-5678-90ab-cdef01234567",
    "email": "tester@example.com",
    "first_name": "Test",
    "last_name": "Engineer",
    "display_name": "Test Engineer",
    "role": "admin",
    "status": "active"
  }
}

Important JWT behaviours

• 15-minute access token. Once it expires every call returns 401 token_expired. Use the refresh endpoint; don't re-login.
• Refresh-token rotation. Every successful /auth/refresh invalidates the supplied refresh token and issues a fresh pair. Using the same refresh token twice fails with token_revoked — that's the rotation-replay defence.
• Permission re-read on refresh. When refresh succeeds, the new access token carries your current permission set from the DB, not the set you had at the original login. A permission granted by the admin between logins is picked up on the next refresh.
• Account lockout. Five consecutive failed logins lock the account for 15 minutes. The wire response is identical to bad-password to avoid leaking which users are deactivated.
• Login rate limit. 10 attempts per minute per IP. Exceeding returns 429.

Logout

POST /auth/logout invalidates the refresh token (blacklist with TTL = the token's remaining lifetime). The access token is still valid until it expires naturally (15 minutes); there is no server-side revocation list for access tokens because the short TTL makes it unnecessary.

Which one should I use?

• Integration / smoke testing from a developer laptop → JWT. Log in as the maker user the platform admin provisioned.
• Postman against staging → JWT. The collection's Login request populates {{accessToken}} automatically.
• Production server posting transactions → API key. Mint one per environment (staging + production = two keys minimum).
• CI smoke job against staging → API key. No password to manage, no expiry to worry about.

Don't mix the two on the same call. The platform tries JWT first; if you present an API key shaped like af_live_... in the JWT position, the JWT verifier fails fast and the API-key verifier takes over, but the failure path costs an extra ~1 ms — not enough to matter for low volume, enough to show up in a load test.

Failure modes

The 401 vs 403 distinction matters for retry logic: 401 is an authentication failure (you can't keep retrying with the same credential); 403 is an authorisation failure (your credential is valid but the operation isn't allowed — don't retry, escalate).

Evaluating transactions

The endpoint your integration spends most of its time talking to.

Per-channel routes are functionally equivalent to POST /evaluate with the channel pinned from the URL. They give you slightly clearer per-channel error messages ("terminal_id is required for POS" rather than the generic card-channel error) and run inside a per-channel rate-limit bucket. Use them when you can; use the catch-all /evaluate when one endpoint has to handle every channel.

Required fields

Every field maps to a column on core.transactions. Length limits mirror DB column widths; a payload that validates here will not trip a database constraint at insert time.

Channel & payment context (recommended)

Customer

Card

Terminal / POS

ATM (channel = atm)

Account-to-account (NIP / RTGS / intra_bank / ACH / cheque)

These channels require both source AND destination identifiers. The platform accepts two equivalent field families — either works:

The 10-digit NUBAN is validated with the CBN check-digit algorithm when its bank code is also supplied. A mismatch returns 422 with code: nuban. Bank codes: 3 or 6 chars. Unknown bank codes return 404 UNKNOWN_BANK.

Other A2A fields: narration (max 255), nip_session_id (30/31/32 chars), stan (6–12 numeric chars), transaction_reference (max 64).

Device / network

Free-form

Wallet / agent banking (channel = wallet_transfer / agent_banking)

Amounts / status / session (optional)

These fields don't drive routing or detection on their own, but they are persisted on core.transactions and available to downstream analytics, reconciliation, and audit-chain replay.

PII rules

• Never send raw BVN. Use bvn_hash (HMAC-SHA256, 64 hex chars). The HMAC key is the platform pepper, shared out-of-band during onboarding.
• Never send raw PAN. Use card_bin (first 6–8 digits) and card_last_four. The platform never asks for the middle of the PAN.
• NUBANs are not PII in the same sense, but they ARE customer identifiers — treat them with the same care.

Idempotency

Re-submitting the same logical transaction (network retry, app crash + restart) must not create duplicate rows. Two layers:

Layer 1 — X-Idempotency-Key header

Recommended. Send a UUIDv4 in the X-Idempotency-Key request header. The platform stores the response under this key for 24 hours; a subsequent request with the same header replays the cached response and sets X-Idempotent-Replay: true on the way out.

curl -X POST https://staging.kupinga.net/api/v1/evaluate \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 11111111-1111-1111-1111-111111111111" \
  -d '{...}'

The key is scoped to the calling merchant_id — two merchants can reuse the same UUID without colliding.

Layer 2 — (merchant_id, external_id) uniqueness

Backstop. Even without the header, the DB enforces uniqueness on (merchant_id, external_id). A second submission of the same pair returns 409 duplicate_transaction with the cached decision; the response carries X-Idempotent: true.

Combined behaviour

If you can generate a stable X-Idempotency-Key from your client state (transaction ID, retry-attempt counter, etc.), use it — it gives you the cleanest 200 replay for retries. If you can't, external_id alone is sufficient: the 409 reply still carries the original decision, so your client logic can branch on the status code and use the same outcome field either way.

Rules-engine variable reference

The exhaustive catalogue of what the detection layer actually reads off your payload.

Three things consume the request body once it clears validation: the rules engine (declarative DSL evaluated by the compiler), the velocity tracker (Redis counters keyed by dimension), and the list checker (blocklist / whitelist / watchlist lookups against entity types). Each reads a different subset of the input — the tables below tell you which fields drive which behaviour.

1. Rules-engine variable catalogue

Every variable a rule may reference in the DSL, where it comes from, and whether it is populated today. Source: internal/rules/schema/.

A variable may still resolve to null at evaluation time if its source field is absent on a specific transaction — e.g. transaction.user_agent is null when the inbound HTTP request had no User-Agent header, and the BVN-fingerprint fields are null when the platform couldn't resolve a fingerprint for the customer (Tier 1 KYC, lookup error, or a 50 ms timeout on the hot path). A rule comparing a null variable with any operator other than == / != evaluates to false and short-circuits, so it's safe to reference these variables without guarding for nullability.

2. Velocity dimensions

The velocity tracker pivots on eleven dimensions. Each is incremented for every accepted transaction that supplies a non-empty value for the corresponding field(s). Source: internal/velocity/dimensions.go.

A dimension is skipped (no counter increment) when its source field is empty. If you want a VELOCITY_COUNT_24H reason code to fire on a phone number, you have to send customer_phone. The fan-out detector (FRD_NIP_FANOUT) keys off the sender_account / beneficiary_account dimensions and won't fire on A2A transactions that omit the source/destination identifiers.

3. List entity types

The list checker (internal/lists/) supports thirteen entity types. A transaction is checked against every type for which it carries a value; a match against a blocklist usually pins the outcome to decline regardless of the numeric score.

4. Channel-required fields at a glance

Per-channel required vs. recommended vs. ignored fields. "Recommended" means a field that isn't required by the validator but unlocks specific reason codes when populated.

/evaluate · examples & reference

Per-channel rate limits, worked examples, the DecisionResponse shape, risk-score bands, latency budgets, and failure modes.

Per-channel rate limits

In addition to the per-key tier limit, each /evaluate/{channel} route has its own bucket per caller:

These match the realistic peak shape per channel (USSD gets a big burst because salary-day spikes are normal traffic; RTGS gets a small bucket because it's low-volume by definition). Exceeding any of them returns 429 with Retry-After.

Example 1 — POS card-present → expect APPROVE

curl -X POST https://staging.kupinga.net/api/v1/evaluate/pos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 11111111-1111-1111-1111-111111111111" \
  -d '{
    "external_id": "demo-pos-001",
    "merchant_id": "BANK_ALPHA_NG",
    "amount": 12500,
    "currency": "NGN",
    "customer_id": "demo-cust-001",
    "channel": "pos",
    "transaction_type": "payment",
    "card_bin": "506099",
    "card_last_four": "0000",
    "card_brand": "verve",
    "card_type": "debit",
    "entry_mode": "chip",
    "emv_cryptogram_present": true,
    "pos_pin_verified": true,
    "terminal_id": "TERM0001",
    "terminal_country": "NGA",
    "merchant_name": "DEMO MERCHANT LAGOS",
    "merchant_city": "Lagos",
    "merchant_country": "NGA",
    "mcc": "5411"
  }'

{
  "transaction_id": "9d5e1b3c-1a2b-4c5d-6e7f-8a9b0c1d2e3f",
  "decision_id": "7c4d2a3b-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "outcome": "approve",
  "risk_score": 12,
  "reason_codes": [],
  "recommended_actions": [],
  "processing_time_ms": 87,
  "request_id": "1b2c3d4e-5f6a-7b8c-9d0e-1f2a3b4c5d6e"
}

Example 2 — High-velocity unusual-geo card → expect CHALLENGE

curl -X POST https://staging.kupinga.net/api/v1/evaluate/pos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 22222222-2222-2222-2222-222222222222" \
  -d '{
    "external_id": "demo-pos-002",
    "merchant_id": "BANK_ALPHA_NG",
    "amount": 850000,
    "currency": "NGN",
    "customer_id": "demo-cust-002",
    "channel": "pos",
    "transaction_type": "payment",
    "card_bin": "539923",
    "card_last_four": "0001",
    "card_brand": "mastercard",
    "card_type": "credit",
    "card_country": "NGA",
    "entry_mode": "magstripe",
    "terminal_id": "TERM9999",
    "terminal_country": "RUS",
    "merchant_name": "DEMO MERCHANT MOSCOW",
    "merchant_city": "Moscow",
    "merchant_country": "RUS",
    "mcc": "7995",
    "ip_address": "203.0.113.42",
    "ip_country": "RUS"
  }'

{
  "transaction_id": "9d5e1b3c-1a2b-4c5d-6e7f-8a9b0c1d2e40",
  "decision_id": "7c4d2a3b-5e6f-7a8b-9c0d-1e2f3a4b5c6e",
  "outcome": "challenge",
  "risk_score": 68,
  "reason_codes": ["UNUSUAL_GEO", "HIGH_RISK_MCC", "MAGSTRIPE_FALLBACK"],
  "recommended_actions": ["step_up_otp", "notify_customer"],
  "challenge": {
    "challenge_type": "otp",
    "instructions": "An OTP has been sent to the customer's registered phone. Enter it to continue.",
    "challenge_id": "ch_2f3a4b5c6d7e8f9a",
    "delivery": "sms",
    "deadline_at": "2026-05-25T11:47:00Z",
    "verify_url": "/api/v1/challenge/ch_2f3a4b5c6d7e8f9a",
    "max_attempts": 3
  },
  "processing_time_ms": 142,
  "request_id": "1b2c3d4e-5f6a-7b8c-9d0e-1f2a3b4c5d6f"
}

When outcome=challenge, your client should drive the customer through the indicated challenge_type (OTP, biometric, PIN, secret question, etc.) and only complete the transaction when the verify_url returns success.

Example 3 — Known-bad merchant + sanctioned counterparty → expect DECLINE

curl -X POST https://staging.kupinga.net/api/v1/evaluate/nip \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 33333333-3333-3333-3333-333333333333" \
  -d '{
    "external_id": "demo-nip-001",
    "merchant_id": "BANK_ALPHA_NG",
    "amount": 4500000,
    "currency": "NGN",
    "customer_id": "demo-cust-003",
    "channel": "nip",
    "transaction_type": "transfer",
    "source_account_number": "0123456789",
    "source_account_name": "DEMO CUSTOMER ALPHA",
    "source_bank_code": "044",
    "dest_account_number": "9876543210",
    "dest_account_name": "SANCTIONED ENTITY LTD",
    "dest_bank_code": "058",
    "narration": "invoice payment",
    "nip_session_id": "044202605251142000123456789012"
  }'

{
  "transaction_id": "9d5e1b3c-1a2b-4c5d-6e7f-8a9b0c1d2e41",
  "decision_id": "7c4d2a3b-5e6f-7a8b-9c0d-1e2f3a4b5c6f",
  "outcome": "decline",
  "risk_score": 95,
  "reason_codes": ["SANCTIONS_HIT", "STRUCTURED_AMOUNT", "BENEFICIARY_HIGH_RISK"],
  "recommended_actions": ["reject_transaction", "open_case", "file_sar"],
  "processing_time_ms": 118,
  "request_id": "1b2c3d4e-5f6a-7b8c-9d0e-1f2a3b4c5d70"
}

Response shape — DecisionResponse

{
  "transaction_id": "uuid",   // platform's transaction public_id
  "decision_id":   "uuid",   // platform's decision public_id
  "outcome":       "approve|review|challenge|decline",
  "risk_score":    0..100,
  "reason_codes":  ["UPPER_SNAKE_CASE", ...],   // empty array when no signal fired
  "recommended_actions": ["snake_case", ...],   // empty array when none
  "challenge":     null | {
    "challenge_type": "otp|otp_sms|otp_email|biometric|pin|secret_question|manual_review",
    "instructions":   "human-readable hint, safe to render verbatim",
    "metadata":       null | {"key": "value"},   // channel-specific hints
    "challenge_id":   "ch_...",                  // realtime plane (when wired)
    "delivery":       "sms|push|...",            // realtime plane
    "deadline_at":    "RFC 3339",                // realtime plane
    "deeplink":       "antifraud://...",         // realtime plane (mobile only)
    "verify_url":     "/api/v1/challenge/...",   // realtime plane
    "max_attempts":   1..5                       // realtime plane
  },
  "processing_time_ms": 87,
  "request_id":        "uuid"   // chi request ID, also on X-Request-Id
}

Field rules:

• transaction_id, decision_id, outcome, risk_score, processing_time_ms are ALWAYS present.
• reason_codes and recommended_actions are always present but may be empty arrays.
• challenge is omitted unless outcome == "challenge". Branch on the field's presence, not on re-deriving from the outcome.
• request_id is omitted only in tests / internal-call contexts; production traffic always carries it.

Risk-score reference

risk_score is an integer in [0, 100]. Higher = riskier. The score is derived from rules + ML + signal weights; the outcome is chosen by mapping the score against per-channel thresholds.

Default bands (global fallback)

When a channel has no custom threshold row configured, the platform uses these defaults:

Source: config.decision_thresholds (defaults seeded in migration 0020). All comparisons are inclusive: a score of exactly 30 approves, exactly 60 challenges, exactly 80 declines.

Per-channel overrides

Thresholds are configurable per channel (POS, NIP, ATM, USSD, Mobile, Internet, Card). A risk-averse channel can move decline_min down to 70; a high-volume low-friction channel can move approve_max up to 40. The four outcomes don't change — only the bands that map to them do.

If you operate across multiple channels, expect different score-to-outcome mappings. Always branch on outcome, not on raw risk_score. The score is informational; the outcome is the decision the platform has already made for you.

Reason-code anchors

Common reason_codes you'll see alongside elevated scores:

The full catalogue lives behind GET /api/v1/decisioning/reason-codes once you have decisions:read scope; the table above is the operational shortlist worth handling explicitly in your UI.

Customer-level vs decision-level score

The Customer object also carries risk_score + risk_tier (low / medium / high). That's a profile-level snapshot maintained by KYC / screening, not a rolling per-transaction aggregate. Treat it as a slow-moving customer attribute. The per-/evaluate risk_score is the realtime decision score and is the one to act on at transaction time.

Latency expectations

The synchronous path runs validation → idempotency lookups (Redis + DB) → enrichment → rules + ML pipeline → persistence → response. The pipeline itself has a 100 ms internal budget; the rest is network + DB round-trips.

If your client's observed latency is materially above these numbers, check: (1) your network path to https://staging.kupinga.net; (2) whether you're hitting the rate limit; (3) the processing_time_ms field on the response — that's the server's view. If your wall-clock differs from it by more than ~200 ms, the gap is in the network.

Failure modes

See rate limits & errors for the full catalogue. The ones specific to /evaluate:

Looking up decisions

Re-fetch any decision by ID. ETag-cacheable. Optionally enrich with signals + transaction.

The same shape /evaluate returns, addressable by the decision_id from the original evaluation. Useful when:

• You need to display a historical decision in your operations console.
• A retry or replay needs the latest server-side view (e.g. an analyst overrode the original decision).
• Your settlement layer wants to confirm the platform's view before releasing funds.

Request

curl https://staging.kupinga.net/api/v1/decisions/7c4d2a3b-5e6f-7a8b-9c0d-1e2f3a4b5c6d \
  -H "Authorization: Bearer $API_KEY"

The path parameter is the decision_id (a UUID) from the /evaluate response. The transaction's own transaction_id is NOT accepted here — use decision_id.

Response — DecisionDetailResponse

The base shape is identical to DecisionResponse.

{
  "transaction_id": "uuid",
  "decision_id":   "uuid",
  "outcome":       "approve|decline|challenge",
  "risk_score":    0..100,
  "reason_codes":  [],
  "recommended_actions": [],
  "challenge":     null,
  "processing_time_ms": 87,
  "request_id":    "uuid",

  // Present only when ?include=signals
  "signals": null,

  // Present only when ?include=transaction
  "transaction": null
}

processing_time_ms reflects the original evaluation. Reads don't re-evaluate, so the field is preserved from the persisted decision row.

?include= — pulling more

curl "https://staging.kupinga.net/api/v1/decisions/$DECISION_ID?include=signals,transaction" \
  -H "Authorization: Bearer $API_KEY"

Comma-separate multiple values. Unknown values are silently ignored, so ?include=signals,future-block is forward-compatible.

When an include is requested: signals: [] means we looked and found no signals (rare but possible — a rules-only path with no hits). signals: null means you didn't ask for it. The pointer-to-slice trick on the wire is intentional: the empty array is a meaningful answer, distinct from "not requested."

ETag / If-None-Match caching

Decisions are immutable once written. The endpoint stamps a strong ETag derived from (decision_id, evaluated_at, include-set) and sends Cache-Control: private, max-age=30. Both the ETag and the cache window are stable across requests for the same logical resource.

# First call — gets 200 + ETag
ETAG=$(curl -i https://staging.kupinga.net/api/v1/decisions/$DECISION_ID \
  -H "Authorization: Bearer $API_KEY" \
  | awk '/^ETag:/{print $2}' | tr -d '\r')

# Second call — gets 304 with no body
curl -i https://staging.kupinga.net/api/v1/decisions/$DECISION_ID \
  -H "Authorization: Bearer $API_KEY" \
  -H "If-None-Match: $ETAG"

304 Not Modified carries ETag and Cache-Control but no body. The If-None-Match: * wildcard is also accepted and short-circuits to 304 whenever the resource exists.

When to look up vs. trust the inline response

Failure modes

Customers

Read-mostly surface with a small write path for explicit CIF onboarding.

If your integration only fires /evaluate and never explicitly onboards customers, the platform creates a stub customer row on first sighting (customer_id carried in the transaction). For explicit onboarding — CIF provisioning, branch-side enrolment, back-office corrections — use the write path below.

Hashing PII before sending

BVN, NIN, and passport numbers never leave your perimeter in the clear. Hash them with HMAC-SHA256 using the shared pepper from your onboarding pack and send the 64-char lowercase hex digest:

import hmac, hashlib
PEPPER = b"<shared-pepper-from-onboarding-pack>"

def hash_id(value: str) -> str:
    return hmac.new(PEPPER, value.encode(), hashlib.sha256).hexdigest()

hash_id("22345678901")       # → 'a3f9...' (64 hex chars)

# Bash one-liner
printf '%s' "$BVN" | openssl dgst -sha256 -hmac "$PEPPER" -r | awk '{print $1}'

The platform validates every *_hash field is exactly 64 hex characters and rejects anything else with 400 validation_error. If your hashes don't match the platform's, screening hits and linkage will silently miss — verify a known test BVN end-to-end during the integration smoke.

Create — POST /customers

curl -X POST https://staging.kupinga.net/api/v1/customers \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_number":  "CUST-0001",
    "first_name":       "Adaeze",
    "last_name":        "Eze",
    "email":            "adaeze@example.com",
    "phone":            "+2348012345678",
    "date_of_birth":    "1990-04-12",
    "gender":           "F",
    "bvn_hash":         "a3f9...64-hex...",
    "nin_hash":         "b1c8...64-hex...",
    "city":             "Lagos",
    "state":            "Lagos",
    "country":          "NGA",
    "nationality":      "NG",
    "kyc_tier":         "tier_2",
    "is_pep":           false
  }'

¹ At least one identifier (BVN, NIN, passport, driving licence hash) is strongly recommended — without it the screening grade and graph linkage have nothing to anchor on.

² Expiry dates are optional. When set, the platform's daily credential-expiry sweeper finds customers whose IDs expire within 30 days (or have already expired) and writes a customer.credential_expiring notification to the customer's in-app inbox. Idempotent — re-runs don't produce duplicates.

Response (201)

{
  "id":              "5d8c9b0a-1234-5678-90ab-cdef01234567",
  "customer_number": "CUST-0001",
  "first_name":      "Adaeze",
  "last_name":       "Eze",
  "email":           "adaeze@example.com",
  "phone":           "+2348012345678",
  "bvn_hash":        "a3f9XX...XXXX",
  "nin_hash":        "b1c8XX...XXXX",
  "passport_hash":   null,
  "country":         "NGA",
  "nationality":     "NG",
  "kyc_tier":        "tier_2",
  "status":          "active",
  "is_pep":          false,
  "risk_score":      0,
  "risk_tier":       "low",
  "screening_status":"pending",
  "created_at":      "2026-05-25T08:42:13.041Z",
  "updated_at":      "2026-05-25T08:42:13.041Z"
}

*_hash fields come back masked (first 6 + last 4 hex) — the raw 64-hex digest is never echoed once stored.

Update — PUT /customers/{public_id}

Partial update — send only the fields you want to change.

Mutable: email, phone, first_name, last_name, address_line1, address_line2, city, state, postal_code, country, kyc_tier, is_pep, risk_score, risk_tier, status, passport_hash, nationality, place_of_birth, business_name.

Immutable post-creation: customer_number, bvn_hash, nin_hash, date_of_birth, gender. If any of these need correction (e.g. wrong BVN attached at onboarding), open a support ticket — the platform requires a maker-checker audit trail.

Search

curl "https://staging.kupinga.net/api/v1/customers?q=ada" \
  -H "Authorization: Bearer $API_KEY"

Required q parameter — free text (name, email, customer number, BVN hash). Empty q returns 400 missing_query. Response: a JSON array of CustomerResponse, capped at 20. Matches name fragments, email prefix, customer number, and hashed BVN. Does NOT search free-text fields like address or narration.

Get accounts

{
  "accounts": [
    {
      "id": "...",
      "nuban": "0123456789",
      "bank": { "cbn_code": "044", "short_name": "Access", "name": "Access Bank Plc" },
      "account_type": "savings",
      "status": "active",
      "pnd": false,
      "pnd_effective_to": null,
      "balance": null,
      "opened_at": "2025-11-14T08:00:00Z",
      "branch_code": "0001",
      "branch_name": "Victoria Island"
    }
  ]
}

balance is always null today. pnd is the Post-No-Debit flag (regulatory hold); true means the account is frozen until pnd_effective_to or manually lifted by compliance.

BVN-hash lookup

The path parameter must be exactly 64 lowercase hex chars. A non-conforming value returns 400 invalid_bvn_hash before the lookup runs — the URL is logged at multiple layers, so the strict shape check guards against accidentally putting a raw BVN in the path.

Credential expiry notifications

For customers who have passport_expires_at or drivers_license_expires_at on file, the platform runs a daily sweeper at 08:00 UTC. For each active customer whose expiry falls within 30 days (or is already in the past), it writes a customer.credential_expiring notification to the customer's in-app inbox.

The notification includes: the customer's first name, the document type ("passport" / "driver licence"), a masked document label (e.g. "passport ending in …X201"), the expiry date, and whether the date is past or future. Idempotent — re-runs on the same day produce zero duplicate notifications. When a customer renews and the integration updates the expiry via PUT /customers/{id}, the new date changes the idempotency key and the sweeper fires one more notification when the new date approaches.

Scenario catalogue entry: FRD-038 ("Customer identity document expiring or expired") with default_action = alert, default_priority = medium, default_score = 25. In-app only today; email mirroring available per-tenant on request.

Directors & beneficial owners — /related-parties

Corporate customers need a control-structure record: directors, shareholders, beneficial owners, signatories, secretaries, trustees. The platform models all of these as one polymorphic related party plus a corporate relationship that pins the party to a customer with a specific role and effective dates.

Supported roles: director, shareholder, beneficial_owner, signatory, secretary, trustee. A single related party can hold multiple roles on the same customer — register the party once, then add each role via the /relationships sub-route.

Create a related party + opening relationship

curl -X POST https://staging.kupinga.net/api/v1/customers/{public_id}/related-parties \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name":           "Olamide Tijani",
    "date_of_birth":       "1978-03-22",
    "nationality":         "NG",
    "country_of_residence":"NG",
    "bvn_hash":            "a3f9...64-hex...",
    "nin_hash":            "b1c8...64-hex...",
    "id_type":             "passport",
    "id_number_hash":      "c2d4...64-hex...",
    "role":                "director",
    "share_pct":           25.00,
    "source":              "cac_registry",
    "effective_from":      "2024-01-15"
  }'

The platform writes the party row and the opening corporate-relationship row in one transaction — you never get a half-created party. PEP status is derived state: don't try to set is_pep on create; it's maintained by the screening pipeline via pep_match_id.

Mutable on PATCH: full_name, date_of_birth, nationality, country_of_residence. Immutable post-create: bvn_hash, nin_hash, id_type, id_number_hash, is_pep. Sent values for immutable fields are silently ignored.

Adding another role: POST /…/{rp_public_id}/relationships. 409 conflict if a relationship row already exists for the same (customer, party, role, effective_from) tuple — use a different effective_from (typically one day later) to record a real change.

Retiring: DELETE /…/relationships/{rel_public_id}. 204 No Content. The platform sets effective_to = now(). Row stays for audit; current-roles queries filter on effective_to IS NULL. 404 if already retired — you can't retire the same relationship twice.

Customer 360 — internal surface

GET /api/v1/customers/{public_id}/360 returns a heavyweight aggregate used by the platform's own admin UI. Client integrations should not consume it directly — the shape is tuned for the React console and may change without notice. If you need a richer view than GET /customers/{id} gives you, ask support to either add fields to the canonical endpoint or expose a dedicated path.

Failure modes

Webhooks

Push events to your endpoint instead of polling. Signed HMAC-SHA256, retried with backoff, replay-protected.

Event catalogue

Subscribing to an unknown event name returns 400 invalid_event at create time. The internal Kafka topics carry richer event types (transaction.completed.v1, cases.status_changed.v1, etc.); the webhook surface deliberately exposes only the subset that's safe to publish to external systems.

Creating a subscription

curl -X POST https://staging.kupinga.net/admin/webhooks \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "bank-alpha-case-notifications",
    "description": "Pipes case.created + case.resolved into the bank ops inbox.",
    "target_url": "https://hooks.bank-alpha.example/antifraud",
    "secret_ref": "secret/clients/bank_alpha/webhook_v1",
    "events": ["case.created", "case.resolved"],
    "headers": { "X-Bank-Realm": "production" },
    "timeout_ms": 5000,
    "is_active": true,
    "consecutive_failures_max": 10,
    "ip_allowlist": ["203.0.113.0/24", "2001:db8:abcd::/48"]
  }'

Delivery shape

The platform POSTs JSON to your target_url with these headers:

There is NO X-Timestamp header — the send-time timestamp lives in the body's event_timestamp field instead. Read it from the JSON, parse RFC 3339, reject deliveries older than ~5 minutes (replay defence).

{
  "event_id": "uuid",
  "event_type": "decision.created",
  "event_timestamp": "2026-05-25T11:42:13.041Z",
  "data": {
    "decision_id": "uuid",
    "transaction_id": "uuid",
    "outcome": "decline",
    "risk_score": 87,
    "reason_codes": ["SANCTIONS_HIT"],
    "merchant_id": "BANK_ALPHA_NG"
  }
}

The data block shape varies per event type. Treat unknown fields as forward-compatible additions; don't reject the payload because of an unexpected key.

Verifying the signature

The HMAC key is whatever the platform admin seeded in Vault at your secret_ref path. They'll share it with you out-of-band during onboarding.

import hmac, hashlib

def verify(body: bytes, signature_header: str, secret: bytes) -> bool:
    # signature_header looks like "sha256=abcd1234..."
    if not signature_header.startswith("sha256="):
        return False
    expected = hmac.new(secret, body, hashlib.sha256).hexdigest()
    received = signature_header[len("sha256="):]
    return hmac.compare_digest(expected, received)

Reject deliveries that fail signature verification (respond 401), carry a body event_timestamp more than 5 minutes in the past (respond 400), or carry an X-Event-Id you've already processed (respond 200 — idempotency).

IP allowlisting & SSRF guard

The dispatcher enforces two layers of destination control before any event leaves the platform.

Unconditional SSRF guard

Every delivery has its target_url resolved via DNS at dispatch time. If any resolved IP falls in one of the following ranges, the delivery is blocked, the row is marked abandoned with error_class='destination_blocked', and the subscription's consecutive_failures counter increments toward auto-suspend.

The block is unconditional in production. There is no per-subscription override; a knob exists for single-VM development (webhooks.allow_private_destinations) but flipping it in production emits a WARN log on every dispatcher startup.

Per-subscription destination allowlist

The optional ip_allowlist field pins the resolved destination to a fixed set of IPs / CIDRs. CIDR or bare IPs, IPv4 + IPv6. Max 50 entries. Empty ([]) means "any resolved destination IP", still subject to the SSRF guard. Enforcement gated by WEBHOOKS_ENFORCE_DESTINATION_ALLOWLIST.

Maker-checker on restricted fields

Six fields can redirect or unlock the signed event stream and are governed by a two-person rule: target_url, secret_ref, events, is_active, status, ip_allowlist. A single-admin PATCH that touches any of these returns 409 requires_proposal. Edits flow through propose + approve:

# Maker
curl -X POST https://staging.kupinga.net/admin/webhooks/{id}/changes \
  -H "Authorization: Bearer $MAKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "field_changes": {
      "target_url": "https://hooks.bank-alpha.example/antifraud-v2",
      "ip_allowlist": ["203.0.113.0/24"]
    },
    "reason": "Rolling target to the v2 endpoint"
  }'

# Checker (must be a different user)
curl -X POST https://staging.kupinga.net/admin/webhooks/changes/{change_id}/approve \
  -H "Authorization: Bearer $CHECKER_TOKEN"

Proposer ≠ approver is enforced in SQL, not just in application code. Proposals expire after 7 days. A new proposal for the same subscription supersedes the prior pending one. Routine fields (name, description, headers, timeout_ms, consecutive_failures_max) continue via direct PATCH.

Retry policy

When your endpoint returns non-2xx or the request times out, the platform retries with exponential backoff:

After 5 attempts the delivery is marked abandoned. If the subscription's consecutive_failures count reaches consecutive_failures_max, the whole subscription auto-suspends and the platform's on-call gets paged. To resurrect, file a status change proposal (maker-checker).

Consumer-side idempotency

The same event_id may be delivered more than once (auto-retry, manual replay, network duplication). Dedupe on event_id before acting on the payload. A reasonable consumer pattern: maintain a fast-lookup table of event_ids you've processed in the last 24 hours. On every incoming delivery, INSERT … ON CONFLICT DO NOTHING; if the conflict fires, return 200 without re-processing.

Listing + inspecting deliveries

# List your subscriptions
curl https://staging.kupinga.net/admin/webhooks \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Last 24h health summary
curl https://staging.kupinga.net/admin/webhooks/{id}/health \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Recent deliveries (default 50, max 500)
curl "https://staging.kupinga.net/admin/webhooks/{id}/deliveries?limit=100" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

/health returns counts (delivered, failed, abandoned, in_flight) plus the last delivered timestamp and the last error. /deliveries returns per-row attempt history. DELETE /admin/webhooks/{id} soft-retires (status flips to retired; row stays for audit; new events stop flowing immediately).

Rate limits & errors

The cross-cutting reliability contract: how fast you can call, what errors look like, and how to retry.

Rate-limit tiers

Per-API-key, sliding-window. Set at mint time via the tier field. Beyond the per-key tier, each /evaluate/{channel} route has its own per-caller bucket — see channel limits.

Burst is the additional headroom above the sustained rate when the bucket is full. A standard key can burst 50 calls above the 1,000/min ceiling before the limiter kicks in.

Rate-limit headers

Every response (allowed or denied) carries:

import time, requests

def call_with_backoff(session, *args, **kwargs):
    for attempt in range(5):
        resp = session.request(*args, **kwargs)
        if resp.status_code != 429:
            return resp
        delay = int(resp.headers.get("Retry-After", 1))
        time.sleep(delay)
    return resp  # last response, surface to caller

Error envelope

Every error response carries the same shape:

{
  "error": {
    "code": "snake_case_machine_token",
    "message": "Human-readable description, safe to log.",
    "details": [
      {
        "field": "amount",
        "code": "gte",
        "message": "amount must be >= 0",
        "param": "0"
      }
    ]
  },
  "request_id": "uuid"
}

details is present on validation errors (422) and absent on plain errors. request_id matches the chi request ID and the X-Request-Id header. Always quote it on a support thread.

Error catalogue

400 — Bad request

401 — Unauthorized

403 — Forbidden

404 — Not found

(UNKNOWN_BANK / UNKNOWN_ATM use uppercase because they're business error codes vs. transport error codes — both shapes coexist.)

409 — Conflict

422 — Unprocessable entity

The validator runs in layered passes (single-field shape → channel-payload alignment → semantic checks like NUBAN check digit). Errors from later passes only surface once earlier passes clear. Fix the first error in details[], retry; the platform may then surface a deeper error.

429 — Too many requests

500 / 503 — Server

When one of the dependencies in the synchronous path is degraded (ML scoring offline, screening offline, etc.) the platform may fall back to a rules-only decision path. The synchronous /evaluate response still lands as 200 with the rules-only outcome — the platform doesn't 503 the route just because a non-critical enricher is down. A genuine 503 means the route itself can't serve the request.

Retry strategy

A defensive retry policy you can drop into any client:

Always cap retries at 5 attempts. Beyond that, surface the failure to your callers — the alternative is a stuck queue that hides a real outage. When retrying with the same X-Idempotency-Key, the platform's idempotency layer guarantees you'll either get the same response again (replay) or 409 if the body differs.

Connection management

• Use TLS 1.2 minimum, 1.3 preferred. Modern AEAD ciphers; HSTS pinned.
• Reuse HTTP/2 connections aggressively. One connection can serve hundreds of concurrent requests.
• Set a client-side timeout of ~2 seconds per call. The platform's internal budget caps at 1.5s; anything longer is a network problem.
• If you sit behind a corporate proxy, confirm it doesn't strip the Authorization header. Some proxies do this by default.

Latency expectations

Going to production

The promotion checklist. When all items below are green, the integration is ready for production cutover.

Pre-flight on staging

Run these against https://staging.kupinga.net first. They are non-negotiable; staging is where you find the bugs.

Functional

• Full Postman collection passes top-to-bottom in Runner. Import from postman/.
• Login + API-key mint + revoke flow works.
• All channels you'll send in production have at least one worked example green: POS, ATM, USSD, NIP, etc.
• Customer search returns expected results for known test customers.
• Decision lookup returns the same outcome you saw inline on /evaluate.
• Decision lookup with ?include=signals,transaction returns enriched data without 5xx.
• If-None-Match revalidation lands a 304 on the second call.

Idempotency

• Same X-Idempotency-Key + same body → 200 with X-Idempotent-Replay: true on retry.
• Same X-Idempotency-Key + different body → 409 idempotency_conflict.
• Same (merchant_id, external_id), no idempotency key → 409 duplicate_transaction with the cached decision in the body.
• Network-disconnect mid-flight scenario: the platform's self-heal logic recovers and the retry lands as a replay, not a duplicate. Test by killing the TCP connection between sending the request and reading the response.

Webhooks (when subscribed)

• Signature verification works against your verifier. Include a deliberate signature-mismatch case to confirm your endpoint rejects it.
• Replay protection: an event with an event_timestamp more than 5 minutes in the past is rejected.
• Consumer-side idempotency: the same X-Event-Id delivered twice causes exactly one downstream effect.
• Retry policy validates: deliberately 500 your endpoint and observe the platform retry with the documented backoff.

Capacity

• Sustained load at 90% of your contracted tier RPS for 5 minutes. The platform side handles this; the test confirms your client side can too.
• No 429 responses during the steady-state window. If you see any, you're either under-provisioned or hot-spotting on a per-channel bucket — investigate before going live.
• Tail latency: p99 stays inside 500ms for /evaluate throughout the run.
• Webhook deliveries don't queue up: GET /admin/webhooks/{id}/health shows in_flight returning to 0 within seconds of the load test ending.

Error handling

• Your client retries 429 with Retry-After.
• Your client retries 5xx and network errors with exponential backoff, capped at 5 attempts.
• Your client does NOT retry 4xx errors other than 429 and 409 idempotency_in_flight.
• Your client logs request_id on every failed call.
• PII never lands in your client-side logs (BVN, NIN, raw PAN). Mask before logging.

Security

• API key is in your secret manager, not in source control.
• No staging keys in production binaries (and vice versa).
• TLS 1.2+ enforced on the client side.
• Bearer tokens never appear in URL paths or query strings (only headers).
• HMAC signing on webhooks uses constant-time comparison.

Production tier negotiation

Before promotion, confirm in writing with integration@<your-domain>:

• Production tier (starter / standard / premium / unlimited)
• Production source IP range (for allowlisting on the API key)
• Production webhook target URL (different from staging)
• Production go-live date
• Production on-call rotation contact for the first 72 hours

The production tier is what the API key gets minted with. Once production traffic starts, lifting the tier is fast (a new key + rotation); lowering it is fast too (PATCH the key).

Cutover sequence

The cutover is a coordinated event. The platform side handles:

1. Tenant cloned to production. A new merchant_id provisioned under the production cluster, same shape as staging.
2. Production API key minted. Same scopes as staging, the contracted tier, and an allowed_cidrs list populated from your IP range. Delivered out-of-band. Later changes to the allowlist require a two-person maker-checker approval.
3. Production webhook subscription created (when contracted), with a fresh HMAC secret in production Vault. Staging secret never reused.
4. Runbook handoff. Platform on-call shares the operator runbook excerpt covering: how to escalate, how to identify merchant traffic in our dashboards, how to read our latency + error dashboards.

You handle:

1. Flip the API key in your secret manager to the production value.
2. Flip the base URL in your client config to the production host.
3. Flip your webhook endpoint to the production handler.
4. Smoke test the production tenant with a low-value transaction (e.g. ₦100 internal test). Confirm the decision lands and the webhook fires.
5. Cut over real traffic in a measured ramp: 1% → 10% → 50% → 100% over the first hour.

First 72 hours

The platform side runs heightened monitoring for the first three days post-cutover:

• Decision-outcome ratio drift watched against staging baseline. A sudden swing (e.g. decline rate from 0.5% to 15%) gets an immediate on-call page.
• Webhook delivery latency + retry counts on your subscription.
• Per-channel rate-limit utilisation.
• p99 latency on /evaluate for your merchant_id.

You should watch your decline rate, 429s, and webhook consumer lag. If anything diverges from staging, file a support ticket with sample request_ids.

When to call

Always quote merchant_id and request_id (or decision_id, event_id, webhook_id). The platform indexes everything on these — an investigation starting from them resolves in minutes; one without them can take hours.

Postman & SDKs

Importable collections, environment files, and snippet packs.

Postman collection

Open Postman and import three files from postman/:

1. antifraud-rest-api.postman_collection.json
2. antifraud-staging.postman_environment.json
3. antifraud-production.postman_environment.json

Select the Antifraud — staging environment, run the Auth → Login request first, then API Keys → Create. The collection's test scripts automatically populate {{accessToken}} and {{apiKey}} into the environment so the rest of the requests work without manual copy-paste.

The Collection Runner (Postman → Collections → Run) executes the full suite top-to-bottom and prints green checks against the response assertions baked into each request's Tests tab.

Snippet packs

The examples/ folder ships curl, Python, and Node.js snippets for the happy-path flows. They mirror the worked examples in this documentation but are written to compile and run unchanged against a fresh API key.

Environment matrix

Support

Where to go when things go sideways.

Quote your merchant_id and (where available) the request_id from the response on every support thread. The platform indexes every audit + log line on those two fields; an investigation starting from them resolves in minutes; one without them can take hours.