PAYKX Rail Verification API

Deterministic certainty layer for high-friction payment corridors. All responses in shadow/demo mode are simulated.

Use your issued API key in the Authorization: Bearer <key> header to authenticate requests.

Version 1.2 Shadow / Demo Mode Contact: taseenrayed@paykx.co.uk

POST /api/v1/verify Verify a payment corridor ⌄

Runs a deterministic risk assessment on the specified corridor using seven weighted signals: fraud_flags (30%), network_healthy (25%), balance_sufficient (15%), fx_volatility (10%), operation_valid (10%), historical_failure_rate (5%), cop_overridden (5%).
Score ≥ 0.80 → GO | 0.48–0.79 → DEGRADED | < 0.48 → NO-GO

Parameters

Name	In	Type	Description
mode	query	string	shadow (default) or live
Authorization*	header	string	Bearer <your-api-key>

Request Body

Field	Type	Required	Description
corridor	string	YES	e.g. UK-NIGERIA, US-UK

Example Response

"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"

Responses

200Verification result returned successfully

400Invalid request body — corridor field missing or malformed

401Missing or invalid API key

Try it out

GET /api/health API Health Check ⌄

Returns the current health status of the PAYKX Rail API, including version and mode. No authentication required.

Example Response

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

Responses

200API is healthy and running

Try it out