Developer Documentation

Overview & Multi-Network Settlement Architecture

Polygon (137) · Base (8453) · Arbitrum (42161) · TON (-239)

Accept USDC and USDT across Polygon PoS (`137`), Base (`8453`), Arbitrum One (`42161`), and TON (`-239`) with atomic on-chain multi-party splits at the moment of payment.

Every checkout session deterministically computes a unique EIP-1167 minimal proxy address (across EVM chains Polygon PoS (`137`), Base (`8453`), and Arbitrum One (`42161`), alongside deterministic Jetton settlement routing on TON (`-239`)) off-chain with zero gas using CREATE2. The address cryptographically commits to the session salt, token contract, recipient addresses, and basis-point split ratios.

When the buyer sends USDC or USDT to that deposit address, ThreeWaySplitFactory.flush() deploys the 45-byte proxy and distributes the balance across all recipients in a single atomic transaction—so your platform never custodies seller funds.

Direct Stablecoin Transfers (Zero On-Ramp Fees)

Buyers holding USDC or USDT in Revolut Crypto Send, MetaMask, Phantom, Rabby, or Telegram TON Wallet transfer directly to the session's deterministic deposit address with zero on-ramp fees, settling directly on-chain within seconds.

Third-Party Fiat On-Ramps (Card / Bank Conversion)

Buyers without existing stablecoins can fund their purchase via Revolut Ramp, Coinbase Onramp, or MoonPay. Card, Apple Pay, or bank conversion is handled entirely by the licensed third-party provider, which delivers USDC/USDT straight to the deterministic split address.

5-Stage Persistent Settlement State Machine

Idempotent Execution

Every checkout session progresses through a deterministic, crash-recoverable 5-stage state machine from deposit detection to signed webhook delivery.

1. PAYMENT_DETECTED

Incoming transfer observed at deterministic deposit address

2. VALIDATION

Token contract, chain ID, minimum amount, and block confirmation check

3. SETTLEMENT_QUEUE

Idempotent lock & retry queue preventing double-processing

4. ON_CHAIN_FLUSH

Atomic execution of ThreeWaySplitFactory.flush() to all recipients

5. SETTLED

Split transaction confirmed on-chain & signed checkout.session.completed webhook delivered

Authentication

Sandbox / Test Example Credential

Authenticate server-to-server requests with your secret Bearer API key. Public documentation examples use sandbox test credentials (rk_test_... and whsec_test_...).

Authorization: Bearer rk_test_51KitePaySandboxExampleKey

Split modes & platform extra fee line items

One smart contract supports both 3-way marketplace seller splits and 2-way direct platform charges. KitePay always takes its processor fee on the grand total.

Mode	Use case	1. Seller share	2. Platform	3. KitePay
three_way	Buyer purchases a marketplace order (`$25` base + `$4` platform service fees = `$29` total)	84% of $25 base = $21.00 (0% of extra fees)	15% of base ($3.75) + $4.00 extra fees net = $7.71	1% of $29.00 total = $0.29
platform_direct	Seller or customer pays platform for SaaS plan, subscription, or featured listing (`$50` total)	$0.00 (2-way mode)	99% of $50.00 = $49.50	1% of $50.00 = $0.50

Create a checkout session

POST /api/v1/checkout/sessions

curl -X POST https://kitepay.tech/api/v1/checkout/sessions \
  -H "Authorization: Bearer rk_test_51KitePaySandboxExampleKey" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Marketplace Order #4091",
    "amount": 25.00,
    "asset": "USDC_POLYGON",
    "splitMode": "three_way",
    "destinationAddress": "0x851F4eb9e8e9c7b05833840b34Ca616187dF1748",
    "platformAddress": "0x1707683F2B00462C31e8367eBE7f8f1347ab43B6",
    "platformFeeBps": 1500,
    "feeItems": [
      { "label": "Platform service fee", "amount": 2.50 },
      { "label": "Buyer protection fee", "amount": 1.50 }
    ],
    "orderId": "ord_4091",
    "successUrl": "https://yourplatform.com/orders/ord_4091"
  }'

Reusable payment links (`POST /api/v1/payment-links`)

Create a permanent `/p/plink_...` URL that spins up a fresh checkout session every time a buyer opens it.

Send the same parameters (`title`, `amount`, `asset`, `splitMode`, `destinationAddress`, `feeItems`) to POST /api/v1/payment-links. Share the returned /p/plink_... URL anywhere—each visitor receives their own isolated CREATE2 deposit address.

Webhooks & HMAC-SHA256 verification

Verify the `X-KitePay-Signature` header using your webhook secret.

import crypto from "crypto";

export function verifyKitePayWebhook(
  rawBody: string,
  signatureHeader: string | null,
  webhookSecret = "whsec_test_51KitePayWebhookExampleSecret"
): boolean {
  if (!signatureHeader) return false;
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((kv) => kv.trim().split("="))
  );
  if (!parts.v1) return false;

  const expected = crypto
    .createHmac("sha256", webhookSecret)
    .update(rawBody)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(parts.v1, "hex"),
    Buffer.from(expected, "hex")
  );
}

Supported networks & contract addresses

Immutable KitePay processor wallet: 0xF41627F0972BbB04Fae10b0737a79fECd6A6A46B

Asset key	Network	Mainnet contract	Amoy testnet (80002)
USDC_POLYGON	Polygon PoS (137)	0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359	0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582 (Amoy 80002)
USDT_POLYGON	Polygon PoS (137)	0xc2132D05D31c914a87C6611C10748AEb04B58e8F	0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582 (Amoy 80002)
USDC_BASE	Base (8453)	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913	0x036CbD53842c5426634e7929541eC2318f3dCF7e (Sepolia 84532)
USDC_ARBITRUM	Arbitrum One (42161)	0xaf88d065e77c8cC2239327C5EDb3A432268e5831	0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d (Sepolia 421614)
USDT_ARBITRUM	Arbitrum One (42161)	0xFd086bc7CD5C481DCC9C85ebE478A1C0b69FCbb9	0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d (Sepolia 421614)
USDT_TON	TON / Telegram (-239)	EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs	kQD0GKBM8ZbryVk2aESmzfU6b9b_8era_IkvBSELujFZPsyy (Testnet -3)

Smart-Contract Security & Verification (ThreeWaySplitFactory.sol)

Idempotent Multi-Deposit Handling: If a buyer sends multiple deposits or partial top-ups to the same deterministic deposit address, ThreeWaySplitFactory.flush() checks if (clone.code.length == 0) to deploy the EIP-1167 minimal proxy only on the first flush, and then calls executeCloneSplit on every subsequent deposit without reverting.
Immutable Processor Treasury: The KitePay processor wallet (0xF41627F0972BbB04Fae10b0737a79fECd6A6A46B) is compiled as a Solidity immutable state variable and cannot be mutated post-deployment.
Cryptographic Salt Commitment: The CREATE2 salt commits to the session ID, token address, seller destination address, platform treasury address, and basis-point split parameters—making it impossible to alter payout recipients after the deposit address is generated.