Quotes & payments

For a ready-made checkout, start with React. This page explains the same purchase using the framework-free client.

Ask for a Quote

Continue with a Cart containing at least one available Line:

const quote = await cart.quote({
  contact: { email: "alex@example.com" },
  shipTo: {
    name: "Alex Example",
    line1: "Example Street 12",
    postalCode: "10115",
    city: "Berlin",
    country: "DE",
  },
});

quote.totals.total is the total to show above the order button. Render money with the SDK rather than dividing amounts yourself:

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

const total = formatMoney(quote.totals.total, "en-GB");

If details are missing, the call throws CommerceError with problem.code === "cart_incomplete" and a problem.missing list. Ask for those details before quoting again. The React checkout does this for you.

Collect payment details

For a browser checkout with card payments enabled, place an empty container on the page:

<div id="payment-field"></div>

Mount the provider's field into it:

const element = document.querySelector<HTMLElement>("#payment-field");
if (!element) throw new Error("The payment container is missing.");

const payment = await quote.mountPayment("card", element);

The field belongs to the payment provider. Card details never pass through your own form. Use a method offered by quote.paymentMethods; not every Channel offers card payments.

Place the Order

Only call this from the buyer's explicit order-button action:

const result = await quote.pay({ payment });

pay() collects the field, accepts the Quote, runs any required payment action (such as 3-D Secure) and follows the result. A slow payment can still return pending.

Use quote.accept({ payment }) instead if you want to handle each action yourself. A timeout is not proof of a failed payment. Never create a second purchase to work around an unclear result.

Return from a payment provider

On the Channel's configured return page, recover the Cart from its saved token:

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

resume() reads the return parameters from the browser URL. Handle the same outcomes as above. To reopen a known Quote after a reload, use cart.openQuote(quoteId); its response includes the known acceptance.

Unmount a payment field when its page or Quote is replaced:

payment.unmount();

Let the React checkout handle these steps →