checkout
ActiveTool of Kifly — Agentic Commerce & Payments
Requires `checkout:write` scope. **Requires `set_shipping_address` to have been called first.** Returns 400 `invalid_shipping` if no address is on the cart, or 400 `delivery_unavailable` if the buyer's address is outside the seller's coverage. Cart total must not exceed the platform cap (`kifly://platform/limits`). On success: `payment_rail` tells you which outcome you got. `'stripe-checkout'`/`'stripe-mpp'` — a real Kifly purchase: returns `payment_url` (Stripe link), `session_id` for `order_status`, and amount breakdown. `'directory-handoff'` — this seller is discovery-only (`kifly_purchasable: false` on the cart, as already signaled by create_cart/add_to_cart/get_cart); there is NO `payment_url`/`session_id`. Instead a `handoff` object carries `seller` (name, handle, storefront_url) and `items` (each with a tracked `link` to the product on the seller's own site, or null — fall back to `seller.storefront_url`), plus a `disclaimer` to relay verbatim. Present this as a referral to complete the purchase off-platform, not as a completed Kifly order. **To pre-fill the buyer's email on the payment page, pass `email` — ask the buyer for it in plain language ('what email should the receipt go to?'). Never ask the buyer to paste a token.** `buyer_token_status` in the response reports whether an (internal) token was applied: `'resolved'` / `'invalid'` / `'none'` — an invalid token is NOT an error response. On 502/503 errors, check `retryable: true` in the body — those are transient upstream faults; wait `retry_after_seconds` then retry once.
Parameters schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"cart_id"
],
"properties": {
"email": {
"type": "string",
"format": "email",
"description": "Buyer's email, collected conversationally. Pre-fills the Stripe Checkout email field so the buyer doesn't retype it. This is ALL you need to pre-fill email — ask the buyer for their email, never for a token."
},
"cart_id": {
"type": "string",
"description": "Cart ID from create_cart"
},
"buyer_token": {
"type": "string",
"description": "INTERNAL token (kfb_live_...) minted by register_buyer / verify_buyer — resolves the buyer's saved profile and pre-fills their email on the payment link. NEVER ask the buyer to paste this. Omit it unless you already obtained one programmatically this session; to pre-fill email, use `email` instead."
}
},
"additionalProperties": false
}Parent server
Kifly — Agentic Commerce & Payments
1/7 registries