Skip to content

Document the Shop Pay wallet #737

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bmsaadat wants to merge 1 commit into
base: main
Choose a base branch
from
+580 −7
Open

Document the Shop Pay wallet #737

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 17 additions & 1 deletion browsers/enable-payments-in-browser-agent.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ verify and approve each purchase before completing checkout.
## Before you start

- have an existing browser agent. this guide adds payment handling, not navigation or reasoning.
- choose a wallet integration from the [wallet overview](/integrations/wallets/overview), then follow its tab below.
- choose a wallet integration from the [wallet overview](/integrations/wallets/overview), then follow its tab below. for shop pay, follow the [shop pay guide](/integrations/wallets/shop-pay), which uses the same controller pattern.
- install a KERNEL sdk with the `vaults` resource. set `KERNEL_API_KEY` and `KERNEL_PROJECT_ID` in your controller.
- use a low-value checkout you control. link is live-only and requires an https merchant origin. on stripe checkouts that support link pay tokens, KERNEL fills the payment without field selectors; elsewhere you need verified field selectors for the virtual card. agentcard requires a [native processor adapter](/integrations/wallets/overview#checkout-and-processor-coverage); the processor doesn't need to be stripe.
- for agentcard, set `AGENTCARD_MODE` in your controller and verify it against the credential's mode. customer-owned configs expose `test_mode` (`true` means sandbox); for KERNEL-managed credentials, confirm the deployment's mode. stop if the mode is unknown or mismatched.
Expand Down Expand Up @@ -165,6 +165,13 @@ kernel browsers create --vault user-12345 -o json

</CodeGroup>

<Tip>
the examples create a headful browser. to run checkout headless, create the
browser with at least `2GiB` of memory (`memory: "2GiB"`, or `--memory 2GiB`
in the cli). heavy checkout pages can exhaust a `1GiB` headless browser, which
then stops responding to KERNEL during authorization and fill.
</Tip>

`browser_live_view_url` lets the user watch the checkout during confirmation
and agentcard approval pauses. `presentLiveView` represents your authenticated
user-facing page: keep the url server-side with the user and browser session
Expand Down Expand Up @@ -668,6 +675,15 @@ native dom `click()`. read that same input's `checked` property and require it t
be `true` before submission. if you can't verify the checked state, stop without
submitting.

</Accordion>
<Accordion title="Stripe's save with link option">

stripe checkouts can pre-check "save my information with link for faster
checkout". while it's checked, stripe also requires a phone number and won't
submit the payment without one. unless the user asked to save their details to link, uncheck it before submitting and read
the input's `checked` property to confirm. these are stripe page details rather
than a KERNEL contract.

</Accordion>
<Accordion title="Missing or unconnected wallets">

Expand Down
4 changes: 2 additions & 2 deletions browsers/payments.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,9 @@ agentcard uses an integration-specific alternative: the agent enters non-sensiti
1. create a vault for the user or task.
2. create a wallet item and send the user through the provider-hosted collection flow.
3. attach the vault when you create the browser session. the attachment also covers items created later in that vault.
4. create a card item for the verified, user-confirmed purchase. complete the provider's required preparation and approval. link authorizes at the checkout page and issues a merchant-bound link pay token on supported stripe checkouts or a single-use virtual card elsewhere; agentcard can reuse a card item with separate approval for each checkout.
4. create a card item for the verified, user-confirmed purchase. complete the provider's required preparation and approval. link authorizes at the checkout page and issues a merchant-bound link pay token on supported stripe checkouts or a single-use virtual card elsewhere; shop pay authorizes at the checkout page and issues a single-use card once the shopper approves in shop; agentcard can reuse a card item with separate approval for each checkout.
5. invoke KERNEL's advertised `fill` operation to inject payment fields without supplying their values, then inspect the outcomes before submitting. for agentcard's alias-based flow, enter aliases and keep a trusted approval observer running while the checkout request is held.
6. submit checkout once, complete any remaining provider-hosted approval, and reconcile with the merchant's order state. fill or approval alone is not payment success.
6. submit checkout once, complete any remaining provider-hosted approval, and reconcile with the merchant's order state. for shop pay, report the outcome with `confirm_transaction`. fill or approval alone is not payment success.

`wallet` and `card` are vault item types. the wallet supplies the provider connection; the card represents payment material and its authorization state. retrieve the item and check `available_operations` before invoking an operation. don't assume every item supports `fill`.

Expand Down
1 change: 1 addition & 0 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -216,6 +216,7 @@
"integrations/wallets/overview",
"integrations/wallets/kernel",
"integrations/wallets/stripe-link",
"integrations/wallets/shop-pay",
"integrations/wallets/agentcard",
"integrations/wallets/embedded-card-capture",
"integrations/wallets/embedded-card-cvc"
Expand Down
9 changes: 5 additions & 4 deletions integrations/wallets/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,13 +19,14 @@ see [how payments work on KERNEL](/browsers/payments#how-payments-work) for the
| --- | --- | --- |
| [KERNEL card](/integrations/wallets/kernel) | collect a user's card directly through hosted or embedded enrollment | live only |
| [link by stripe](/integrations/wallets/stripe-link) | use payment methods from the user's link wallet; requires a us phone number | live only |
| [shop pay](/integrations/wallets/shop-pay) | use cards saved to the user's shop account, approved in shop for each purchase; usd only | live only |
| [agentcard](/integrations/wallets/agentcard) | use agentcard's card vault and provider-executed checkout | sandbox or live, set by the agentcard credential |

approval, eligibility, and reuse depend on the integration and card. follow the provider guide before choosing a checkout flow.

## Checkout and processor coverage

KERNEL's `fill` api does not require a native processor adapter. for link virtual cards, the page must be on the authorized origin and provide supported checkout inputs. on stripe checkouts that expose link's agent payment tools, KERNEL delivers a link pay token instead, with no field selectors. see [link card requirements](/integrations/wallets/stripe-link#fill-the-checkout).
KERNEL's `fill` api does not require a native processor adapter. for link virtual cards, the page must be on the authorized origin and provide supported checkout inputs. on stripe checkouts that expose link's agent payment tools, KERNEL delivers a link pay token instead, with no field selectors. see [link card requirements](/integrations/wallets/stripe-link#fill-the-checkout). shop pay cards follow the same origin rule; see [shop pay fill](/integrations/wallets/shop-pay#fill-the-checkout).

agentcard's alias-based checkout requires a recognized processor request. see [agentcard's processor coverage](/integrations/wallets/agentcard#checkout-and-processor-coverage) for supported formats and limitations. neither field filling nor provider handoff guarantees processor acceptance or payment success.

Expand All @@ -37,7 +38,7 @@ see [why use KERNEL payments](/browsers/payments#why-use-kernel-payments) for sa

use KERNEL-managed credentials by default. if you need your own client, follow
the optional setup in [link](/integrations/wallets/stripe-link#bring-your-own-link-oauth-client)
or [agentcard](/integrations/wallets/agentcard#bring-your-own-agentcard-oauth-client). a named
or [agentcard](/integrations/wallets/agentcard#bring-your-own-agentcard-oauth-client). shop pay connects through KERNEL's shop app only and has no provider configuration. a named
provider configuration stores your application's `client_id` and `client_secret`,
not an end user's wallet grant. credentials are encrypted at rest; secrets are
never returned.
Expand Down Expand Up @@ -68,11 +69,11 @@ has a wallet in any state, and reuse or recover the existing item.
a card's `spec.wallet` must reference a wallet in the same vault and from the
same provider.

for provider-specific behavior, see [KERNEL card](/integrations/wallets/kernel), [link](/integrations/wallets/stripe-link#item-reference), or [agentcard](/integrations/wallets/agentcard#item-reference).
for provider-specific behavior, see [KERNEL card](/integrations/wallets/kernel), [link](/integrations/wallets/stripe-link#item-reference), [shop pay](/integrations/wallets/shop-pay#item-reference), or [agentcard](/integrations/wallets/agentcard#item-reference).

## Payment actions and recovery

`action.name` can be `link_oauth`, `spend_approval`, `push_approval`, `collect`, `mfa`, `embedded_ceremony`, or `card_enrollment`. actions that require a hosted interaction include a `url`. don't send action urls or provider authorization material to the agent.
`action.name` can be `link_oauth`, `shop_pay_oauth`, `spend_approval`, `push_approval`, `collect`, `mfa`, `embedded_ceremony`, or `card_enrollment`. actions that require a hosted interaction include a `url`. don't send action urls or provider authorization material to the agent.

`recovery_required` means a card's provider outcome is unresolved. it stops
item wait loops and blocks new authorization, checkout, and deletion of the
Expand Down
Loading
Loading