The checkout and when it can be paid

Who this is for. Developers building a checkout page, and anyone asked why a shopper's pay button is disabled. After this page you can say what state a checkout is in, what can still change, and exactly what is missing before it can be paid.

A checkout is a record

A checkout is created from the cart when the shopper starts paying, and becomes an order once they have paid in full. The cart page's checkout button sends POST /checkout, which creates the checkout from the cart's available items, copies the cart's currency and discount codes, and works out the discounts and totals again. Items that are not available stay behind in the cart; a request that names an unavailable item explicitly is refused with a 400 (error.item.notAvailable).

In between, the checkout holds what the cart does not: the person and their email address, billing and delivery addresses, fulfilments with their shipping rates, order metadata, and the totals with discounts, shipping and tax. Three facts shape the rest of this page:

• It has no status field. "Ready for payment" and "fully paid" are worked out from its contents every time they are asked for, never stored.
• A client writes four fields: person, billingAddress, deliveryAddress and metadataFieldValues. Items, fulfilments and totals are managed by the platform, through the calls that create shipping, add codes and take payment.
• It is found through a cookie called checkout, which GET /checkout reads to find the visitor's checkout.

Its currency, and the language of its lines

A checkout is in one currency from start to finish: the cart's currency at the moment the checkout was created, copied across and never chosen on the checkout itself. The cart's currency is set when its first item is added (the currencyCode sent with that add, or else the default currency) and stays until the cart is emptied; see Prices and currencies. Every amount on the checkout, from item prices to shipping rates, discounts and tax, is in that currency. A template reads its code with {$checkout->getCurrencyCode()} (Twig {{ checkout.getCurrencyCode() }}), and the page's script receives it the same way (Seed the state from the server).

A line's name is stored on the line when the item is added to the cart. It is the product's name in the client's default language, and it stays as stored for the life of the cart and the checkout; the line carries no language of its own. On a multilingual site, print each line in the shopper's language from its product: take the line's product (getProduct()) and read its description in the visitor's language, with the default as the fallback, as Reading the right description shows. Build the line's link from the same description, so its name and its URL are in the same language.

From cart to order

A checkout passes through up to three stages. What brings it to each, and what can still change there:

A shopper can also leave: DELETE /checkout abandons the checkout and returns them to the cart.

What "ready for payment" requires

A checkout is ready for payment when all four of these hold:

1. It has at least one fulfilment.
2. Every fulfilment has a selected shipping rate that has not expired. A rate lasts an hour from when it was created.
3. It has a person with an email address.
4. It has a billing address.

A delivery address is not one of them. A shipping rate is, so a store that sells only digital goods still creates shipping and selects a rate: give it a shipping method that returns a free rate for every address (Shipping methods and their templates). Creating shipping, and what to do when a rate expires, are on Addresses and shipping at checkout.

Why the pay button is disabled

The checkout says which condition is missing. After every create and every edit, the API response carries a warning message for each check that does not pass, so the page can show the reason next to a disabled button before the shopper tries to pay:

Disable the pay button while any of these warnings is present, and print beside it what the shopper should do ("Choose a delivery option", "Add your billing address"). A purchase sent anyway is refused with a 400, "Checkout is not ready for payment" (error.checkout_not_ready_for_payment), and the response carries the same warnings again.

What the purchase call does

POST /cdna-api/checkout/<id>/purchase takes payment, in this order:

1. It checks the captcha token, unless the captcha is set to disabled (The captcha at purchase).
2. It checks that the checkout is ready for payment.
3. If the total is zero, it completes a free checkout: a zero invoice is still created and paid, and the checkout still becomes an order.
4. Otherwise it takes the payment method from _paymentMethodId, creates an invoice (or reuses the one it already has), and calls the payment provider.
5. It answers according to the provider's result.

"Paid in full" means the settled amount reaches the checkout's total: paid invoices count in full, open invoices by the amount authorised, draft and void invoices not at all. The completion URL carries the order's uuid, not the checkout's. Every result that leaves the payment unresolved splits the checkout from its cart before answering, so a payment that completes later is not affected by what the shopper does to the cart in the meantime. Handling each result on the page, and the providers themselves, are on Payment methods and how a payment runs.

The pages and the API

The platform supplies the routes and the records; the template, checkouts/single-page.html, and all of the page's script are yours.

GET /checkout is never cached. It finds the visitor's checkout by the checkout cookie and, without one, sends them to the cart. When a signed-in visitor opens a checkout that belongs to another person (a guest who has since signed in, say), it links the checkout to the signed-in person. It renders checkouts/single-page.html with three variables: checkout, metadataFields (every order metadata field defined for the site) and _recaptcha.

<id> is the checkout's uuid. Every call needs a signed-in visitor or guest checkout switched on (The guest checkout setting), and every call except the read is CSRF-checked.

The rest of the checkout

How to structure the page's script, and how to keep what a shopper has typed through a reload, are on The single-page checkout. Collecting the email and addresses and choosing shipping are on Addresses and shipping at checkout.

Discount codes and automatic discounts on the checkout, with what the checkout answers for each kind of code, have their own page: Discounts at checkout.

Order metadata fields, gift options and donations are on Donations, metadata and gift options.

Guest and account checkout, what each creates and how a guest gets an account later, have their own page, together with the captcha: Guest checkout and the captcha.