Developer Integration Spec

Bearer Token

GET /api/v1/payments HTTP/1.1
Host: api.kxco.io
Authorization: Bearer kxco_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

ML-DSA-65 (Post-Quantum) — per-request signing

POST /api/v1/payments HTTP/1.1
Authorization: Bearer kxco_live_xxxx
X-KXCO-Timestamp: 1748000000
X-KXCO-Signature: <ML-DSA-65 signature of "timestamp.method.path.body_hash">
Content-Type: application/json

Register your ML-DSA public key

POST /api/admin/institutions/:id/ml-dsa
{
  "publicKey": "<1952-byte ML-DSA-65 public key, hex-encoded>"
}

Initiate a payment

POST /api/v1/payments
{
  "endToEndId": "E2E-2026-001",
  "debtor": {
    "name":    "Jane Smith",
    "account": "KXCO-ACC-20260101-AABBCC",
    "agent":   "YOURBANK"
  },
  "creditor": {
    "name":    "Supplier Co Ltd",
    "account": "KXCO-ACC-20260101-XXYYZZ",
    "agent":   "PARTNERBANK"
  },
  "amount": {
    "currency": "USD",
    "value":    "10000.00"
  },
  "remittanceInfo": "Invoice #2026-089"
}

Response

{
  "uetr":      "550e8400-e29b-41d4-a716-446655440000",
  "txRef":     "KXCO-PMNT-20260518-AB12CD",
  "status":    "INITIATED",
  "riskHeld":  false,
  "createdAt": "2026-05-18T10:22:00.000Z"
}

Payment lifecycle

Register an endpoint

POST /api/admin/institutions/:id/webhooks
{
  "url":    "https://yourbank.com/webhooks/kxco",
  "events": ["payment.settled", "payment.failed", "payment.returned"]
}

Request headers on delivery

Verifying either signature alone is sufficient. Verifying both gives defence-in-depth: HMAC blocks tampering by any party who knows the shared secret, and ML-DSA-65 cryptographically binds the message to the KXCO platform identity even if the HMAC secret is ever leaked.

Fetch the platform public key (one-time, pin and cache)

GET /wallet/api/.well-known/kxco-pq-pubkey

// Response
{
  "alg":         "ML-DSA-65",
  "spec":        "NIST FIPS 204",
  "publicKey":   "<3904 hex chars = 1952 bytes>",
  "kid":         "aa29f37ab7f4b2cf",
  "sigEncoding": "hex",
  "msgFormat":   "{X-KXCO-Timestamp}.{raw_request_body}"
}

Pin the public key in your config and treat the kid as the active key identifier. If you receive a delivery with an unexpected kid, refresh the well-known endpoint.

Verify the classical HMAC signature (Node.js)

const crypto = require('crypto')

function verifyHmac(secret, timestamp, rawBody, sigHeader) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(sigHeader),
    Buffer.from(expected)
  )
}

Verify the post-quantum signature — recommended (Node.js)

// npm install kxco-post-quantum
const { webhook } = require('kxco-post-quantum')

const PINNED_KID    = 'aa29f37ab7f4b2cf'                     // current KXCO production kid
const PINNED_PUBKEY = Buffer.from('...3904 hex chars...', 'hex')

function verify(req) {
  const headers = Object.fromEntries(
    Object.entries(req.headers).map(([k, v]) => [k.toLowerCase(), v])
  )
  const r = webhook.verifyDelivery({
    headers,
    rawBody:     req.rawBody,        // byte-for-byte exactly as received
    pqPublicKey: PINNED_PUBKEY,
    pinnedKid:   PINNED_KID,
  })
  return r.pqOk && r.timestampOk && r.kidOk
}

The same package handles HMAC verification, kid pinning, and the timestamp replay window. Source: npmjs.com/package/kxco-post-quantum.

Or use any FIPS 204 implementation directly

// npm install @noble/post-quantum
const { ml_dsa65 } = require('@noble/post-quantum/ml-dsa')

function verifyPq(headers, rawBody) {
  if (headers['x-kxco-pq-kid'] !== PINNED_KID) return false
  const sig = headers['x-kxco-pq-signature'].replace(/^ml-dsa-65=/, '')
  const ts  = headers['x-kxco-timestamp']
  if (Math.abs(Date.now() / 1000 - parseInt(ts, 10)) > 300) return false
  const msg = Buffer.from(`${ts}.${rawBody}`, 'utf8')
  return ml_dsa65.verify(PINNED_PUBKEY, msg, Buffer.from(sig, 'hex'))
}

Works with @noble/post-quantum, liboqs, the BoringSSL PQ branch, or any FIPS 204 implementation.

Example payload — payment.settled

{
  "event":          "payment.settled",
  "uetr":           "550e8400-e29b-41d4-a716-446655440000",
  "txRef":          "KXCO-PMNT-20260518-AB12CD",
  "instrAmt":       10000.00,
  "instrAmtCcy":    "USD",
  "settlAmt":       8471.23456789,
  "onChainTxHash":  "0xabc123...",
  "sttlmTm":        "2026-05-18T10:35:00.000Z"
}

Retry policy

Available events

Customer registration flow

POST /api/app/auth/register
{
  "name":            "Jane Smith",
  "email":           "jane@example.com",
  "phone":           "+44 7700 000000",
  "password":        "••••••••",
  "institutionCode": "YOURBANK"   // your 8-char BIC-style code
}

// On success: session cookie set, redirect to /app/home

Consumer API endpoints

PWA routes