PAYKX Decision API

Independent pre-execution intelligence for high-friction payment corridors. Send a corridor and amount, get back a clear GO / DEGRADED / NO-GO decision — proceed, pause, or reroute — with a confidence score and a seven-signal breakdown.

https://api.paykx.co.uk

Make your first call

curl https://api.paykx.co.uk/api/v1/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"corridor": "GB-NG", "amount": 1500, "currency": "GBP"}'

{
  "decision": "GO",
  "score": 0.94,
  "confidence": 0.97,
  "recommended_partner": "Partner A",
  "reasons": [
    { "code": "HEALTHY_PARTNER", "message": "All monitored execution signals are healthy." }
  ],
  "reason_codes": ["HEALTHY_PARTNER"],
  "request_id": "req_m3a7fzk2p1r4",  // ← req_… format = demo only, not auditable (see note below)
  "evaluated_at": "2026-07-15T11:30:47Z",
  "decision_model": "v1.2",
  "probe_count": 7,
  "corridor": "GB-NG",
  "currency": "GBP",
  "corridor_supported": true,
  "response_ms": 112,
  "signals": {
    "balance_sufficient": true,
    "operation_valid": true,
    "network_healthy": true,
    "historical_failure_rate": 0.04,
    "cop_overridden": false,
    "fx_volatility": "low",
    "fraud_flags": 0
  },
  "probe_details": {
    "fraud_flags":             { "signal": "CLEAR", "risk_value": 1.00 },
    "network_healthy":         { "signal": "CLEAR", "risk_value": 0.92 },
    "balance_sufficient":      { "signal": "CLEAR", "risk_value": 1.00 },
    "fx_volatility":           { "signal": "CLEAR", "risk_value": 0.88 },
    "operation_valid":         { "signal": "CLEAR", "risk_value": 0.95 },
    "historical_failure_rate": { "signal": "CLEAR", "risk_value": 0.96 },
    "cop_overridden":          { "signal": "CLEAR", "risk_value": 1.00 }
  },
  "environment": "fca-sandbox-validated",
  "api_version": "1.2"
}

Authentication & API Keys

Every call to a protected endpoint requires your API key, passed as a Bearer token. There are two key types — test keys for shadow mode and live keys for production.

Key types

How to authenticate

Pass your key in the Authorization header as a Bearer token, or alternatively in the X-API-Key header:

curl https://api.paykx.co.uk/api/v1/verify \
  -H "Authorization: Bearer pk_test_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"corridor": "GB-NG", "amount": 1500, "currency": "GBP"}'

curl https://api.paykx.co.uk/api/v1/verify \
  -H "X-API-Key: pk_test_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"corridor": "GB-NG", "amount": 1500, "currency": "GBP"}'

const res = await fetch("https://api.paykx.co.uk/api/v1/verify", {
  method: "POST",
  headers: {
    "Authorization": "Bearer pk_test_xxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ corridor: "GB-NG", amount: 1500, currency: "GBP" })
});
const { decision, score, confidence, reason_codes } = await res.json();

import requests

resp = requests.post(
    "https://api.paykx.co.uk/api/v1/verify",
    headers={"Authorization": "Bearer pk_test_xxxxx"},
    json={"corridor": "GB-NG", "amount": 1500, "currency": "GBP"},
)
data = resp.json()
print(data["decision"], data["confidence"], data["reason_codes"])

Key lifecycle

Onboarding flow

From zero to a verified, scoped API key in five steps:

Permissions

Keys are scoped to the caller. Each key can only read the verification records it created — two API consumers are never able to see each other's data.

Sandbox / Demo

PAYKX currently runs in shadow mode. This is a safe test environment where every decision is computed with the real scoring engine, but no live payment rails are touched. It's a good way to integrate and test before you go live.

Public demo endpoint

Want to try PAYKX without a key? The demo endpoint needs no authentication and returns a full seven-signal decision for the GB-NG corridor.

curl -X POST https://api.paykx.co.uk/api/v1/demo-verify \
  -H "Content-Type: application/json" \
  -d '{"corridor": "GB-NG", "amount": 1500, "currency": "GBP"}'

Profile comparison endpoint

Want to see how different risk profiles score the same payment? POST /api/v1/demo-compare needs no authentication and scores a payment against conservative, balanced, and speed-optimised profiles in one call. Use amount: 85000 to see profiles diverge.

curl -X POST https://api.paykx.co.uk/api/v1/demo-compare \
  -H "Content-Type: application/json" \
  -d '{
    "payment": {"corridor": "GB-NG", "amount": 85000, "currency": "GBP"},
    "profiles": ["conservative", "balanced", "optimise_speed"]
  }'

See the full endpoint reference in the API Reference section below, or explore it interactively in the API Explorer ↗.

API Reference

Full request and response detail for every endpoint. Expand a card to see parameters, an example response, and a live “Try it out” console.

"decision": "GO",
"score": 0.87,
"volatility": 0.09,
"confidence": 0.87,
"probe_count": 7,
"corridor_supported": true,
"validation_note": "Corridor fully validated with deep data.",
"idempotency_hit": false,
"signals": {
  "balance_sufficient":      true,
  "operation_valid":         true,
  "network_healthy":         true,
  "historical_failure_rate": 0.04,
  "cop_overridden":          false,
  "fx_volatility":           "low",
  "fraud_flags":             0
},
"probe_details": {
  "balance_sufficient":      { "signal": "CLEAR", "risk_value": 1.00 },
  "operation_valid":         { "signal": "CLEAR", "risk_value": 0.95 },
  "network_healthy":         { "signal": "CLEAR", "risk_value": 0.92 },
  "historical_failure_rate": { "signal": "CLEAR", "risk_value": 0.96 },
  "cop_overridden":          { "signal": "CLEAR", "risk_value": 1.00 },
  "fx_volatility":           { "signal": "CLEAR", "risk_value": 0.88 },
  "fraud_flags":             { "signal": "CLEAR", "risk_value": 1.00 }
},
"currency": "GBP",
"environment": "fca-sandbox-validated"

"decision": "DEGRADED",
"score": 0.61,
"confidence": 0.88,
"recommended_partner": "Partner B",
"reasons": [
  { "code": "HIGH_FX_VOLATILITY", "message": "Foreign exchange spread or rate volatility is elevated." },
  { "code": "HIGH_FAILURE_RATE", "message": "Historical failure rate on this corridor is above acceptable threshold." }
],
"reason_codes": ["HIGH_FX_VOLATILITY", "HIGH_FAILURE_RATE"],
"request_id": "req_p9xk2m4r7nq1",
"evaluated_at": "2026-07-15T11:31:22Z",
"decision_model": "v1.2",
"probe_count": 7,
"corridor_supported": true,
"signals": {
  "balance_sufficient":      true,
  "operation_valid":         true,
  "network_healthy":         true,
  "historical_failure_rate": 0.28,
  "cop_overridden":          false,
  "fx_volatility":           "high",
  "fraud_flags":             0
},
"environment": "fca-sandbox-validated"

"status": "healthy",
"version": "1.2",
"message": "PAYKX Rail Verification API is running successfully",
"mode": "shadow",
"environment": "shadow-demo"

{
  "phase": 0,
  "state": "telemetry_only",
  "decision_influence": false,
  "supported_for_decisioning": false,
  "confidence": "experimental",
  "last_updated": "2026-08-01T00:00:00.000Z",
  "observations_collected": 0,
  "blend_weight": 0,
  "escalation_enabled": false,
  "active_adapters": ["synthetic-baseline", "central-bank-ng"],
  "governed_by": "ADR-015"
}

curl -X POST https://api.paykx.co.uk/api/v1/demo-compare \
  -H "Content-Type: application/json" \
  -d '{
    "payment": { "corridor": "GB-NG", "amount": 85000, "currency": "GBP" },
    "profiles": ["conservative", "balanced", "optimise_speed"]
  }'

"corridor": "GB-NG",
"amount": 85000,
"profiles_compared": ["conservative", "balanced", "optimise_speed"],
"results": {
  "conservative": { "decision": "DEGRADED", "score": 0.726, "go_threshold": 0.85 },
  "balanced":     { "decision": "DEGRADED", "score": 0.726, "go_threshold": 0.80 },
  "optimise_speed": { "decision": "GO",       "score": 0.726, "go_threshold": 0.70 }
},
"divergence": {
  "profiles_agree": false,
  "summary": "Profiles diverge: conservative→DEGRADED, balanced→DEGRADED, optimise_speed→GO."
},
"evaluated_at": "2026-07-29T12:00:00Z",
"environment": "sandbox"

Corridor Scope

PAYKX only returns a confident decision for corridors it has deep, validated data for. Everything else is deliberately returned as DEGRADED so you are never given false confidence.

Decisions

Every verification returns one of three decisions. For supported corridors the decision follows the composite score band below, so it's fully deterministic and explainable. Unsupported corridors are always returned as DEGRADED (see note).

Score vs Confidence — why both matter

The response returns two separate numeric fields that are easy to conflate but operationally distinct:

Two DEGRADED decisions can look identical in the decision band but be operationally very different:

"decision": "DEGRADED",
"score":    0.68,
"confidence": 0.97,
"recommended_partner": "Partner B",
"reasons": [{ "code": "HIGH_FX_VOLATILITY", "message": "FX volatility elevated." }]

"decision": "DEGRADED",
"score":    0.68,
"confidence": 0.51,
"recommended_partner": null,
"reasons": [{ "code": "CORRIDOR_UNSUPPORTED", "message": "Limited data." }]

Code Examples

Call the verify endpoint from any stack. Replace YOUR_API_KEY with your issued key.

curl https://api.paykx.co.uk/api/v1/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"corridor": "GB-NG", "amount": 1500, "currency": "GBP"}'

import requests

resp = requests.post(
    "https://api.paykx.co.uk/api/v1/verify",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"corridor": "GB-NG", "amount": 1500, "currency": "GBP"},
)
data = resp.json()
print(data["decision"], data["score"])

const res = await fetch("https://api.paykx.co.uk/api/v1/verify", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ corridor: "GB-NG", amount: 1500, currency: "GBP" })
});
const data = await res.json();
console.log(data.decision, data.score);

SDKs

The official @paykx/sdk package is in private beta. Copy the wrapper below into your project now — it has the same interface the published package will use, so your code will not need to change.

npm install @paykx/sdk

import { verify } from '@paykx/sdk';

const result = await verify({
  apiKey: process.env.PAYKX_API_KEY,
  corridor: 'GB-NG',
  amount: 1500,
  currency: 'GBP',
});
// result.decision | result.confidence | result.reason_codes

Use today — copy this wrapper

Same interface, no dependency, works in any Node.js or browser environment:

// paykx.js — drop-in client, same interface as @paykx/sdk
const BASE = "https://api.paykx.co.uk";

export async function verify({ apiKey, corridor, amount, currency = "GBP", idempotencyKey } = {}) {
  const res = await fetch(`${BASE}/api/v1/verify`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ corridor, amount, currency, idempotency_key: idempotencyKey }),
  });
  if (res.status === 429) {
    const retryAfter = res.headers.get("Retry-After");
    throw Object.assign(new Error("Rate limited"), { status: 429, retryAfter });
  }
  if (!res.ok) {
    const err = await res.json().catch(() => ({}));
    throw Object.assign(new Error(err.message ?? `PAYKX error ${res.status}`), { status: res.status });
  }
  return res.json(); // { decision, score, confidence, reason_codes, signals, probe_details, … }
}

// usage
const { decision, confidence, reason_codes } = await verify({
  apiKey: process.env.PAYKX_API_KEY,
  corridor: "GB-NG",
  amount: 1500,
});
console.log(decision, confidence, reason_codes);

# paykx.py — drop-in client, same interface as paykx-sdk (PyPI, coming soon)
import os, requests

BASE = "https://api.paykx.co.uk"

def verify(*, api_key=None, corridor, amount, currency="GBP", idempotency_key=None):
    api_key = api_key or os.environ["PAYKX_API_KEY"]
    resp = requests.post(
        f"{BASE}/api/v1/verify",
        headers={"Authorization": f"Bearer {api_key}"},
        json={"corridor": corridor, "amount": amount, "currency": currency,
              **({"idempotency_key": idempotency_key} if idempotency_key else {})},
        timeout=10,
    )
    resp.raise_for_status()
    return resp.json()  # dict with decision, score, confidence, reason_codes, …

# usage
result = verify(corridor="GB-NG", amount=1500)
print(result["decision"], result["confidence"], result["reason_codes"])

// paykx.cjs — CommonJS version
const BASE = "https://api.paykx.co.uk";

async function verify({ apiKey, corridor, amount, currency = "GBP", idempotencyKey } = {}) {
  const res = await fetch(`${BASE}/api/v1/verify`, {
    method: "POST",
    headers: { "Authorization": `Bearer ${apiKey}`, "Content-Type": "application/json" },
    body: JSON.stringify({ corridor, amount, currency, idempotency_key: idempotencyKey }),
  });
  if (!res.ok) throw new Error(`PAYKX ${res.status}`);
  return res.json();
}

module.exports = { verify };

package paykx

import (
        "bytes"
        "encoding/json"
        "fmt"
        "net/http"
)

const base = "https://api.paykx.co.uk"

type VerifyRequest struct {
        Corridor       string  `json:"corridor"`
        Amount         float64 `json:"amount,omitempty"`
        Currency       string  `json:"currency,omitempty"`
        IdempotencyKey string  `json:"idempotency_key,omitempty"`
}

type VerifyResponse struct {
        Decision    string  `json:"decision"`
        Score       float64 `json:"score"`
        Confidence  float64 `json:"confidence"`
        ReasonCodes []string `json:"reason_codes"`
        RequestID   string  `json:"request_id"`
        EvaluatedAt string  `json:"evaluated_at"`
}

func Verify(apiKey string, req VerifyRequest) (*VerifyResponse, error) {
        body, _ := json.Marshal(req)
        r, err := http.NewRequest("POST", base+"/api/v1/verify", bytes.NewReader(body))
        if err != nil {
                return nil, err
        }
        r.Header.Set("Authorization", "Bearer "+apiKey)
        r.Header.Set("Content-Type", "application/json")
        resp, err := http.DefaultClient.Do(r)
        if err != nil {
                return nil, err
        }
        defer resp.Body.Close()
        if resp.StatusCode != 200 {
                return nil, fmt.Errorf("paykx: %s", resp.Status)
        }
        var result VerifyResponse
        json.NewDecoder(resp.Body).Decode(&result)
        return &result, nil
}

// usage
// result, err := paykx.Verify(os.Getenv("PAYKX_API_KEY"), paykx.VerifyRequest{
//     Corridor: "GB-NG", Amount: 1500, Currency: "GBP",
// })

# Verify corridor — replace YOUR_KEY with your API key
curl https://api.paykx.co.uk/api/v1/verify \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"corridor":"GB-NG","amount":1500,"currency":"GBP"}'

# Demo endpoint — no key required
curl -X POST https://api.paykx.co.uk/api/v1/demo-verify \
  -H "Content-Type: application/json" \
  -d '{"corridor":"GB-NG","amount":1500,"currency":"GBP"}'

# Profile comparison — no key required
# Returns the same payment scored against conservative / balanced / speed-optimised profiles
curl -X POST https://api.paykx.co.uk/api/v1/demo-compare \
  -H "Content-Type: application/json" \
  -d '{"payment":{"corridor":"GB-NG","amount":85000,"currency":"GBP"},"profiles":["conservative","balanced","optimise_speed"]}'

# Health check
curl https://api.paykx.co.uk/api/health

# With idempotency (safe retries)
curl https://api.paykx.co.uk/api/v1/verify \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"corridor":"GB-NG","amount":1500,"currency":"GBP","idempotency_key":"uuid-goes-here"}'

Error Codes

PAYKX uses standard HTTP status codes. Every error response includes a JSON body with a message field.

JSON response bodies

Every non-200 response returns the same JSON envelope. Use message for display and code (when present) for programmatic logic.

{ "message": "corridor is required" }

{ "message": "Invalid API key." }

{ "message": "Idempotency key reused with a different request body." }

HTTP/1.1 429 Too Many Requests
Retry-After: 37

{ "message": "Rate limit exceeded. Try again in 37 seconds." }

{ "message": "Internal Server Error" }

{ "message": "Service temporarily unavailable." }

Idempotency

Pass an idempotency_key (for example a UUID) in the request body to make retries safe. The first request with a given key is processed and cached; reusing the same key with the same body returns the identical cached result with idempotency_hit: true. Reusing it with a different body returns 409 Conflict.

Error Handling Guide

Practical guidance for each error state — what caused it, how to detect it in code, and the correct recovery action for your integration.

HTTP/1.1 400 Bad Request

{
  "message": "corridor is required",
  "code": "INVALID_REQUEST"
}

HTTP/1.1 401 Unauthorized

{
  "message": "Invalid API key."
}

HTTP/1.1 429 Too Many Requests
Retry-After: 37

{
  "message": "Rate limit exceeded. Try again in 37 seconds."
}

HTTP/1.1 503 Service Unavailable
Retry-After: 120

{
  "message": "Signal provider temporarily unavailable. Retry after 2 minutes.",
  "unavailable_signals": ["fx_volatility", "network_healthy"]
}

Rate Limits

Public endpoints are rate limited per IP. Authenticated endpoints are gated per API key. Exceeding any limit returns 429 Too Many Requests with a Retry-After header telling you when to retry.

Retry-After header

When a 429 is returned, the response includes a Retry-After header with the number of seconds until your limit resets. Implement exponential backoff starting from that value:

HTTP/1.1 429 Too Many Requests
Retry-After: 37
Content-Type: application/json

{ "message": "Rate limit exceeded. Try again in 37 seconds." }

Burst behaviour

Requests are counted on a rolling window, not a fixed clock boundary. A burst of requests within the same second counts against the per-minute limit. If you need higher throughput, contact taseenrayed@paykx.co.uk to discuss a higher-rate tier.

Retry Guidance

Not every error is worth retrying. Use the table below to decide whether to retry, fix credentials, or escalate — and how quickly.

Exponential backoff pattern

async function verifyWithRetry(payload, apiKey, maxAttempts = 4) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const res = await fetch("https://api.paykx.co.uk/api/v1/verify", {
      method: "POST",
      headers: { "Authorization": "Bearer " + apiKey, "Content-Type": "application/json" },
      body: JSON.stringify(payload),
    });
    if (res.ok) return res.json();
    if (res.status === 429) {
      const wait = parseInt(res.headers.get("Retry-After") ?? "5", 10) * 1000;
      await new Promise(r => setTimeout(r, wait));
    } else if (res.status >= 500) {
      await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 1000));
    } else {
      throw Object.assign(new Error("PAYKX error " + res.status), { status: res.status });
    }
  }
  throw new Error("Max retries exceeded");
}

Request Traceability

Every PAYKX response includes fields and headers that let you correlate a decision back to the exact request that produced it — in your logs, in your UI, and in support escalations. Traceability is part of the Execution Assurance contract: if you acted on a PAYKX decision, you can always prove what the engine said and when.

Response fields

Response headers

Passing a correlation ID

Include correlation_id in your request body to bind the PAYKX decision to your own transaction reference. It is echoed back on the response and stored with the verification record.

{
  "corridor": "GB-NG",
  "amount": 2500,
  "currency": "GBP",
  "correlation_id": "your-internal-payment-ref-abc123"
}

// Response includes:
{
  "request_id": "paykx-req-a3f9c2",
  "correlation_id": "your-internal-payment-ref-abc123",
  "evaluated_at": "2026-07-19T11:42:00.000Z",
  "api_version": "1.2",
  "decision": "GO",
  ...
}

Retrieving verification history

Every verification you run is stored and retrievable. Use your API key to query your own record set — cross-key access is not permitted.

GET /api/verifications
Authorization: Bearer pk_test_xxxxx

// Returns an array of your verification records including:
// request_id, corridor, decision, score, confidence, evaluated_at, correlation_id

Decision Model

PAYKX evaluates seven independent signals across five risk dimensions. Every signal is weighted, the weights produce a composite score, and the score determines the decision band. There is no black-box model — every decision is auditable.

Seven signals — what each one measures

PAYKX does not expose proprietary scoring weights or raw data sources, but the category of inputs feeding each signal is documented here so you can reason about what a flag means and what to do about it.

Execution Uncertainty Score

The Execution Uncertainty Score (EUS) is a derived operator metric surfaced in Replay Analysis reports. It provides a single headline number summarising the concentration of DEGRADED and NO-GO decisions across an analysed transaction portfolio — giving operators an immediate orientation before reading the full report.

How it is calculated

EUS is computed directly from the replay results — it is not a separate model. The formula is:

EUS = round( min(100,  no_go_pct × 3.5  +  degraded_pct × 1.0) )

Where no_go_pct and degraded_pct are the percentage of transactions in each decision band from the replay. Both inputs come from the same PAYKX decisions already present in the report — EUS adds no new scoring logic.

Why NO-GO is weighted higher than DEGRADED

NO-GO decisions represent execution conditions severe enough for PAYKX to block a payment entirely. DEGRADED decisions indicate conditions that may warrant review but do not necessarily prevent execution. The 3.5× weight on NO-GO reflects that asymmetry — a portfolio with 10% NO-GO carries meaningfully more operational risk than one with 10% DEGRADED, and the score should reflect that difference.

Score levels and thresholds

These thresholds are PAYKX guidance derived from the scoring formula. They will be calibrated against real partner replay data as design partners share historical transaction outcomes. Thresholds may shift as calibration data is incorporated.

What EUS is not

EUS is a summary statistic, not a predictive model output. It does not claim to predict future failure rates, guarantee operational outcomes, or replace analysis of the full report. Use it as an orientation metric — the opening number in a Shadow Diagnostic conversation — before reviewing decision distribution, corridor health, and top risk signals in detail.

Accessing EUS via API

EUS is returned automatically in every POST /api/v1/batch-assess response under execution_uncertainty_score. A standalone methodology reference is also available:

GET /api/v1/methodology

Returns the formula, band definitions, weighting rationale, and calibration status as structured JSON — suitable for embedding in operator dashboards or internal documentation.

Reason Codes

Every response includes a reasons array of objects (each with a code and a message) and a flat reason_codes array for backward-compatible consumers. Use these codes to drive downstream logic — retry routing, manual review queues, or user messaging. These codes are part of the API contract and will not be removed without a deprecation notice.

Transactions above £50,000 are subject to a policy cap that floors the verdict at DEGRADED. This reflects conservative execution policy for high-value transfers pending corridor-specific calibration.

Using reason codes in your application

Read reason_codes (flat array) or reasons (array of objects with code and message) to drive consistent user experiences. Build your routing logic around the code strings — they are stable API contract values and will not change without a deprecation notice.

const data = await res.json();

switch (data.decision) {
  case "GO":
    // Safe to execute — all signals clear
    await executePayment(payload);
    break;

  case "DEGRADED":
    if (data.reason_codes.includes("POLICY_CAP_APPLIED")) {
      // High-value transfer needs manual approval
      await queueForManualReview(payload, data.request_id);
    } else if (data.reason_codes.includes("NETWORK_DEGRADED")) {
      // Rail issue — retry in 30–60s
      scheduleRetry(payload, 45_000);
    } else if (data.reason_codes.includes("HIGH_FX_VOLATILITY")) {
      // Show user a warning and ask to confirm at new rate
      showFxWarning(data.reasons.find(r => r.code === "HIGH_FX_VOLATILITY").message);
    } else {
      await routeToPartnerB(payload);
    }
    break;

  case "NO-GO":
    if (data.reason_codes.includes("HIGH_FRAUD_SIGNAL")) {
      // Hard block — do not allow retry
      blockAndEscalate(payload, data.request_id);
    } else {
      // All other NO-GO — inform user and stop
      showUserError("This transfer cannot proceed right now.");
    }
    break;
}

data = resp.json()
decision = data["decision"]
codes = data["reason_codes"]

if decision == "GO":
    execute_payment(payload)

elif decision == "DEGRADED":
    if "POLICY_CAP_APPLIED" in codes:
        queue_for_manual_review(payload, data["request_id"])
    elif "NETWORK_DEGRADED" in codes:
        schedule_retry(payload, delay_seconds=45)
    elif "HIGH_FX_VOLATILITY" in codes:
        show_fx_warning(next(r["message"] for r in data["reasons"]
                            if r["code"] == "HIGH_FX_VOLATILITY"))
    else:
        route_to_partner_b(payload)

elif decision == "NO-GO":
    if "HIGH_FRAUD_SIGNAL" in codes:
        block_and_escalate(payload, data["request_id"])
    else:
        show_user_error("This transfer cannot proceed right now.")

Architecture

PAYKX sits in front of your existing payment flow as an independent decision step. It never touches funds. It only returns a decision you act on.

Request flow

A single POST /api/v1/verify call walks through the following steps inside PAYKX Rail before a decision is returned:

Decision pipeline

Request body
  ↓ Zod schema validation
  ↓ Auth: SHA-256(token) vs approved hash set
  ↓ Idempotency: key seen? → return cached result
  ↓ Corridor: normalise → cooldown check
  ↓ Signal probes (7 parallel evaluations)
      fraud_flags  network_healthy  balance_sufficient
      fx_volatility  operation_valid  historical_failure_rate  cop_overridden
  ↓ Weighted sum → composite score [0.00 – 1.00]
  ↓ Multi-flag penalty (3+ flagged → −25%)
  ↓ Policy gate (amount thresholds)
  ↓ Decision band: ≥0.80 GO | 0.48–0.79 DEGRADED | <0.48 NO-GO
  ↓ Reason codes derived from flagged signals
  ↓ recommended_action (DEGRADED only)
  ↓ Write verification record → return response

Latency

The response_ms field on every response gives you the actual server-side processing time for that specific call. Use it to monitor your own p95 and p99 over time.

Audit trail

Every PAYKX response is an immutable, timestamped record. The following fields together form a complete audit entry for any pre-execution assurance check:

Enterprise Integration Guide

A production integration follows five deterministic steps. Each step maps to a PAYKX API call or an action in your own system.

POST /api/v1/request-access
{ "name": "Acme Payments", "email": "eng@acme.com", "reason": "..." }
→ Your key is sent by email. Store it in your secrets manager — never in code.

POST /api/v1/verify
Authorization: Bearer <your-key>
Idempotency-Key: <your-payment-uuid>
{ "corridor": "GB-NG", "amount": 5000, "currency": "GBP" }

{ "decision": "GO", "score": 0.87, "confidence": 0.94,
  "request_id": "req_...", "reason_codes": [] }

{ "decision": "DEGRADED", "score": 0.61, "confidence": 0.72,
  "reason_codes": ["HIGH_FX_VOLATILITY"] }

{ "decision": "NO-GO", "score": 0.31, "confidence": 0.88,
  "reason_codes": ["FRAUD_FLAG_ACTIVE", "NETWORK_DEGRADED"] }

// GO: proceed immediately
if (decision === 'GO') initiateTransfer(payment);

// DEGRADED: queue for review, or override if approved
if (decision === 'DEGRADED') holdForReview(payment);

// Record a compliance override if approved manually
POST /api/v1/override
{ "request_id": "PAYKX-2026-622", "action": "EXECUTE",
  "reason_code": "COMPLIANCE_APPROVED", "justification": "..." }

// NO-GO: block and do not proceed
if (decision === 'NO-GO') preventExecution(payment);

GET /api/v1/audit/PAYKX-2026-{id}
Authorization: Bearer <your-key>
→ Returns decision + all signals + override (if any) in one response.
→ Immutable. Write-once. Cannot be modified after creation.

Decision Lifecycle

Every payment intent flows through a fixed lifecycle. PAYKX produces the decision — your system acts on it — and the audit record closes the loop.

Reading the diagram

Webhook Retry Policy

PAYKX guarantees at-least-once delivery for every webhook event. If your endpoint does not return a 2xx response, the platform retries automatically on a fixed backoff schedule.

Retry schedule

After 5 failed attempts the event is dropped. Events are not replayed beyond the retry window.

Event envelope fields

Every delivery includes metadata fields to support idempotent processing:

{
  "event":      "payment.override.created",
  "event_id":   "evt_3f8a2c1d9e7b4051",
  "created_at": "2026-07-20T14:23:01.000Z",
  "attempt":    1,
  "data": { ... }
}

• event_id — stable across all retry attempts for the same event. Use this to deduplicate on your side.
• attempt — integer starting at 1. Increments with each retry so you can log delivery history.
• X-PAYKX-Attempt — also sent as an HTTP header on every delivery request.
• X-PAYKX-Signature — HMAC-SHA256 of secret + body. Recompute this on every attempt to verify authenticity before processing.

Responding correctly

Your endpoint must return HTTP 2xx within 5 seconds. Return any other status code — or let the connection time out — and PAYKX will schedule a retry.

Response headers on all enterprise endpoints

Every enterprise API endpoint also returns two environment headers for integration diagnostics:

X-PAYKX-Version:     v1
X-PAYKX-Environment: sandbox

API Key Permissions

Today every API key grants full access to all authenticated endpoints. The permissions model below is designed for enterprise buyers who need fine-grained role separation — for example, allowing a treasury team to read decisions but not submit overrides.

Planned permission scopes

Future API key schema

When permissions are introduced, API key metadata returned from the access-request flow will include a permissions array:

{
  "api_key":    "pk_live_...",
  "issued_at":  "2026-07-20T00:00:00Z",
  "permissions": [
    "decision:read",
    "audit:read",
    "override:create",
    "webhook:manage"
  ]
}

Requests made with a key that lacks the required scope will receive a 403 Forbidden response with a required_scope field identifying which permission is missing.

PAYKX vs Payment Orchestration

The single most common question from bank and fintech buyers. PAYKX and payment orchestration layers solve adjacent problems — they are designed to work together, not replace each other.

How they fit together in a payment flow

Capability comparison

PAYKX and Fraud, AML & Compliance Layers

PAYKX does not evaluate whether a customer is legitimate. It evaluates whether the payment route is ready to execute.

Fraud detection, AML, and KYC systems analyse customer behaviour, identity, and transaction risk. They answer:

"Should this transaction from this customer be approved?"

PAYKX analyses payment execution conditions before funds are committed. It answers:

"Is this corridor and payment partner reliable enough to execute through right now?"

These layers are complementary.

PAYKX does not replace:

• KYC
• AML screening
• fraud detection
• transaction monitoring

PAYKX operates upstream as an execution assurance layer.

Security & Compliance

A complete reference for the security controls, data handling practices, and compliance assurances that enterprise and regulated buyers need to evaluate PAYKX for production use.

🔒 Authentication

All authenticated API endpoints require a Bearer token in the Authorization header. Tokens are long random strings (minimum 128 bits of entropy) issued through the access request flow.

Authorization: Bearer pk_live_<your-key>

• Keys are hashed (SHA-256) before storage — the plaintext key is never persisted.
• The plaintext key is returned once only at issuance. Store it in a secrets manager (e.g. AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager).
• Keys have no expiry by default in sandbox. Production keys will support configurable TTL and rotation policies.
• Admin operations (key issuance, access approval) require a separate X-Admin-Key header with a distinct secret — no API key can perform admin actions.

🔐 Encryption

📄 Audit Retention

Every verification decision is stored as a write-once immutable record. Records are never modified or deleted in response to API calls.

Retention periods are set to align with FCA and EBA record-keeping requirements for payment service providers. Contact us if your jurisdiction requires a different retention window.

🔑 API Key Management

• Never embed keys in frontend code. API keys must only be used from server-side code where they cannot be extracted by browser inspection or public repos.
• Use environment variables or a secrets manager. Do not hardcode keys in source files. Treat them like database passwords.
• Rotate keys if compromised. Email access@paykx.co.uk to revoke a key immediately. Revocation takes effect within 60 seconds.
• Use one key per environment. Maintain separate keys for development, staging, and production. Never use a production key in test environments.
• Scope keys by role (roadmap). See the API Key Permissions section for the planned granular permission model.

🔗 Webhook Security

Every webhook delivery is signed with HMAC-SHA256. Your endpoint should verify the signature before processing the payload — this prevents spoofed events from triggering actions in your system.

// Node.js — verify incoming webhook signature
import { createHash } from "crypto";

function verifyWebhook(secret: string, rawBody: string, signature: string): boolean {
  const expected = "sha256=" + createHash("sha256").update(secret + rawBody).digest("hex");
  return expected === signature;
}

// In your handler:
const sig = req.headers["x-paykx-signature"];
const body = req.body; // raw string — do not parse before verifying
if (!verifyWebhook(process.env.PAYKX_WEBHOOK_SECRET, body, sig)) {
  return res.status(401).send("Invalid signature");
}

• The X-PAYKX-Signature header is present on every delivery attempt, including retries.
• Use a constant-time comparison (not ===) to prevent timing attacks — most crypto libraries provide this.
• Store the webhook secret in your secrets manager alongside your API key.
• Acknowledge with 200 OK immediately — do heavy processing asynchronously to avoid timeouts triggering retries.
• See the Webhook Retry Policy for the full retry schedule and deduplication guidance.

👤 Data Handling

Use Cases

Where a deterministic pre-transaction decision adds the most value.

Status

Live health of the PAYKX API, checked from your browser right now.

Corridors fully validated: GB-NG, NG-GB.

How PAYKX helps payment teams scale

This section is for payment operations, treasury, and compliance leads — not engineers. It explains what changes when PAYKX is in the stack.

Before PAYKX

Payment teams managing cross-border execution typically rely on:

• Provider dashboards — checked manually, updated on delay, one per partner
• Failure queues — discovered after settlement, not before execution
• Spreadsheets — corridor performance tracked offline, not in the payment path
• Escalations — when a payment fails, the first signal is a customer complaint

The result: execution decisions are made without real-time signal data. Risk is discovered retrospectively.

After PAYKX

One API call before each payment returns:

• Execution confidence — a score reflecting current corridor and partner health, not historical averages
• Reason codes — machine-readable flags with plain-English business explanations, readable by compliance and treasury teams
• Audit evidence — every decision is logged with probe-level detail, exportable for regulatory review
• Operational recommendations — the API tells the operator what to do, not just what the signals say: proceed, reroute, request KYC, or hold

What this replaces

Audience reference

• Payments operations — use /verify to gate execution; use recommended_action to automate rerouting decisions
• Treasury — use operational_implications to understand settlement and liquidity exposure before funds move
• Compliance — use /audit and /explanation to produce decision evidence for regulatory review
• Engineering — integrate via REST; see Quickstart and API Reference

Design Partner Data Flow

Bring PAYKX a payment execution question. We replay your historical evidence to show what PAYKX would have flagged and compare those signals with observed outcomes — each stage is discrete, reversible, and does not affect live payments.

What question can a replay answer?

Start with a payment execution question, such as “where did manual intervention start?”, “which payments later failed?”, or “what risks were visible before a delay?”. Then provide the historical evidence needed to test it:

• Corridor — source and destination country (e.g. GB-NG)
• Amount and currency — transaction value
• Outcome (optional but useful) — whether the payment succeeded or failed, so alignment can be measured

Customer names, account numbers, customer IDs, and other personal data are not required and must be removed. After your request, PAYKX provides a CSV template and secure upload instructions — do not send raw payment files by email.

How long does each stage take?

Each stage has a clear exit condition. You can stop at any point — nothing is irreversible until you choose to move to active gating.

Start here

Request a limited shadow replay → — tell us your intended corridor and sample size. We'll send a CSV template and secure upload instructions within one business day; the delivery timeline is agreed only after PAYKX confirms the dataset is usable and assigns capacity.

Changelog

Notable changes to the PAYKX API and developer docs.