ORBCART DOCUMENTATION
A checkout without React
Your own checkout page in plain TypeScript, with the checkout store of @orbcart/client. Details, the binding total, a card field and every outcome of the order button.
You build a checkout page from your own markup: the buyer types their details, sees the exact total
with a card field, and orders. Every outcome, from 3-D Secure to a changed price, reaches the page
through one store, so the page only draws what the store says. Vue, Svelte or Solid subscribe to the
same store; <Checkout> is this store with React markup.
You need a Cart with a Line, such as from Add to cart, and its token
rendered into the page by your server. card must be mapped to a provider in the Channel's
payments.
1. The markup
<form id="details">
<label>Email <input name="email" type="email" autocomplete="email" required /></label>
<label>Name <input name="name" autocomplete="name" required /></label>
<label>Street <input name="line1" autocomplete="address-line1" required /></label>
<label>Postal code <input name="postalCode" autocomplete="postal-code" required /></label>
<label>City <input name="city" autocomplete="address-level2" required /></label>
<label>
Country
<select name="country" autocomplete="country">
<option value="DE">Germany</option>
<option value="AT">Austria</option>
</select>
</label>
<button>Continue to payment</button>
</form>
<div id="payment-field"></div>
<p id="total"></p>
<p id="notice" role="status"></p>
<button id="order" type="button" hidden></button>2. The page's code
import { createCommerce, describe, formatMoney } from "@orbcart/client";
import type { CheckoutState, MountedPayment } from "@orbcart/client";
const locale = "en-GB";
const words = describe(locale);
const commerce = createCommerce({
url: import.meta.env.VITE_ORBCART_URL,
key: import.meta.env.VITE_ORBCART_PUBLISHABLE_KEY,
});
// `savedToken` is yours: the Cart token your server rendered into this page.
const checkout = commerce.openCart(savedToken).checkout();
const form = document.querySelector<HTMLFormElement>("#details")!;
const field = document.querySelector<HTMLElement>("#payment-field")!;
const total = document.querySelector<HTMLElement>("#total")!;
const notice = document.querySelector<HTMLElement>("#notice")!;
const orderButton = document.querySelector<HTMLButtonElement>("#order")!;
orderButton.textContent = words.orderButton; // the wording the law asks for, in the buyer's language
let card: Promise<MountedPayment> | undefined;
checkout.subscribe(render);
// Also resumes a purchase the buyer comes back to, such as from PayPal or their bank.
void checkout.start();
form.addEventListener("submit", (event) => {
event.preventDefault();
const data = new FormData(form);
const value = (name: string) => String(data.get(name) ?? "");
void checkout.submitDetails({
contact: { email: value("email") },
shipTo: {
name: value("name"),
line1: value("line1"),
postalCode: value("postalCode"),
city: value("city"),
country: value("country"),
},
});
});
orderButton.addEventListener("click", async () => {
const method = checkout.state.paymentMethod;
if (method) await checkout.placeOrder({ payment: card ? await card : method.id });
});
function render(state: CheckoutState) {
if (state.order) {
form.hidden = field.hidden = orderButton.hidden = true;
notice.textContent = `Thank you. Your order number is ${state.order.number}.`;
return;
}
// Back from the provider, the purchase resumes by itself: nothing to type meanwhile.
form.hidden = state.resuming !== undefined;
notice.textContent = state.notice ? words.notice(state.notice).join(" ") : "";
total.textContent = state.quote ? formatMoney(state.quote.totals.total, locale) : "";
orderButton.hidden = state.step === "details";
orderButton.disabled = state.step !== "quoted" || state.busy !== undefined;
// The card field appears with the first Quote and outlives every later one.
const method = state.paymentMethod;
if (state.quote && method?.flow === "inline") card ??= checkout.mountPayment(method.id, field);
}The store runs one step at a time, in the order the buyer took them. Its steps never throw a refusal:
what the buyer must hear lands in state.notice, and describe() words it in English, German, French
or Dutch.
Offer more than the card
state.paymentMethods lists what this buyer can use. Draw them as choices, call
checkout.choosePayment(id), and mount the field again when the chosen method is inline. A
redirect method, such as PayPal, needs no field: placeOrder sends the buyer to the provider,
and start() picks the purchase up on their way back.
What the buyer sees
| Moment | The page shows |
|---|---|
| A field is empty or wrong | The notice names it, such as a postal code that does not fit the country. |
| Details complete | The exact total, the card field and "Order with obligation to pay". |
| The bank asks for 3-D Secure | The bank's check, opened from the card field, then the order number. |
| A price changed since the total | The notice says what changed and the new total stands. One more click orders at that total. |
| The card is declined | The notice says so, the button is ready again for another card. |
| The provider is slow | The notice says the page updates by itself; it turns into the order number once decided. |
| The buyer reloads or comes back | start() finds the running purchase. It never starts a second payment. |
Next
- Quotes & payments: the single calls under the store,
quote(),mountPayment()andpay(), for a server or an agent. - Errors: every code a notice can carry.
- Test a purchase: prove the flow against your own Worker.
Add to cart and a mini cart
An add-to-cart button for your product pages and a bag in the header that shows the server's Lines and total.
Prices and stock from your ERP
Answer OrbCart's offers and inventory contracts from an ERP over HTTP, with one request per call, parsed answers and a reservation that never sells the last unit twice.