Carts & checkout

ORBCART DOCUMENTATION

Quotes & payments

Show the exact total, collect the payment and turn the purchase into an Order.

Using React? <Checkout> does everything on this page for you. In another framework, the checkout store does: A checkout without React. Read on for the single calls underneath, for a server or an agent.

1. Ask for a Quote

const quote = await cart.quote({
  contact: { email: "anna@example.com" },
  shipTo: {
    name: "Anna Berg",
    line1: "Bergstraße 12",
    postalCode: "10115",
    city: "Berlin",
    country: "DE",
  },
});

The Quote is binding. It is signed, holds the exact total and expires after at most 30 minutes. Show quote.totals.total next to the order button:

import { formatMoney } from "@orbcart/client";

formatMoney(quote.totals.total, "en-GB"); // "€94.85"

Never divide amounts yourself.

Details missing? The call throws CommerceError with code cart_incomplete. error.problem.missing lists what to ask for, such as ["ship_to_postal_code"].

2. Let the buyer choose how to pay

quote.paymentMethods lists what this buyer can use right now. It depends on the Channel, the currency and the billing country:

quote.paymentMethods;
// [{ id: "card", provider: "adyen", flow: "inline" },
//  { id: "paypal", provider: "paypal", flow: "redirect" },
//  { id: "klarna", provider: "adyen", flow: "redirect" }]
flowWhat happens
inlineA field from the provider sits on your page. Card, Bancontact.
redirectThe buyer leaves for the provider and comes back. PayPal, Klarna, iDEAL, TWINT.
walletA wallet sheet opens. Apple Pay, Google Pay. Express →

3. Mount the payment field

For an inline method, give the provider an empty element:

<div id="payment-field"></div>
const element = document.querySelector<HTMLElement>("#payment-field")!;
const payment = await quote.mountPayment("card", element);

Card details go straight to the provider. They never touch your page or OrbCart. The field outlives the Quote, so a new Quote can use the same field.

For a redirect method, there is nothing to mount. Pass the method's name instead.

Match the field to your page

Adyen draws its card from CSS variables on the element, Stripe from an appearance. Both helpers take your colors, so the field reads like the rest of your checkout:

import { adyenVariables, stripeAppearance } from "@orbcart/client";

const colors = { text: "#0a0f1f", surface: "#fff", action: "#31476b", radius: "6px" };
Object.assign(
  element.style,
  adyenVariables({
    ...colors,
    muted: "#5b6275",
    error: "#b3261e",
    border: "#d9dce4",
    focus: colors.action,
  }),
);
const payment = await quote.mountPayment("card", element, { appearance: stripeAppearance(colors) });

Adyen's variables accept var(--your-token); Stripe's field is its own document and needs literal colors. Pass dark: true to stripeAppearance on a dark page.

4. Place the Order

Call pay() only from the buyer's click on the order button:

const result = await quote.pay({ payment }); // inline: the mounted field
const result = await quote.pay({ payment: "paypal" }); // redirect: the method's name

pay() accepts the Quote, runs 3-D Secure if the bank asks for it and waits for the answer. Handle every outcome:

switch (result.status) {
  case "ordered":
    return showConfirmation(result.order.number);
  case "quote_changed":
    return askAgain(result.quote, result.changes);
  case "failed":
    return letBuyerTryAgain();
  case "pending":
    return showWaiting(result);
  case "requires_action":
    return result.action.run();
}
statusWhat it means and what you do
orderedDone. Show result.order.number.
quote_changedA price, stock or shipping changed. Show result.quote and result.changes. Ask again.
failedThe payment was declined. Let the buyer fix it or pick another method.
pendingThe provider has not decided after 10 seconds. Wait, don't retry.
requires_actionThe buyer left a step unfinished, such as 3-D Secure. result.action.run() continues it.

Never start a second payment to escape pending

A timeout is not a failed payment. The money may already be on its way. Follow the same purchase until the provider decides.

Waiting for an undecided payment

A pending result's wait() checks again for 10 seconds. To keep a page open until the provider decides, wait without a limit:

if (result.status === "pending") {
  const outcome = await result.wait({ timeout: Infinity });
}

The runtime decides within the 30-minute payment window at the latest. <Checkout> does this for you: after 10 seconds it shows a calm waiting panel, asks the buyer not to order again, and becomes the confirmation once the provider answers.

5. Return from a redirect

PayPal, Klarna, iDEAL and others send the buyer to the Channel's returnUrl. On that page, open the saved Cart and resume:

const cart = commerce.openCart(savedToken);
const result = await cart.resume();

resume() reads the return parameters from the page's URL and answers with the same outcomes as pay().

After a normal reload in the middle of checkout, reopen the Quote instead:

const quote = await cart.openQuote(quoteId);

It never starts a new payment. It returns the Quote with what its last payment came to.

pay() or accept()?

MethodUse it when
pay()A buyer is on the page. Runs every step and waits. Use this.
accept()You want to run each step yourself, or you pay from a server or an agent with a ready-made token (instrument).

Verify a Quote

Every Quote is signed with the environment's key. Anyone can check it, even years later:

import { verifyQuote } from "@orbcart/client";

const keys = await fetch(`${ORBCART_URL}/.well-known/jwks.json`).then((r) => r.json());
const { valid } = await verifyQuote(quote, keys);

An Order keeps its signed Quote in order.quote, so the agreed purchase stays provable.

Configure shipping →

On this page