Technical & Partner Integration Overview

API Reference & Onramp Architecture

Base API Endpoint: https://api.paycandor.com • Settlement Assets: USDC on Base (8453) & Polygon (137)

Architecture Note for Onramp Partners: Candor Pay operates strictly as B2B invoicing and checkout orchestration software. Merchants authenticate with scoped API keys (X-API-Key) and supply their own external EVM wallet address. Candor Pay never takes custody of buyer fiat or merchant USDC balances.

1. Create an Invoice Session

Merchants create USD-denominated checkout sessions via POST /v1/invoices. Each call computes a deterministic per-invoice CREATE2 deposit address bound immutably to the merchant's external payout wallet and configured fee split.

curl -X POST https://api.paycandor.com/v1/invoices \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cnd_live_..." \
  -d '{
    "amount": 125.00,
    "currency": "USD",
    "customer_email": "buyer@example.com",
    "external_order_id": "INV-2048",
    "description": "Annual Software License #2048",
    "chain": "base"
  }'
{
  "success": true,
  "data": {
    "link_id": "cnd_a91f4c82d31e7b049210",
    "status": "active",
    "amount": 125,
    "currency": "USD",
    "payment_url": "https://checkout.paycandor.com/pay/cnd_a91f4c82d31e7b049210",
    "deposit_address": "0x...",
    "payout_wallet_evm": "0x...",
    "settlement_chain": "base",
    "settlement_asset": "USDC",
    "expires_at": "2026-11-21T07:30:00.000Z"
  }
}

2. Supported Licensed Onramp Adapters

Adapter ID Partner Rail Supported Settlement Integration Role
coinbase_cdp Coinbase CDP Onramp Base / Polygon USDC Apple Pay & guest debit checkout
stripe_crypto Stripe Crypto Onramp Polygon / Base USDC Link & card fiat-to-USDC session
topper Topper by Uphold Polygon / Base USDC Global card & mobile pay widget
robinhood_connect Robinhood Connect Polygon / Base USDC Funded brokerage & debit transfer

3. Deterministic CREATE2 Split Forwarder

Every invoice derives a 32-byte salt from (chainId, usdcContract, merchantWallet, feeRecipient, feeBps, linkId). Purchased USDC is delivered to that deterministic forwarder address and atomically swept on-chain via CandorSplitForwarder.sweep() directly to the merchant's external EVM wallet.

4. HMAC-SHA256 Webhook Verification

Settlement events and webhook.test diagnostics are signed over the raw UTF-8 JSON body using HMAC-SHA256 and sent in the X-Candor-Signature header as lowercase hex.

const expected = crypto
  .createHmac("sha256", process.env.CANDOR_WEBHOOK_SECRET)
  .update(rawBody, "utf8")
  .digest("hex");

const provided = req.headers["x-candor-signature"];
const isValid = crypto.timingSafeEqual(
  Buffer.from(expected, "hex"),
  Buffer.from(provided, "hex")
);