PayHub API

REST API for integrating PayHub's dispute and chargeback rail into your agent payment system. Base URL: http://localhost:3001 (self-hosted).

Authentication

All requests are unauthenticated except POST /payments/:id/resolve, which requires an arbiter token in the request body.

// Arbiter auth — include in resolve requests
{
  "authToken": "your_arbiter_token"   // set via ARBITER_AUTH_TOKEN in .env
}

Endpoints

POST /payments/preflight

Run before calling initiatePayment on-chain. Verifies both parties hold a valid A-Pass, checks A-Token transfer eligibility via the CCP protocol, and generates a Travel Rule reference.

// Request
POST /payments/preflight
{
  "payerAddress":    "0xABC...",
  "merchantAddress": "0xDEF...",
  "amount":          "50000000",   // in token base units (6 decimals)
  "asset":           "0x...",      // A-Token contract address
  "orderId":         "order_123"
}

// Response 200
{
  "cleared":       true,
  "apassPayer":    "434",          // Cleanverse A-Pass ID — store and pass to contract
  "apassMerchant": "435",
  "ccpRiskScore":  2,
  "payerTier":     "20",
  "merchantTier":  "20",
  "travelRuleId":  "tr_pre_abc..."
}

// Response 403 — payment blocked
{
  "error": "Payer does not hold a valid A-Pass",
  "detail": { ... }
}

POST /payments/register

Call immediately after initiatePayment confirms on-chain. Stores enriched metadata so the audit trail can be reconstructed.

// Request
POST /payments/register
{
  "paymentId":       "0x...",    // bytes32 returned from initiatePayment event
  "orderId":         "order_123",
  "payerAddress":    "0xABC...",
  "merchantAddress": "0xDEF...",
  "amount":          "50000000",
  "asset":           "0x...",
  "apassPayer":      "434",
  "apassMerchant":   "435",
  "travelRuleId":    "tr_pre_abc...",
  "txHash":          "0x..."
}

// Response 200
{ "ok": true, "paymentId": "0x..." }

Disputes

Disputes are identity-bound — only the original A-Pass-verified payer can open one. The backend re-verifies identity at dispute time before the on-chain transaction is submitted.

// Step 1 — verify payer identity (before submitting on-chain)
POST /payments/:id/dispute/preflight
{ "callerAddress": "0xABC..." }

// Response 200
{ "eligible": true, "apassId": "434", "windowClosesAt": "2026-06-21T..." }

// Step 2 — register after on-chain openDispute confirms
POST /payments/:id/dispute/register
{ "reason": "Merchant did not deliver", "txHash": "0x..." }

// Step 3 — arbiter resolves (CCP screens refund leg first)
POST /payments/:id/resolve
{
  "inFavorOfPayer": true,
  "verdict":        "Merchant did not provide delivery proof. Refund issued.",
  "authToken":      "your_arbiter_token"
}

GET /payments/:id/audit

Returns a signed HMAC audit bundle generated at resolution time. Contains the full compliance trail for regulators.

// Response 200
{
  "payment": {
    "id":     "0x...",
    "status": "REFUNDED"
  },
  "identity": {
    "payerAPass":    "434",
    "merchantAPass": "435"
  },
  "compliance": {
    "ccpPayment": { "cleared": true, "riskScore": 2 },
    "ccpRefund":  { "cleared": true },
    "travelRule": ["tr_pre_abc..."]
  },
  "resolution": {
    "verdict":    "Merchant did not provide delivery proof. Refund issued.",
    "resolvedAt": "2026-06-18T10:00:00Z",
    "txHash":     "0x..."
  },
  "signature": "sha256=..."    // HMAC-signed — tamper-evident
}

Smart Contract

Deployed at 0x7BBDa4409e300eaDB0A61F137498480c96173C9e on Monad Testnet (Chain ID 10143).

// Key functions

// Payer calls after backend preflight
initiatePayment(
  address merchant,
  address token,
  uint256 amount,
  string  orderId,
  string  apassPayer,      // A-Pass ID stored on-chain for audit
  string  apassMerchant,
  uint256 customFinality   // 0 = use 3-day default
) returns (bytes32 paymentId)

// Payer opens dispute during dispute window (2 days)
openDispute(bytes32 paymentId, string reason)

// Merchant submits evidence (24h response window)
respondToDispute(bytes32 paymentId, string evidence)

// Arbiter (or owner) resolves
// inFavorOfPayer=true → refund to original payer
resolveDispute(bytes32 paymentId, bool inFavorOfPayer, string verdict)

// Anyone can call after merchant misses response window
autoResolveExpiredDispute(bytes32 paymentId)

Cleanverse Compliance Primitives

PayHub enforces compliance at every gate using the Cleanverse Cooperate API. No on-chain transaction is submitted without a backend pre-check.

Walk through the full integration flow — compliance checks, escrow, dispute, and audit download.