# Express checkout

Apple Pay, Google Pay, PayPal and Amazon Pay buttons right in the bag.

An express button skips the checkout form. The wallet supplies the address and
contact, OrbCart quotes each step, and the buyer pays in the sheet.

The Channel's [`billingAddress: "required"`](/docs/shop/configuration#billingaddress)
also applies here. A full delivery address bills by default; an explicit billing
address must be complete on its own. A wallet's partial address may price a
delivery sheet, but cannot create a payment or order. If authorization or review
still lacks billing details, the runtime returns `cart_incomplete` with the
`bill_to` requirements and the current Cart. `<Checkout>` returns to its editable
details; a standalone button must offer the regular checkout as the way to
complete them. An incomplete provider review keeps the approved contact and
delivery details but drops its approval: completing billing requires fresh consent.

<Callout>
`<Checkout>` shows express buttons automatically for every method that supports them. This page
is for buttons elsewhere, such as in the bag or on a product page.
</Callout>

## Two kinds of express

| Mode     | Methods               | How it works                                                                  |
| -------- | --------------------- | ----------------------------------------------------------------------------- |
| `sheet`  | Apple Pay, Google Pay | The buyer picks address and card in the wallet sheet and pays there.          |
| `review` | PayPal, Amazon Pay    | The buyer chooses details at the provider, then confirms on your review page. |

`cart.paymentMethods` tells you which methods offer express: their `express`
field is `"sheet"` or `"review"`. `expressOnly: true` methods, such as Amazon Pay
by default, belong only in express buttons and their prepared review, not the
normal payment choices. A Channel's `offer` moves a method among the payment
methods, or shows it in both places.

## In React

`ExpressCheckout` shows the provider's own button for every express method of
the Cart, follows the purchase and says what went wrong in the buyer's language:

```tsx title="BagExpress.tsx"
import { useNavigate } from "react-router";
import type { Cart, CommerceCart } from "@orbcart/client";
import { ExpressCheckout } from "@orbcart/react";

export function BagExpress({ cart, current }: { cart: CommerceCart; current: Cart }) {
  const navigate = useNavigate();

  return (
    <ExpressCheckout
      cart={cart}
      initial={current}
      locale="en-GB"
      returnTo="/en/checkout"
      onReviewed={({ preparation }) => navigate(`/en/checkout?preparation=${preparation}`)}
      onOrdered={(order) => navigate(`/orders/${order.token}`)}
    />
  );
}
```

- **`onOrdered`** gets each Order once. Show your confirmation page.
- **`onReviewed`** takes PayPal's approval to your checkout page. The checkout
  there finds `?preparation=` in the address and shows the review by itself:
  the address and email PayPal gave, the shipping, the total and one order
  button. **Change** leads back to the form, where the next order click asks
  PayPal again. Without `onReviewed`, only the wallets that pay in their sheet
  are offered.
- **`returnTo`** is that page. A buyer PayPal redirects instead of using its
  popup comes back there, in the language they shopped in.
- **`pending`** keeps the buttons waiting while a change of the bag is on its
  way, so a sheet never shows the old total.
- **`paymentOptions={{ appearance: "inherit" }}`** dresses the buttons in your
  theme as they appear, as on the [checkout](/docs/shop/react-checkout#theme-it).

Amazon Pay uses the same `reviewed`/`onReviewed` contract, so supply it even though
Amazon normally redirects to `returnTo` instead of calling it in-page. Keep that
checkout page and the Cart token across redirects. The client uses Amazon's
official signed button, not a server-created session passed to `renderButton`.
The reviewed address stays read-only; hosted **Change** controls reopen Amazon.

For markup of your own, `useExpressCheckout` gives you the methods and a mount
function, and `ExpressButton` renders one provider's button.

## Without React

```ts
const button = await cart.mountExpress("apple_pay", element, {
  accepted: (result) => {
    if (result.status === "ordered") showConfirmation(result.order.number);
  },
  reviewed: (review) => goToReviewPage(review.preparation),
  failed: (error) => console.error(error),
});

if (!button.available) hideWalletSection();
```

`accepted` receives the same outcomes as [`quote.pay()`](/docs/shop/quotes#4-place-the-order).

A checkout of your own built on `cart.checkout()` shows PayPal's review while
`state.prepared` holds the approval: the details from `state.quote`, and an
order button that calls `placeOrder({ payment: state.prepared })`. Its way back
to the form is `leaveReview()`.

For an Amazon review, show `state.prepared.review.paymentDescriptor` verbatim
and mount the optional `mountChangeShippingAddress(element)` and
`mountChangePaymentMethod(element)` controls on your buttons. The client binds
Amazon's hosted change actions; after the redirect, resume the review to read
fresh details. Keep the controls for the same `review.id`; remount them when
that provider session changes. Do not turn the Amazon address into editable local fields.
`cart.reviewPayment({ preparation, returned })` also supports a custom return
page: forward provider query parameters except `preparation`; the server verifies
the session. Accept only the reviewed payment, never an untrusted returned ID.

## 3-D Secure in a wallet

Some banks ask for 3-D Secure even after Apple Pay or Google Pay. OrbCart opens
the challenge in a dialog above the page, so the buyer never loses sight of it.
Nothing to build.

## Setup checklist

- **Apple Pay with Stripe:** register your domain as a payment method domain in Stripe.
- **Apple Pay with Adyen:** serve Adyen's domain file at `/.well-known/apple-developer-merchantid-domain-association` as `text/plain`, and test with an Apple sandbox tester.
- **Apple Pay with PAYONE:** register your domain in PAYONE's portal and set `PAYONE_WALLET_NAME` and `PAYONE_WALLET_COUNTRY` ([details](/docs/shop/payments#google-pay-and-apple-pay)).
- **Google Pay:** nothing extra in test. In live, Google requires your merchant registration; with PAYONE, set its ID as `PAYONE_GOOGLE_PAY_MERCHANT_ID`.
- **Amazon Pay:** [configure credentials, region/currency and registered HTTPS review URLs](/docs/shop/payments#amazon-pay); use an Amazon sandbox buyer for acceptance.
- **Content Security Policy:** allow `pay.google.com` and Apple's Pay SDK.
- **HTTPS:** wallets only show on secure origins. `localhost` counts as secure.

<Callout type="warn" title="Testing Apple Pay">
Stripe test cards cannot be added to Apple Pay. Use a real card in your wallet with Stripe's test
keys: Stripe creates a test token and charges nothing.
</Callout>

[Find test cards and accounts →](/docs/shop/test-payments)