Payment Rails

Kifly supports two machine-to-machine payment protocols. Both are handled by the same checkout endpoint — the server detects which rail the agent is using from the request headers.

Rail 1 — Stripe MPP (live)

Stripe's Machine Payments Protocol (MPP) uses a standard HTTP 402 challenge-response flow. The agent presents a Shared Payment Token (SPT) — a short-lived credential issued by Stripe under a cardholder's mandate — and Kifly settles directly against it.

How it works

Step 1 — Initiate checkout (challenge)

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

The server responds with a payment challenge:

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

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

Step 2 — Present the SPT (settlement)

The agent obtains an SPT from Stripe using the cardholder's mandate, then re-submits:

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

On success:

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

MCP path

If you are using the MCP integration, the checkout tool handles this for you — it reads the 402 challenge for totals and creates a Stripe Payment Link for the buyer to complete. No SPT required from your agent.

Rail 2 — x402 / USDC on Base (v2, coming)

The x402 protocol extends HTTP 402 for on-chain payments. Agents pay USDC on Base and re-request automatically — no human payment step.

When x402 launches, the checkout endpoint will respond with an additional 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 send payment proof in a single re-request:

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

One round-trip, no challenge-response cycle.

Header detection

The checkout endpoint uses these headers to select the payment rail:

Idempotency

All mutating agent endpoints require an Idempotency-Key header. Use a UUID per logical operation. 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. Collisions across different tokens are impossible.