Skip to content

Checkout flow

Checkout is a window over the shop page. The shopper enters contacts and delivery, reviews the order and pays by card; the card is saved for the following subscription charges.

  1. The shopper clicks «Checkout» in your cart.
  2. Your server creates the order through POST /v1/shop/orders/create with lines from getOrderItems() and returns order.id to the page.
  3. The page calls NeocartsSubscription.open({ orderId }).
  4. The shopper goes through the steps: contacts → delivery → review → payment.
  5. After payment the page receives neocarts:paid and the server receives the order.paid webhook.
try {
await NeocartsSubscription.open({ orderId: order.id });
} catch (e) {
// 'Shop is not ready' — the shop has not finished its setup
// e.status === 404 — order not found
}
Parameter Type Required Description
orderId string yes The order id from the Shop API response
locale string no uk or en; applies only when the order has no locale

Calling open() again with the same orderId does nothing; with another one it opens the new order and keeps the contacts and delivery already entered. close() closes the window.

First and last name, phone (+380…), email.

The «Contact details» step

Only the methods enabled in Settings → Delivery: Nova Poshta — branch, parcel locker or address, with city and branch search. The recipient defaults to the contact.

The «Delivery» step

Products and totals from the order, contacts, delivery and consent to recurring charges (when the order has subscriptions). «Go to payment» locks the order contents — the lines cannot be changed after it.

The «Review» step

The shop’s payment provider page opens inside checkout. After paying, the shopper is brought back to the result automatically.

Screen When What the shopper sees
Success payment confirmed order number, amount paid, delivery, subscriptions with next charge dates, «Back to the shop»
Failure the bank declined, the payment timed out, the card was not saved the reason and a button to pay again
Unavailable the order is cancelled or not found «Checkout unavailable», «Back to the shop»
Success Failure
Success screen Payment failure screen

Reason texts are in Statuses.

On a phone checkout takes the full screen:

Checkout on a phone

Moment Action
the shopper clicked «Checkout» create the order on the server, store order.id, call open({ orderId })
open() rejected with Shop is not ready show that subscriptions are temporarily unavailable; finish payment and delivery setup in the panel
the shopper changed the cart before paying update the lines with PUT /v1/shop/orders/{order}/items; on 409 create a new order
neocarts:paid empty the cart, forget order.id, show the order number
neocarts:order-missing forget order.id; the next «Checkout» creates a new order
the shopper closed the window without paying nothing; a «Continue checkout» button calls open() with the same order.id

The widget remembers an unfinished checkout in the shopper’s browser, so nothing has to be re-entered after a page reload. To continue, call open() with the same order.id or open the page with the ?neocarts=checkout marker. If the order is already paid, the shopper sees the success screen and the page receives neocarts:paid.

Where the success screen leads: the «Back to the shop» button, and also closing checkout with the header button or Esc. It is not passed to the payment provider. Without it all of these just close the window.