Request to proof, end to end

How the gateway works

A partner sale request comes in, the gateway authenticates and normalizes it, resolves routing, routes the capture through its CyberSource connection, computes fees, and attaches a tamper-evident proof, all in one response. PaychainX is the orchestration and proof layer; CyberSource is the connected processor, Propelr the pilot partner, and Zero Hash the stablecoin settlement provider. Below are the real artifacts captured from the running gateway.

In plain English

What PaychainX does

When a customer pays, PaychainX is the layer between the store and the bank. It checks the payment is legitimate, sends it to the card network to collect the money, works out the fees, and then writes a sealed digital receipt for that exact transaction.

Why it matters

That receipt is a fingerprint. If anyone later changes a single detail, the fingerprint no longer matches, so tampering is obvious. Banks and auditors can check it themselves without trusting us. The post-quantum work future-proofs that seal so it stays trustworthy against tomorrow's quantum computers.

For the technical reader, every claim above is backed by the real request, response, and proof artifacts below. For everyone else, that is the whole story: take payments, prove each one, keep the proof valid for the long run.

Request lifecycle

1
POST /v1/integrations/{partner}/sale

API key header, JSON body. Schema validated before any downstream call.

2
Authenticate and validate

Zero Trust: every hop re-validates the request and merchant context. A bad key fails fast with 401.

3
Partner adapter, map to canonical

Terminal, device, store, lane, operator, and session metadata normalized into one canonical request.

4
Merchant vault (Redis)

Routing policy, approved processors, MID, and volume thresholds resolved on the hot path.

5
Risk, AVS, CVV

Decision, score, and flags, plus normalized AVS and CVV so merchant logic is processor-independent.

6
Processor abstraction, CyberSource capture

Stored-credential token captured through a uniform adapter that returns a canonical result.

7
Fee engine

Gross, fee (bps plus fixed), and net computed by the gateway, not the processor.

8
PQ shadow proof (non-blocking)

Canonical result is digested into a proof_id and proof_hash, submitted, and queued for the immutable archive. Runs in parallel, never blocks the capture.

9
200 OK, canonical JSON

Processor-agnostic payment object with pq_proof and fees attached. Same shape regardless of processor.

The request

Partner sale. The API key is server-side only and never exposed. Token is a non-PAN stored-credential reference.

POST /v1/integrations/propelr/sale x-api-key: •••••••••• (never exposed) Content-Type: application/json { "reference": "propelr_test_2", "amount": 11111, "currency": "USD", "terminal_id": "term_001", "device_id": "device_001", "token_id": "ptok_…", "store_id": "store_100", "lane_id": "lane_7", "operator_id": "operator_22", "session_id": "session_abc123" }

The canonical response captured

Processor-agnostic payment object. No PAN, no CVV value, no PII.

{ "ok": true, "result": { "status": "captured", "amount": 11111, "currency": "USD", "processor": "cybersource", "processor_transaction_id": "7810344559206579203814", "avs": { "avs_normalized": "match" }, "cvv": { "cvv_normalized": "match" }, "risk": { "decision": "allow", "score": 20 }, "channel": "terminal", "pq_proof": { "proof_id": "pq_316d746f6b98aab7", "proof_hash": "c078c435…a9bc5544", "hash_algorithm": "sha256", "status": "submitted", "archive_pending": true }, "fees": { "gross_amount": 11111, "fee_amount": 63, "net_amount": 11048, "fee_bps": 30, "fixed_fee": 30 } } }

Proof artifacts, deterministic by content

captured evidence

Each captured payment binds a SHA-256 digest to its full canonical content. Identical canonical inputs reproduce the same hash; changing any field changes it. These are real proof hashes observed across live runs.

reference = propelr_test_2 amount = 11111 (store, lane, operator, session set) proof_hash = c078c435136eec533f85ef66cd991dadf3ba003d0f777e07d44ad704a9bc5544 (same hash reproduced under proof_id pq_316d…, pq_efe40610…, pq_77bbdcdc…) reference = pq_test_final amount = 11111 (store, lane, operator, session null) proof_hash = 9d18f72192756164c8bf019215f85376027518d28adc08d12cedab8cd0febfc6 reference = pq_test_final_4 amount = 1111 proof_hash = 55c6ab7c24ad1954eec7549e1dced6227ee34d903f2060f56831e338734bdc02

Two runs with the same amount (11111) but different reference and terminal context produce different hashes, which proves the digest binds the full canonical content, not just the amount. That is the property an auditor needs: recompute the digest from the archived canonical result and it must match, independent of the processor report.

Independent verification

Anyone can verify a proof without trusting the processor report.

# 1) fetch the persisted proof GET /v1/admin/payments/{id}/detail -> proofs[] with proof_hash + hash_algorithm # 2) recompute and compare recomputed = sha256( canonical(result) ) assert recomputed == proof_hash # tamper-evident
Try it live in your browser →

Crypto, today versus roadmap

Integrity digestSHA-256, live
Widen to SHA-512roadmap
PQ signatureML-DSA, roadmap
signature fieldreserved, null today
Envelope shapeunchanged, drop-in

The proof record already reserves the signature and signature_algorithm fields, so the post-quantum upgrade is drop-in and does not change the envelope merchants integrate against.

Admin and reporting APIs

All require authentication. A bad key returns 401.

GET /v1/admin/payments/search?limit=5&offset=0 GET /v1/admin/payments/{id}/detail -> payment + attempts + proofs + webhook_deliveries GET /v1/transactions/daily -> per-day totals, captured and failed counts GET /v1/transactions/export?limit=5

Observability

Gateway computesub-3 ms (2.466 ms observed)
Production end to end~516 to 524 ms
Edge and transportCloudflare, HTTP/2, TLS
Auth fast-fail401 in ~2.4 ms
Webhooksat-least-once, up to 5 retries
Ledgerpersistent, 200+ transactions

Production end-to-end time includes the Cloudflare edge and the live CyberSource round trip; gateway-only compute is sub-3 ms.

Legacy processors process transactions. PaychainX processes, orchestrates, verifies, and audits them.