From 4289a28651b1a6c8fb434464d9af3c6d18776caf Mon Sep 17 00:00:00 2001 From: AnnaXWang <6621137+AnnaXWang@users.noreply.github.com> Date: Thu, 10 Sep 2026 02:50:32 +0000 Subject: [PATCH 1/4] Clarify Vault payment security guidance --- browsers/enable-payments-in-browser-agent.mdx | 32 ++++++++++--------- integrations/payments/overview.mdx | 29 +++++++++-------- integrations/payments/stripe-link.mdx | 12 +++---- vaults.mdx | 31 ++++++++++++------ 4 files changed, 60 insertions(+), 44 deletions(-) diff --git a/browsers/enable-payments-in-browser-agent.mdx b/browsers/enable-payments-in-browser-agent.mdx index 62cab916..da3f6759 100644 --- a/browsers/enable-payments-in-browser-agent.mdx +++ b/browsers/enable-payments-in-browser-agent.mdx @@ -3,21 +3,23 @@ title: "Enable Payments in a Browser Agent" description: "Give a browser agent provider-backed payment aliases and complete a web checkout without exposing card data" --- -you're building a browser agent. you can add payments without bringing your application, agent, or browser into pci dss scope. +you're building a browser agent. you can add payments without exposing the card +number or cvc to your application, agent, or browser. this design may help limit +pci dss scope; confirm your exact scope with your compliance advisor or qsa. -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. +create a KERNEL vault and add a wallet backed by [link by stripe](/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 +link by stripe 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 +you can use either [link by stripe](/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 | +| | link by stripe | 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 | @@ -32,8 +34,8 @@ to run either path with a coding agent that has access to the 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 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. +- link by stripe 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. @@ -218,7 +220,7 @@ items by `spec.provider`, and apply this flow: | `connected` | hide the add option, show the provider as connected, and reuse the existing wallet | | any other state | hide the add option and show the existing state; recover it or use an explicit remove-and-replace flow | -if both stripe link and agentcard wallets exist, hide both provider add options. +if both link by stripe and agentcard wallets exist, hide both provider add options. recheck this condition in your trusted controller immediately before wallet creation so a stale ui cannot submit a second wallet. @@ -263,9 +265,9 @@ updating a card item: 4. stop when any value is missing, cannot be verified, or disagrees. do not create or update a card item and do not invoke authorization. 5. show the independently verified values to the end user and wait for explicit confirmation. 6. freeze that verified, confirmed purchase object. derive the card specification and any authorization request from that same object. do not accept replacement values from the agent after confirmation. -7. for stripe link, list the connected wallet's payment methods and let the end user select one. for agentcard, pin an enrolled card or let the end user choose during approval. -8. ask KERNEL to prepare a card item on the end user's behalf. stripe link requires a new one-use item. agentcard can reuse a ready item and update its specification when the api permits. the item refers to the connected wallet; it is not the end user's real card. -9. for stripe link, invoke the advertised `authorize` operation using the same verified purchase object, then present any returned approval action to the end user. agentcard begins authorization after the browser submits checkout. +7. for link by stripe, list the connected wallet's payment methods and let the end user select one. for agentcard, pin an enrolled card or let the end user choose during approval. +8. ask KERNEL to prepare a card item on the end user's behalf. link by stripe requires a new one-use item. agentcard can reuse a ready item and update its specification when the api permits. the item refers to the connected wallet; it is not the end user's real card. +9. for link by stripe, invoke the advertised `authorize` operation using the same verified purchase object, then present any returned approval action to the end user. agentcard begins authorization after the browser submits checkout. 10. wait for the card item to become `ready`, then pass only its aliases to the browser agent. @@ -470,7 +472,7 @@ the agent can fill both top-level fields and payment fields embedded in iframes. ## 5. Keep approval and observation outside the agent -start observing the card item before the agent submits checkout and keep the observer running until the merchant reaches a terminal order state. this is required for agentcard, where the outgoing checkout request is held while the user approves it. the same observer works for stripe link and provides item events after credential substitution. +start observing the card item before the agent submits checkout and keep the observer running until the merchant reaches a terminal order state. this is required for agentcard, where the outgoing checkout request is held while the user approves it. the same observer works for link by stripe and provides item events after credential substitution. the example uses `presentProviderAction`, an application-owned function. it must publish the action only to an authenticated session for the end user who @@ -630,7 +632,7 @@ use item state, item events, the checkout page, and the merchant's order record | `payment_succeeded` | verify that the merchant created the expected order | | `payment_requires_action` | continue the existing merchant flow without resubmitting payment | | `payment_processing` | wait for the existing payment and inspect the merchant's status | -| stripe link `consumed`, `credential_submitted`, or `credential_tokenized` | confirm processor and merchant state; credential use alone does not prove purchase success | +| link by stripe `consumed`, `credential_submitted`, or `credential_tokenized` | confirm processor and merchant state; credential use alone does not prove purchase success | | agentcard `ready` or authorization `approved` | inspect charge, replay, and merchant state; reusable item state does not prove purchase success | | decline, expiry, rejection, failure, abandonment, or `payment_unknown` | stop and reconcile the existing attempt before deciding whether a new purchase is appropriate | diff --git a/integrations/payments/overview.mdx b/integrations/payments/overview.mdx index 108f26c4..d28cd55b 100644 --- a/integrations/payments/overview.mdx +++ b/integrations/payments/overview.mdx @@ -3,7 +3,10 @@ title: "overview" description: "Add payments to a browser agent without exposing card data to your application, agent, or browser" --- -your browser agent can complete a web checkout without bringing your application, agent, or browser into pci dss scope. a provider-hosted flow collects and stores the user's payment method, so neither you nor your agent handles the card number or cvc. +your browser agent can complete a web checkout without exposing the card number +or cvc to your application, agent, or browser. this design reduces card-data +exposure and may help limit pci dss scope. your exact scope depends on your +integration and environment; confirm it with your compliance advisor or qsa. KERNEL connects that payment method to a [vault](/vaults), returns non-secret aliases, and resolves those aliases at @@ -12,7 +15,7 @@ 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 +link by stripe 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 @@ -32,7 +35,7 @@ both credential providers use the same integration shape: each vault must contain at most one wallet item for each provider. before showing a provider connection option, list the vault's items. if that provider already has a wallet in any state, hide the add option and reuse or recover the -existing item. when both stripe link and agentcard wallets exist, show both as +existing item. when both link by stripe and agentcard wallets exist, show both as configured and do not offer either provider again. ```mermaid @@ -52,11 +55,11 @@ the card number and cvc stay outside the agent-controlled environment. the brows - collect a stripe link wallet and approve a one-use credential for a specific + collect a link by stripe wallet and approve a one-use credential for a specific purchase. - stripe link and agentcard identify where the credential comes from and how the + link by stripe 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 | +| behavior | link by stripe | agentcard | | ------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------- | | payment-method collection | hosted `link_oauth` action | fully white-labeled `card_enrollment` page | | purchase authorization | explicit `authorize` operation before checkout | the user approves with Face ID | @@ -83,7 +86,7 @@ the card number and cvc stay outside the agent-controlled environment. the brows | reuse | card item and aliases are consumed on first substitution | cards can be reused for recurring and one-time purchases | | environment | live only | configured agentcard credential; not exposed through the vault api | -choose [stripe link](https://hypeship.dev/integrations/payments/stripe-link) when each purchase requires a newly approved, single-use credential. choose [agentcard](https://hypeship.dev/integrations/payments/agentcard) when one enrolled card must support multiple purchases, with separate approval for each. +choose [link by stripe](https://hypeship.dev/integrations/payments/stripe-link) when each purchase requires a newly approved, single-use credential. choose [agentcard](https://hypeship.dev/integrations/payments/agentcard) when one enrolled card must support multiple purchases, with separate approval for each. both integrations may provide additional benefits, including card rewards and chargeback protection. review each provider’s own documentation for the most up-to-date details. @@ -91,7 +94,7 @@ both integrations may provide additional benefits, including card rewards and ch KERNEL currently includes native adapters for these checkout request formats. all five adapters are enabled for -both stripe link and agentcard. +both link by stripe and agentcard. | merchant processor or platform | recognized HTTPS `POST` request formats | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -101,8 +104,8 @@ both stripe link and agentcard. | 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 +for example, a browser can enter link by stripe or agentcard aliases into a Shopify +checkout. Shopify remains the merchant platform; link by stripe or agentcard supplies the credential and approval flow. the outgoing request must contain the complete alias set and match the adapter's @@ -119,7 +122,7 @@ 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. +- integrate with one KERNEL vault api for both link by stripe 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. @@ -139,7 +142,7 @@ real processors and measuring reliability are active priorities. ## Next step -configure [stripe link](/integrations/payments/stripe-link) or [agentcard](/integrations/payments/agentcard), then follow [Enable Payments in a Browser Agent](/browsers/enable-payments-in-browser-agent) to attach the vault and give payment aliases to your agent. +configure [link by stripe](/integrations/payments/stripe-link) or [agentcard](/integrations/payments/agentcard), then follow [Enable Payments in a Browser Agent](/browsers/enable-payments-in-browser-agent) to attach the vault and give payment aliases to your agent. the provider pages show the CLI commands for creating wallets and cards. once the card item is ready, the shared CLI flow is: diff --git a/integrations/payments/stripe-link.mdx b/integrations/payments/stripe-link.mdx index 5b408af4..d48381c3 100644 --- a/integrations/payments/stripe-link.mdx +++ b/integrations/payments/stripe-link.mdx @@ -1,16 +1,16 @@ --- -title: "stripe link" -description: "Use stripe link to approve a one-use payment credential for a browser checkout" +title: "link by stripe" +description: "use link by stripe to approve a one-use payment credential for a browser checkout" --- -[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. +[link by stripe](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 with kms-backed envelope encryption, 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 +link by stripe 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. +example, you can use a link by stripe credential in a Shopify checkout. ## Before you start @@ -52,7 +52,7 @@ kernel vaults create --name user-12345 ## Connect a wallet -before showing a stripe link connection option, list the vault's items. if a +before showing a link by stripe connection option, list the vault's items. if a link wallet already exists in any state, reuse it and do not let the user add another. show its existing action or status instead. the api makes item keys unique but does not currently enforce one wallet per provider, so the ui must diff --git a/vaults.mdx b/vaults.mdx index 0e39de44..d6e131b1 100644 --- a/vaults.mdx +++ b/vaults.mdx @@ -24,7 +24,7 @@ resolved. vaults are in preview. the initial release supports `wallet` and `card` items - for [stripe link](/integrations/payments/stripe-link) and + for [link by stripe](/integrations/payments/stripe-link) and [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 @@ -35,11 +35,17 @@ resolved. ### Values do not come back through the api -sensitive values do not have a read path through the vault api. item responses -return non-sensitive specifications, state, masks, aliases, actions, and events, -but not the underlying value. for the initial payment integrations, a -provider-hosted flow collects the user's payment method and the provider-backed -card reaches the vault without passing through your application or agent. +sensitive payment values do not have a read path through the vault api. item +responses return specifications, state, masks, aliases, actions, and events, +but not the underlying value. these response fields are not general-purpose +secret storage. do not put card numbers, cvc, passwords, api keys, oauth codes, +or other secrets in item keys, specifications, metadata, merchant fields, +context, or events. + +for link by stripe, KERNEL stores oauth credentials and approved one-use card +data with kms-backed envelope encryption. for agentcard, the underlying card +remains with agentcard. both providers connect the user's payment method through +a hosted flow, without passing card data through your application or agent. ### Agents use aliases @@ -142,7 +148,12 @@ retrieve an item before acting on it. responses expose these fields and advertis | `expanded` | requested live data; not persisted on the item | | `expires_at`, `created_at`, `updated_at` | item timestamps when present | -when `action` is present, complete it in a trusted user-facing surface. invoke only operations listed in `available_operations`, and request only expansions listed in `available_expansions`. don't hard-code provider transitions from a previous response. +when `action` is present, complete it in a trusted user-facing surface. treat an +action url as a short-lived bearer link: bind it to the authenticated user, +vault, and item, and don't log it or put it in model context. invoke only +operations listed in `available_operations`, and request only expansions listed +in `available_expansions`. don't hard-code provider transitions from a previous +response. item reads accept `wait` values from 0–60 seconds. a read returns early when the item no longer has an unresolved authorization or approval transition. event reads support the same maximum wait and return an ordered array. use the last event `id` as the `after` cursor for newer events. @@ -157,7 +168,7 @@ connects an end user's payment method through a provider-hosted flow. a card ite 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 +link by stripe 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 @@ -165,13 +176,13 @@ 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 +link by stripe creates a one-use card for an approved purchase. agentcard keeps a reusable card item and requests approval for each checkout. wallet connection, authorization, provider handoff, and checkout observations are recorded as immutable events without card data. read the [payments overview](/integrations/payments/overview) for the shared -lifecycle or use the [stripe link](/integrations/payments/stripe-link) and +lifecycle or use the [link by stripe](/integrations/payments/stripe-link) and [agentcard](/integrations/payments/agentcard) provider guides. ## Initial item specifications From c3f2ce9c094be91d8af485bdb98edf3ab91b2ba9 Mon Sep 17 00:00:00 2001 From: Anna Wang Date: Wed, 9 Sep 2026 20:01:12 -0700 Subject: [PATCH 2/4] Apply suggestion from @AnnaXWang --- browsers/enable-payments-in-browser-agent.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/browsers/enable-payments-in-browser-agent.mdx b/browsers/enable-payments-in-browser-agent.mdx index da3f6759..8597018a 100644 --- a/browsers/enable-payments-in-browser-agent.mdx +++ b/browsers/enable-payments-in-browser-agent.mdx @@ -4,8 +4,7 @@ description: "Give a browser agent provider-backed payment aliases and complete --- you're building a browser agent. you can add payments without exposing the card -number or cvc to your application, agent, or browser. this design may help limit -pci dss scope; confirm your exact scope with your compliance advisor or qsa. +number or cvc to your application, agent, or browser. create a KERNEL vault and add a wallet backed by [link by stripe](/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. From 91e4be94637099e22ac7e4efcaca7cf9262fd139 Mon Sep 17 00:00:00 2001 From: Anna Wang Date: Wed, 9 Sep 2026 20:02:26 -0700 Subject: [PATCH 3/4] Apply suggestion from @AnnaXWang --- integrations/payments/overview.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/integrations/payments/overview.mdx b/integrations/payments/overview.mdx index d28cd55b..b4bd554b 100644 --- a/integrations/payments/overview.mdx +++ b/integrations/payments/overview.mdx @@ -5,8 +5,7 @@ description: "Add payments to a browser agent without exposing card data to your your browser agent can complete a web checkout without exposing the card number or cvc to your application, agent, or browser. this design reduces card-data -exposure and may help limit pci dss scope. your exact scope depends on your -integration and environment; confirm it with your compliance advisor or qsa. +exposure and avoids expanding pci dss scope. KERNEL connects that payment method to a [vault](/vaults), returns non-secret aliases, and resolves those aliases at From 3e3becdaeba14cbcb8fef793b995f11351ca44d1 Mon Sep 17 00:00:00 2001 From: Anna Wang Date: Wed, 9 Sep 2026 20:37:39 -0700 Subject: [PATCH 4/4] Apply batched suggestions from code review Co-authored-by: Anna Wang --- browsers/enable-payments-in-browser-agent.mdx | 20 +++++++++---------- integrations/payments/overview.mdx | 14 ++++++------- integrations/payments/stripe-link.mdx | 6 +++--- vaults.mdx | 11 ++++------ 4 files changed, 24 insertions(+), 27 deletions(-) diff --git a/browsers/enable-payments-in-browser-agent.mdx b/browsers/enable-payments-in-browser-agent.mdx index 8597018a..db1730ab 100644 --- a/browsers/enable-payments-in-browser-agent.mdx +++ b/browsers/enable-payments-in-browser-agent.mdx @@ -6,9 +6,9 @@ description: "Give a browser agent provider-backed payment aliases and complete you're building a browser agent. you can add payments without exposing the card number or cvc to your application, agent, or browser. -create a KERNEL vault and add a wallet backed by [link by stripe](/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. +create a KERNEL vault and add a wallet backed by [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. -link by stripe and agentcard are credential providers, not merchant payment +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 @@ -42,7 +42,7 @@ references a wallet item in the same vault, so create the wallet before the card. 1. create or retrieve a vault named `user-12345`. -2. list the vault's items and locate its only link by stripe wallet. require its +2. list the vault's items and locate its only link wallet. require its status to be `connected` and reuse it. if none exists, more than one exists, or an action is present, stop and ask me to resolve wallet setup outside this agent. do not create another wallet or print, return, or open an action url. @@ -140,7 +140,7 @@ 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 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. -- link by stripe card creation is live-only. agentcard mode comes from the integration's configured credential. +- 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. @@ -219,7 +219,7 @@ items by `spec.provider`, and apply this flow: | `connected` | hide the add option, show the provider as connected, and reuse the existing wallet | | any other state | hide the add option and show the existing state; recover it or use an explicit remove-and-replace flow | -if both link by stripe and agentcard wallets exist, hide both provider add options. +if both link and agentcard wallets exist, hide both provider add options. recheck this condition in your trusted controller immediately before wallet creation so a stale ui cannot submit a second wallet. @@ -264,9 +264,9 @@ updating a card item: 4. stop when any value is missing, cannot be verified, or disagrees. do not create or update a card item and do not invoke authorization. 5. show the independently verified values to the end user and wait for explicit confirmation. 6. freeze that verified, confirmed purchase object. derive the card specification and any authorization request from that same object. do not accept replacement values from the agent after confirmation. -7. for link by stripe, list the connected wallet's payment methods and let the end user select one. for agentcard, pin an enrolled card or let the end user choose during approval. -8. ask KERNEL to prepare a card item on the end user's behalf. link by stripe requires a new one-use item. agentcard can reuse a ready item and update its specification when the api permits. the item refers to the connected wallet; it is not the end user's real card. -9. for link by stripe, invoke the advertised `authorize` operation using the same verified purchase object, then present any returned approval action to the end user. agentcard begins authorization after the browser submits checkout. +7. for link stripe, list the connected wallet's payment methods and let the end user select one. for agentcard, pin an enrolled card or let the end user choose during approval. +8. ask KERNEL to prepare a card item on the end user's behalf. link requires a new one-use item. agentcard can reuse a ready item and update its specification when the api permits. the item refers to the connected wallet; it is not the end user's real card. +9. for link, invoke the advertised `authorize` operation using the same verified purchase object, then present any returned approval action to the end user. agentcard begins authorization after the browser submits checkout. 10. wait for the card item to become `ready`, then pass only its aliases to the browser agent. @@ -471,7 +471,7 @@ the agent can fill both top-level fields and payment fields embedded in iframes. ## 5. Keep approval and observation outside the agent -start observing the card item before the agent submits checkout and keep the observer running until the merchant reaches a terminal order state. this is required for agentcard, where the outgoing checkout request is held while the user approves it. the same observer works for link by stripe and provides item events after credential substitution. +start observing the card item before the agent submits checkout and keep the observer running until the merchant reaches a terminal order state. this is required for agentcard, where the outgoing checkout request is held while the user approves it. the same observer works for link and provides item events after credential substitution. the example uses `presentProviderAction`, an application-owned function. it must publish the action only to an authenticated session for the end user who @@ -631,7 +631,7 @@ use item state, item events, the checkout page, and the merchant's order record | `payment_succeeded` | verify that the merchant created the expected order | | `payment_requires_action` | continue the existing merchant flow without resubmitting payment | | `payment_processing` | wait for the existing payment and inspect the merchant's status | -| link by stripe `consumed`, `credential_submitted`, or `credential_tokenized` | confirm processor and merchant state; credential use alone does not prove purchase success | +| link `consumed`, `credential_submitted`, or `credential_tokenized` | confirm processor and merchant state; credential use alone does not prove purchase success | | agentcard `ready` or authorization `approved` | inspect charge, replay, and merchant state; reusable item state does not prove purchase success | | decline, expiry, rejection, failure, abandonment, or `payment_unknown` | stop and reconcile the existing attempt before deciding whether a new purchase is appropriate | diff --git a/integrations/payments/overview.mdx b/integrations/payments/overview.mdx index b4bd554b..40737c90 100644 --- a/integrations/payments/overview.mdx +++ b/integrations/payments/overview.mdx @@ -14,7 +14,7 @@ page creates its normal payment request. KERNEL handles authorization and payment handoff outside the browser. -link by stripe and agentcard are credential providers, not merchant payment +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 @@ -34,7 +34,7 @@ both credential providers use the same integration shape: each vault must contain at most one wallet item for each provider. before showing a provider connection option, list the vault's items. if that provider already has a wallet in any state, hide the add option and reuse or recover the -existing item. when both link by stripe and agentcard wallets exist, show both as +existing item. when both link and agentcard wallets exist, show both as configured and do not offer either provider again. ```mermaid @@ -58,7 +58,7 @@ the card number and cvc stay outside the agent-controlled environment. the brows href="/integrations/payments/stripe-link" icon="link" > - collect a link by stripe wallet and approve a one-use credential for a specific + collect a link wallet and approve a one-use credential for a specific purchase. - link by stripe and agentcard identify where the credential comes from and how the + 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. @@ -93,7 +93,7 @@ both integrations may provide additional benefits, including card rewards and ch KERNEL currently includes native adapters for these checkout request formats. all five adapters are enabled for -both link by stripe and agentcard. +both link and agentcard. | merchant processor or platform | recognized HTTPS `POST` request formats | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -103,8 +103,8 @@ both link by stripe and agentcard. | 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 link by stripe or agentcard aliases into a Shopify -checkout. Shopify remains the merchant platform; link by stripe or agentcard +for example, a browser can enter link or agentcard aliases into a Shopify +checkout. Shopify remains the merchant platform; link or agentcard supplies the credential and approval flow. the outgoing request must contain the complete alias set and match the adapter's diff --git a/integrations/payments/stripe-link.mdx b/integrations/payments/stripe-link.mdx index d48381c3..aada7212 100644 --- a/integrations/payments/stripe-link.mdx +++ b/integrations/payments/stripe-link.mdx @@ -5,12 +5,12 @@ description: "use link by stripe to approve a one-use payment credential for a b [link by stripe](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 with kms-backed envelope encryption, gives your agent non-secret aliases, substitutes the credential at browser egress, and then consumes the card item. -link by stripe is the credential provider, not the merchant's payment processor. at +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 link by stripe credential in a Shopify checkout. +example, you can use a link credential in a Shopify checkout. ## Before you start @@ -52,7 +52,7 @@ kernel vaults create --name user-12345 ## Connect a wallet -before showing a link by stripe connection option, list the vault's items. if a +before showing a link connection option, list the vault's items. if a link wallet already exists in any state, reuse it and do not let the user add another. show its existing action or status instead. the api makes item keys unique but does not currently enforce one wallet per provider, so the ui must diff --git a/vaults.mdx b/vaults.mdx index d6e131b1..9ca0c7c7 100644 --- a/vaults.mdx +++ b/vaults.mdx @@ -37,12 +37,9 @@ resolved. sensitive payment values do not have a read path through the vault api. item responses return specifications, state, masks, aliases, actions, and events, -but not the underlying value. these response fields are not general-purpose -secret storage. do not put card numbers, cvc, passwords, api keys, oauth codes, -or other secrets in item keys, specifications, metadata, merchant fields, -context, or events. +but not the underlying value. -for link by stripe, KERNEL stores oauth credentials and approved one-use card +for link, KERNEL stores oauth credentials and approved one-use card data with kms-backed envelope encryption. for agentcard, the underlying card remains with agentcard. both providers connect the user's payment method through a hosted flow, without passing card data through your application or agent. @@ -168,7 +165,7 @@ connects an end user's payment method through a provider-hosted flow. a card ite then publishes aliases that an attached browser can enter into a web checkout. authorization and payment handoff happen outside the browser vm. -link by stripe and agentcard are credential providers, not merchant payment +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 @@ -176,7 +173,7 @@ 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). -link by stripe creates a one-use card for an approved purchase. agentcard keeps a +link creates a one-use card for an approved purchase. agentcard keeps a reusable card item and requests approval for each checkout. wallet connection, authorization, provider handoff, and checkout observations are recorded as immutable events without card data.