Skip to Content
Build a shop

ORBCOMMERCE DOCUMENTATION

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" 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.

<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.

Two kinds of express

ModeMethodsHow it works
sheetApple Pay, Google PayThe buyer picks address and card in the wallet sheet and pays there.
reviewPayPal, Amazon PayThe 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:

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.

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

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().

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).
  • 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; 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.

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.

Find test cards and accounts →

On this page