Payment Rails

Kifly supports three payment rails. Card purchases are always human-confirmed — the buyer opens a payment link and completes it themselves. No tool call ever settles a card purchase on its own.

Rails 2–3 are beta: the code paths are wired and tested against internal test suites but have not yet completed production activation (live key config + first real-money settlement). For new integrations today, use Rail 1.

No autonomous card settlement. Kifly deliberately does not offer a stored-card / reusable-token rail that lets an agent charge a buyer without the buyer confirming. The checkout tool always returns a link the buyer opens themselves. (Connector-directory requirement, 2026-07.)

Rail 1 — Stripe Payment Link (live)

The default rail. The agent handles the entire purchase except the payment step; the buyer pays in Stripe's hosted UI.

Flow

The agent calls checkout (MCP tool) or POST /api/agent/payment-link directly. Kifly creates a Stripe Checkout Session pre-filled with the shipping address and returns:

{
  "session_id": "cs_live_XXXXXXXXXX",
  "payment_url": "https://checkout.stripe.com/c/pay/cs_live_XXXXXXXXXX",
  "amount": 8550,
  "subtotal_cents": 7000,
  "delivery_fee_cents": 1550,
  "currency": "usd",
  "buyer_token_status": "resolved"
}

The agent surfaces the payment_url to the buyer. Stripe's webhook to Kifly marks the order paid; the agent confirms via order_status.

buyer_token_status is "resolved" if a valid buyer_token was passed (email pre-filled in Stripe Checkout), "invalid" if the token was unrecognized (checkout proceeds without pre-fill), or "none" if no token was passed.

Why this is the default

• No buyer-side setup. No wallet, no Coinbase account.
• Works today on every kfa_live_ key — no Stripe allowlist.
• Universal: any agent that can return a URL to a human can use it.

Rail 2 — Coinbase Commerce (beta)

Same shape as Rail 1 but the buyer has a choice at the payment page: pay with USDC on Base (Coinbase Commerce) or pay with card (Stripe). The agent's request is identical to Rail 1; Kifly returns a chooser URL when the seller has Coinbase Commerce enabled.

{
  "session_id": "kpc_XXXXXXXXXX",
  "payment_url": "https://kifly.ai/pay/kpc_XXXXXXXXXX",
  "amount": 8550,
  "currency": "usd",
  "methods": ["usdc-on-base", "card-via-stripe"]
}

Beta: Seller-side Coinbase Commerce configuration (API key + webhook secret) is not yet self-serve in the seller dashboard. Sellers can opt in by emailing hello@kifly.ai.

Rail 3 — x402 USDC on Base (beta)

The x402 protocol extends HTTP 402 for on-chain payments. Agents whose buyer authorizes an on-chain payment submit a signed USDC proof; there is no stored-credential card path.

Reading the cart total returns a 402 challenge; for x402-enabled sellers it also carries an X-Payment-Required header advertising the USDC option:

POST /api/agent/cart/{cart_id}/checkout
Authorization: Bearer kfa_live_xxxxxxxxxxxxxxxx
Idempotency-Key: <uuid>

HTTP/1.1 402 Payment Required
WWW-Authenticate: Payment realm="kifly"
X-Payment-Required: {"network":"base","currency":"USDC","amount":"49.99","address":"0x…"}

Agents that support x402 re-request with a signed payment proof:

POST /api/agent/cart/{cart_id}/checkout
X-Payment: <signed-usdc-proof>

The proof is verified by the Coinbase x402 facilitator and broadcast to Base mainnet.

Beta: this rail's production settlement is not yet activated. The protocol is implemented and tested; until activation completes, fall back to Rail 1 — X-Payment on an inactive endpoint returns x402_not_configured.

Header detection

An Authorization: Payment <token> credential is not accepted for settlement — Kifly has no stored-card / reusable-token rail. Presenting one simply re-issues the 402 challenge.

Idempotency

All mutating agent endpoints require an Idempotency-Key header (UUID). Repeating a request with the same key returns the original response — safe to retry on network errors.

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Keys are scoped to your API token. Always reuse the same key when retrying the same logical operation.