Technical & Partner Integration Overview
API Reference & Onramp Architecture
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")
);