diff --git a/browsers/enable-payments-in-browser-agent.mdx b/browsers/enable-payments-in-browser-agent.mdx index dd073c2..62cab91 100644 --- a/browsers/enable-payments-in-browser-agent.mdx +++ b/browsers/enable-payments-in-browser-agent.mdx @@ -7,18 +7,22 @@ you're building a browser agent. you can add payments without bringing your appl create a KERNEL vault and add a wallet backed by [stripe link](/integrations/payments/stripe-link) or [agentcard](/integrations/payments/agentcard). the provider-hosted flow collects and stores the user's payment method, so neither you nor your agent handles the card number or cvc. attach the vault when you create a browser session, give the agent the returned aliases, and let it complete a web checkout. KERNEL handles authorization and payment handoff at egress. +stripe link and agentcard are credential providers, not merchant payment +processors. at the browser form layer, both work with any web checkout that +accepts standard card details, and the merchant's processor does not need to be +stripe. end-to-end handoff also requires the outgoing request to match one of the +[native processor adapters](/integrations/payments/overview#checkout-and-processor-coverage). + you can use either [stripe link](/integrations/payments/stripe-link) or [agentcard](/integrations/payments/agentcard). choose based on how the payment credential is created and when the user approves it: -| | stripe link | agentcard | -| -------------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | -| card source | provider-minted, one-use card for a specific purchase | user's enrolled card, represented by a reusable card item | -| approval timing | before the browser submits checkout | after the browser submits checkout and while the request is held | -| reuse | card item and aliases are consumed after the first supported substitution | card item and aliases return to `ready`; every checkout requires approval | -| mode | live only | deployment credential; the vault api does not expose sandbox or live mode | -| checkout fit | likely the better starting point for stripe-powered checkout pages | may fit general card-entry pages better because it is backed by the user's enrolled card | -| current preview constraint | limited to the [supported stripe request formats](/integrations/payments/overview#supported-checkouts) | limited to the same [supported stripe request formats](/integrations/payments/overview#supported-checkouts), not arbitrary payment processors | +| | stripe link | agentcard | +| --------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------- | +| card source | provider-minted, one-use card for a specific purchase | user's enrolled card, represented by a reusable card item | +| approval timing | before the browser submits checkout | after the browser submits checkout and while the request is held | +| reuse | card item and aliases are consumed after the first native handoff | card item and aliases return to `ready`; every checkout requires approval | +| mode | live only | deployment credential; the vault api doesn't expose sandbox or live mode | agentcard is backed by a card the user enrolls, but the agent and browser still enter aliases rather than the underlying card details. those details remain @@ -70,7 +74,7 @@ card. values for required email, billing, postal, shipping, or other customer fields; stop if a required value is missing. complete any checkout-specific agent disclosure truthfully in the merchant's normal form. submit checkout - once. + once and never retry submission. 10. inspect the checkout result and the card item's events. do not retry a failed, timed-out, or indeterminate payment. report the existing attempt so we can reconcile it first. @@ -109,7 +113,7 @@ card. an enrolled card during approval. 8. retrieve the card item and confirm its status is `ready`. do not invoke `authorize`; agentcard starts authorization only when the attached browser - submits a supported checkout request. + submits a recognized processor request containing the aliases. 9. give me the exact cli observation commands, but do not run them. ask me to start the trusted approval observer outside this agent. after i confirm it is running, use only the returned aliases with @@ -117,9 +121,9 @@ card. fields. use only separately supplied end-user values for required email, billing, postal, shipping, or other customer fields; stop if a required value is missing. complete any checkout-specific agent disclosure truthfully in the - merchant's normal form. submit checkout once and keep that execution open - while KERNEL holds the payment request. do not poll or print the card item - while approval is pending. + merchant's normal form. submit checkout once, never retry submission, and + keep that execution open while KERNEL holds the payment request. do not poll + or print the card item while approval is pending. 10. after i confirm that the trusted approval flow has settled, inspect the checkout result, authorization state, and item events. do not retry a failed, timed-out, or indeterminate payment. report the existing attempt so we can @@ -134,8 +138,8 @@ this guide starts after you have an existing browser agent. it changes how you p - install a KERNEL sdk version that includes the `vaults` resource. - set `KERNEL_API_KEY` and `KERNEL_PROJECT_ID` in the trusted controller that creates your browser. -- use a supported stripe checkout you control. the initial release supports the request formats listed in the [payments overview](/integrations/payments/overview#supported-checkouts). -- use a low-value checkout you control while validating the flow. stripe link card creation is live-only. agentcard mode comes from the integration's configured credential. +- use a low-value web checkout you control whose outgoing payment request matches a [native processor adapter](/integrations/payments/overview#checkout-and-processor-coverage). the merchant processor doesn't need to be stripe. +- stripe link card creation is live-only. agentcard mode comes from the integration's configured credential. - for agentcard, keep an application-owned `AGENTCARD_MODE` deployment setting and fail closed unless it explicitly matches the sandbox or live environment you intend to use. the vault api does not return this mode. @@ -192,13 +196,14 @@ the end user creates the purchase intent. your application translates that confirmed intent into a KERNEL card item without exposing its api key to the user or agent. -| actor | responsibility | -| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| your application | enforces one wallet per provider; independently verifies purchase values; calls KERNEL; presents provider actions; observes state; attaches the vault | -| your end user | initiates wallet setup and purchases; adds or selects the real payment method; confirms the verified purchase; completes approval | -| your browser agent | proposes purchase values; after verification and confirmation, receives aliases, enters them into the checkout form, and submits once | -| KERNEL | creates the requested vault resources, returns aliases, enforces browser bindings, and handles payment data at egress | -| the payment provider | hosts connection, enrollment, and approval; stores the underlying payment method; authorizes the purchase | +| actor | responsibility | +| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| your application | enforces one wallet per provider; independently verifies purchase values; calls KERNEL; presents provider actions; observes state; attaches the vault | +| your end user | initiates wallet setup and purchases; adds or selects the real payment method; confirms the verified purchase; completes approval | +| your browser agent | proposes purchase values; after verification and confirmation, receives aliases, enters them into the checkout form, and submits once | +| KERNEL | creates the requested vault resources, returns aliases, enforces browser bindings, and handles payment data at egress | +| the credential provider | hosts wallet connection, enrollment, and approval; stores or mints the underlying payment credential | +| the merchant's processor | receives the recognized checkout request and returns its tokenization or payment response | ### Once per end user and provider @@ -270,6 +275,11 @@ updating a card item: card specification, approval display, and authorization. +purchase verification doesn't depend on the merchant processor. prefer the +merchant's trusted order or cart backend. if one isn't available, use documented +structured checkout data or deterministic extraction for that checkout, and +fail closed when the values can't be independently verified. + for a stripe payment link without an order or cart backend, use the payment-link response as the deterministic source. the current response exposes `account_settings.display_name`, `line_item_group.total`, @@ -300,16 +310,16 @@ browser session. the vault attachment covers items created later in that vault. - we're onboarding more native payment providers and will update this guide as - new integrations become available. we plan to build additional card-collection - and vault-management surfaces so developers can connect the payment providers - and third-party vaults they already use. over time, we want{" "} + we're adding credential-provider integrations and merchant-processor adapters + and will update this guide as coverage expands. we plan to build additional + card-collection and vault-management surfaces so developers can connect the + credential providers and third-party vaults they already use. over time, we want{" "} KERNEL to support more of the browser-side steps required to complete a payment without exposing the underlying credential to the agent or browser. -both provider flows leave you with a card item whose `state.status` is `ready` and whose `state.aliases` contains `number`, `cvc`, `exp_month`, and `exp_year`. +both credential-provider flows leave you with a card item whose `state.status` is `ready` and whose `state.aliases` contains `number`, `cvc`, `exp_month`, and `exp_year`. ### Collect non-card checkout fields @@ -324,8 +334,14 @@ merchant-specific agent disclosures are normal checkout fields. if the page asks whether automation is acting for another person, instruct the agent to answer truthfully in the merchant's form before submission. for a checkout that offers **I am an AI agent acting on behalf of someone else**, select that option. -don't bypass the disclosure or replace the page's normal submission with a raw -processor request. +stripe can render hidden or duplicate copies of its disclosure control for +responsive layouts. target the visible label. if the label doesn't toggle the +control, locate the associated real `input[type="checkbox"]` and invoke its +native dom `click()`. read that same input's `checked` property and require it to +be `true` before submission. if you can't verify the checked state, stop without +submitting. don't bypass the disclosure or replace the page's normal submission +with a raw processor request. after triggering submission once, never retry it, +including after a timeout, unchanged page, or indeterminate result. retrieve the item immediately before creating the browser. don't cache aliases after an item expires, changes state, or is deleted. @@ -443,8 +459,9 @@ If the checkout asks whether an agent is acting for another person, select the truthful disclosure option in the page before submission. For example: - I am an AI agent acting on behalf of someone else -Submit the checkout once. If the payment request pauses for user approval, -wait for the controller to finish that approval. Do not retry payment. +Submit the checkout once and never retry submission. If the payment request +pauses for user approval, wait for the controller to finish that approval. Do +not retry payment. ``` replace the angle-bracketed fields in your controller before sending the task. don't put oauth codes, action urls, provider responses, the vault api key, or the browser connection url in the prompt. diff --git a/integrations/payments/agentcard.mdx b/integrations/payments/agentcard.mdx index fcb9b8b..5e1b3cf 100644 --- a/integrations/payments/agentcard.mdx +++ b/integrations/payments/agentcard.mdx @@ -5,6 +5,19 @@ description: "Use Agentcard to approve browser checkouts against an enrolled pay [agentcard](https://www.agentcard.sh/) collects a user's card in a hosted enrollment flow and authorizes each browser checkout against that enrolled payment method. the card number and cvc stay with agentcard. your agent receives non-secret aliases. +agentcard is the credential provider, not the merchant's payment processor. at +the browser form layer, it works with any web checkout that accepts standard +card details, and the merchant's processor doesn't need to be stripe. end-to-end +handoff also requires the outgoing request to match a [native processor +adapter](/integrations/payments/overview#checkout-and-processor-coverage). +KERNEL currently has adapters for +request formats used by stripe, shopify, square, recurly, and razorpay. + +KERNEL's native handoff aims to +support the same processors supported by agentcard's direct SDK. email +[support@kernel.sh](mailto:support@kernel.sh) if you need another processor so +we can prioritize its adapter and validate a real checkout. + ## Before you start create a project-scoped client and vault. the examples below use these `kernel` and `vault` variables. @@ -57,7 +70,7 @@ credential. 2. wait for the wallet to become `connected`. 3. create a reusable `card` item with the merchant, amount, and currency. 4. attach the vault to a browser and give `state.aliases` to the agent. -5. when the browser submits a supported checkout, KERNEL holds the request and starts agentcard authorization. +5. when the browser submits a recognized processor request containing the aliases, KERNEL holds the request and starts agentcard authorization. 6. show the returned approval action to the user while the checkout remains in progress. 7. agentcard executes the approved request, and KERNEL replays the processor response to the browser. @@ -315,11 +328,11 @@ use this sequence for an agentcard checkout: 1. require exactly one agentcard wallet in the vault and wait for it to become `connected`. 2. create a headful browser with the vault attached, surface `browser_live_view_url` through your trusted application, and navigate to the checkout. keep this same browser for verification and submission so location-dependent pricing cannot change between the confirmed purchase and the outgoing request. -3. independently verify the merchant, items, active presentment amount, and active presentment currency. for a stripe payment link, prefer `account_settings.display_name`, `line_item_group.total`, `line_item_group.currency`, and `line_item_group.line_items` from the structured payment-link response when you don't have an order backend. use dom text and test ids only as supplemental checks because stripe can duplicate or omit them across layouts. +3. independently verify the merchant, items, active presentment amount, and active presentment currency from the merchant's trusted order or cart backend. if one isn't available, use documented structured checkout data or deterministic extraction for that checkout. for a stripe payment link specifically, prefer `account_settings.display_name`, `line_item_group.total`, `line_item_group.currency`, and `line_item_group.line_items` from the structured payment-link response. use dom text and test ids only as supplemental checks because stripe can duplicate or omit them across layouts. 4. collect merchant-required fields such as email, billing name, and postal code from the end user. identify checkout-specific agent disclosures and instruct the agent to answer them truthfully in the normal form. 5. show the verified purchase to the end user. after confirmation, create or update the card item from that same frozen object and require it to be `ready`. the vault attachment covers items created later in the same vault. 6. start the card and event observer before checkout submission. keep it running concurrently while the browser request is held. -7. give the browser agent the aliases, separately collected customer fields, and any required disclosure answer. submit the merchant form once. +7. give the browser agent the aliases, separately collected customer fields, and any required disclosure answer. submit the merchant form once and never retry submission. 8. publish the approval action through the authenticated, expiring application flow. never send it to the checkout browser or agent. 9. after the authorization settles, reconcile authorization state, item events, the checkout page, and the merchant order record. don't prepare the next purchase until this attempt is terminal or explicitly classified as indeterminate. @@ -471,7 +484,9 @@ event id, classify the attempt as indeterminate, and don't resubmit checkout. ## Handle checkout approval -agentcard does not advertise the `authorize` operation. authorization begins only after an attached browser submits a supported checkout request containing the aliases. +agentcard doesn't advertise the `authorize` operation. authorization begins +only after an attached browser submits a recognized processor request containing +the aliases. while the request is held, retrieve the card and send `action.url` through the same authenticated, expiring user-action flow used for enrollment. stop serving @@ -498,7 +513,10 @@ terminal and never pass its output to an agent. | `replay_attempted` | whether KERNEL attempted to replay the processor response | | `replay_delivered` | whether that response reached the browser; this does not confirm a merchant order | -declines, expirations, and provider failures can return a stripe-shaped error to the browser. the reusable item can still return to `ready`, so item status alone does not prove that the purchase succeeded or failed. +declines, expirations, and provider failures can return a processor-shaped +failure response to the browser. the exact response depends on the native +adapter. the reusable item can still return to `ready`, so item status alone +doesn't prove that the purchase succeeded or failed. your reconciliation policy must return `succeeded` only when the merchant order record confirms a paid order whose merchant, items, amount, and currency match diff --git a/integrations/payments/overview.mdx b/integrations/payments/overview.mdx index 4fda21e..ebd340a 100644 --- a/integrations/payments/overview.mdx +++ b/integrations/payments/overview.mdx @@ -12,9 +12,15 @@ page creates its normal payment request. KERNEL handles authorization and payment handoff outside the browser. +stripe link and agentcard are credential providers, not merchant payment +processors. at the browser form layer, both work with any web checkout that +accepts standard card details, and the merchant's processor does not need to be +stripe. end-to-end handoff also requires the outgoing payment request to match a +native KERNEL processor adapter. + ## How payments work -both supported providers use the same integration shape: +both credential providers use the same integration shape: 1. create a vault for the user or task. 2. create a wallet item and send the user through the provider-hosted collection flow. @@ -31,12 +37,12 @@ configured and do not offer either provider again. ```mermaid flowchart LR - U[user] --> H[provider-hosted collection] + U[user] --> H[credential-provider collection] H --> W[wallet item] W --> C[card item and aliases] C --> A[agent fills checkout] A --> E[KERNEL egress] - E --> P[payment provider] + E --> P[merchant processor] P --> M[merchant response] ``` @@ -64,9 +70,9 @@ the card number and cvc stay outside the agent-controlled environment. the brows - KERNEL is actively adding native - integrations with more payment providers. email - [support@kernel.sh](mailto:support@kernel.sh) to request one. + stripe link and agentcard identify where the credential comes from and how the + user approves it. choose between them based on that lifecycle, not the + merchant processor. processor-adapter coverage is the same for both. | behavior | stripe link | agentcard | @@ -79,16 +85,47 @@ the card number and cvc stay outside the agent-controlled environment. the brows choose [stripe link](/integrations/payments/stripe-link) when each purchase needs a newly approved, one-use credential. choose [agentcard](/integrations/payments/agentcard) when the same enrolled card must support multiple separately approved purchases. -## Supported checkouts - -the initial release recognizes form-encoded card requests sent to `api.stripe.com` on these paths: - -- `/v1/payment_methods` -- `/v1/tokens` -- `/v1/payment_intents/{id}/confirm` -- `/v1/payment_pages/{id}/confirm` - -the request must contain the complete alias set. arbitrary processors, custom request formats, and every possible stripe integration are not supported in the initial release. +## Checkout and processor coverage + +KERNEL currently includes native +adapters for these checkout request formats. all five adapters are enabled for +both stripe link and agentcard. + +| merchant processor or platform | recognized HTTPS `POST` request formats | +| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| stripe | form requests to `api.stripe.com/v1/payment_methods`, `/v1/tokens`, `/v1/payment_intents/{id}/confirm`, and `/v1/payment_pages/{id}/confirm` | +| shopify | JSON card-session requests to `checkout.pci.shopifyinc.com/sessions` and `deposit..shopifycs.com/sessions` | +| square | JSON card-nonce requests to `pci-connect.squareup.com/v2/card-nonce` and `pci-connect.squareupsandbox.com/v2/card-nonce` | +| recurly | form token requests to `api.recurly.com/js/v1/token` and `api.eu.recurly.com/js/v1/token` | +| razorpay | form card-payment requests to `api.razorpay.com/v1/payments/create/ajax` and `api.razorpay.com/v1/standard_checkout/payments/create/ajax` | + +for example, a browser can enter stripe link or agentcard aliases into a Shopify +checkout. Shopify remains the merchant platform; stripe link or agentcard +supplies the credential and approval flow. + +the outgoing request must contain the complete alias set and match the adapter's +expected HTTPS method, host, path, content type, and card-field layout. these +adapters are enabled today, but non-Stripe coverage still needs broader +validation against real processor SDKs and hosted checkouts. encrypted payloads, +different request layouts, and unrecognized processor endpoints pass through +without native handoff. + +KERNEL's native handoff aims to +support the same processors supported by agentcard's direct SDK. email +[support@kernel.sh](mailto:support@kernel.sh) if you need another processor so +we can prioritize its adapter and validate a real checkout. + +## Why use KERNEL handoff + +- integrate with one KERNEL vault api for both stripe link and agentcard. +- let KERNEL intercept recognized payment requests at egress, including requests from embedded payment frames, instead of maintaining cdp interception or page-routing logic in your agent. +- verify the project, browser session, vault attachment, item, aliases, and lifecycle state before handoff, then record the payment lifecycle in vault audit events. +- keep the underlying credential outside your application, agent, and browser through aliases and provider-hosted enrollment and approval. + +the handoff is designed to prevent credential injection and browser-to-provider +handoff failures. we don't yet have comparative data showing higher checkout +completion or payment acceptance rates. expanding acceptance coverage against +real processors and measuring reliability are active priorities. don't retry a failed, timed-out, rejected, or indeterminate payment. a browser diff --git a/integrations/payments/stripe-link.mdx b/integrations/payments/stripe-link.mdx index c5c8905..5b408af 100644 --- a/integrations/payments/stripe-link.mdx +++ b/integrations/payments/stripe-link.mdx @@ -5,6 +5,13 @@ description: "Use stripe link to approve a one-use payment credential for a brow [stripe link](https://stripe.com/payments/link) connects a user's wallet through oauth and issues a one-use payment credential for an approved purchase. KERNEL stores that credential encrypted, gives your agent non-secret aliases, substitutes the credential at browser egress, and then consumes the card item. +stripe link is the credential provider, not the merchant's payment processor. at +the browser form layer, it works with any web checkout that accepts standard +card details, and the merchant's processor doesn't need to be stripe. end-to-end +handoff also requires the outgoing request to match a [native processor +adapter](/integrations/payments/overview#checkout-and-processor-coverage). for +example, you can use a stripe link credential in a Shopify checkout. + ## Before you start create a project-scoped client and vault. the examples below use these `kernel` and `vault` variables. @@ -41,7 +48,7 @@ kernel vaults create --name user-12345 4. create a `card` item with the purchase details. 5. retrieve the card, verify that it advertises `authorize`, and perform that operation after explicit user approval. 6. complete the returned `spend_approval` or `push_approval` action and wait for `state.status` to become `ready`. -7. use `state.aliases` in an attached browser. the first supported substitution changes the item to `consumed`. +7. use `state.aliases` in an attached browser. the first native handoff changes the item to `consumed`. ## Connect a wallet @@ -329,6 +336,9 @@ kernel vaults items get user-12345 notebook-order --wait 60 -o json after the user completes the approval action, retrieve the card with `wait: 60` until it becomes `ready`. pass `state.aliases` to the [browser agent payments guide](/browsers/enable-payments-in-browser-agent). -the first supported checkout request that contains the aliases consumes the item and clears its encrypted card value. `consumed` means the credential was substituted, not that the processor accepted the payment or the merchant created an order. +the first recognized processor request that contains the aliases consumes the +item and clears its encrypted card value. `consumed` means the credential was +substituted, not that the processor accepted the payment or the merchant created +an order. don't repeat `authorize` or create a replacement item to retry an unknown purchase. inspect item events and the merchant's order state first. diff --git a/vaults.mdx b/vaults.mdx index 7eca52c..0e39de4 100644 --- a/vaults.mdx +++ b/vaults.mdx @@ -25,9 +25,10 @@ resolved. vaults are in preview. the initial release supports `wallet` and `card` items for [stripe link](/integrations/payments/stripe-link) and - [agentcard](/integrations/payments/agentcard). the vault model is not limited - to payments, but no other item types or providers are supported in this - release. + [agentcard](/integrations/payments/agentcard). here, provider means the + credential provider connected to the vault, not the merchant's payment + processor. the vault model isn't limited to payments, but no other item types + or credential providers are supported in this release. ## How vaults work @@ -153,8 +154,16 @@ see the [vaults api reference](https://kernel.sh/docs/api-reference/vaults/creat the initial release applies the vault primitive to browser checkout. a wallet connects an end user's payment method through a provider-hosted flow. a card item -then publishes aliases that an attached browser can enter into a supported -checkout. authorization and payment handoff happen outside the browser vm. +then publishes aliases that an attached browser can enter into a web checkout. +authorization and payment handoff happen outside the browser vm. + +stripe link and agentcard are credential providers, not merchant payment +processors. at the browser form layer, both work with any web checkout that +accepts standard card details, and the merchant's processor doesn't need to be +stripe. end-to-end handoff requires the outgoing request to match a native +processor adapter. the current adapters cover request formats used by stripe, +shopify, square, recurly, and razorpay; see [checkout and processor +coverage](/integrations/payments/overview#checkout-and-processor-coverage). stripe link creates a one-use card for an approved purchase. agentcard keeps a reusable card item and requests approval for each checkout. wallet connection,