Payment Rails

Kifly supports four payment rails across two payer types — human buyers (browser-based) and autonomous agents (machine-to-machine).

Rails 2–4 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.

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 SPT, no wallet, no Coinbase account.
• Works today on every kfa_live_ key — no Stripe allowlist, no MPP access.
• 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 — Stripe MPP (beta)

Stripe's Machine Payments Protocol (MPP) enables fully autonomous agent purchases. The agent presents a Shared Payment Token (SPT) issued by Stripe under a cardholder's mandate — no human payment step.

Step 1 — Initiate checkout (challenge)

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

Response:

HTTP/1.1 402 Payment Required
WWW-Authenticate: Payment realm="kifly", token_types="spt"

{ "payment_required": true, "amount": 4999, "currency": "usd", "token_types": ["spt"] }

Step 2 — Settle with SPT

POST /api/agent/cart/{cart_id}/checkout
Authorization: Payment <spt_token>
Idempotency-Key: <same-uuid>

Success response:

{ "order_id": "order_01JXXXXXXXXX", "payment_intent_id": "pi_3XXXXXXXXXX", "amount": 4999, "currency": "usd" }

Beta: MPP depends on Stripe issuing SPTs to your agent platform. If your platform doesn't have SPT access yet, fall back to Rail 1.

Rail 4 — x402 USDC on Base (beta)

The x402 protocol extends HTTP 402 for on-chain payments. Agents pay USDC on Base in a single re-request — no challenge-response cycle.

The checkout endpoint returns an X-Payment-Required header alongside the MPP challenge:

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

Agents that support x402 submit a signed payment proof:

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

One round-trip, no human step. 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 (Rails 3 & 4)

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.