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
| 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:
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}`)}
/>
);
}onOrderedgets each Order once. Show your confirmation page.onReviewedtakes 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. WithoutonReviewed, only the wallets that pay in their sheet are offered.returnTois that page. A buyer PayPal redirects instead of using its popup comes back there, in the language they shopped in.pendingkeeps 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-associationastext/plain, and test with an Apple sandbox tester. - Apple Pay with PAYONE: register your domain in PAYONE's portal and set
PAYONE_WALLET_NAMEandPAYONE_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.comand Apple's Pay SDK. - HTTPS: wallets only show on secure origins.
localhostcounts 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.