Two ways to take payment
| Hosted checkout | Your own checkout | |
|---|---|---|
| What you build | Event and ticket choice on your site; then a redirect. | Every step on your site, with Stripe’s Payment Element for the card. |
| Buyer details and card | Taken by your EOS shop’s checkout, in your name and colours. | Your form, then Stripe’s secure card field on your page. |
| Calls | Create a session, redirect to its url. | Create a session, complete it, confirm the payment with Stripe.js. |
| Card data on your site | None. | None: the Payment Element sends it straight to Stripe. |
Either way the money goes to your own Stripe account, the buyer gets the same ticket emails, and the guests are on the same door list.
1. Show events and prices
Read events with their ticket types, prices and what is left. Buyers pay AVEO’s booking fee on card orders, once per order, at the band of the most expensive ticket, so show each type’s price_with_booking_fee (the price of buying one), as the law on headline prices asks; the fee itself is booking_fee. When your company absorbs the fee in its prices (booking_fee_payer iscompany), booking_fee is 0 and buyers pay the price alone. A type with paid_at_door costs its door_price, paid at the door. Keep the list for a minute or so rather than asking on every page view.
curl "https://eos.aveoevents.com/api/v1/events?expand=ticket_types" \
-H "Authorization: Bearer $EOS_API_KEY"2. Hold the tickets
When the buyer has chosen, create a checkout session. It holds the tickets until expires_at, usually 15 minutes. Add a discount_code if they entered one, and anything of your own in metadata, such as your basket number: it comes back on the session.
422 unavailable: a ticket type is sold out, off sale, or the quantity is outside its limits. Ask the buyer to choose again.422 discount_invalid: the code does not work on this event. Say so, and offer to carry on without it.- If the buyer gives up, cancel the session to put the tickets back on sale at once.
- With a publishable key, one visitor holds at most five sessions at a time (
429 too_many_holds), so a web page cannot tie up an event’s tickets.
curl -X POST "https://eos.aveoevents.com/api/v1/checkout/sessions" \
-H "Authorization: Bearer $EOS_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"event_id":41,"items":[{"ticket_type_id":9001,"quantity":2}],"metadata":{"basket":"8812"}}'{
"object": "checkout_session",
"id": "cs_9f2c4e1a7b3d5f8e0a6c2b4d",
"status": "open",
"event_id": 41,
"order_id": "O-7KQ2M4X",
"url": "https://eos.aveoevents.com/acme-events/checkout-link/eyJhbGciOi...",
"expires_at": "2026-11-20T10:30:00.000Z",
"currency": "GBP",
"amount_items": 50,
"booking_fee": 1,
"booking_fee_payer": "buyer",
"amount_total": 51,
"discount_code": null,
"items": [
{
"ticket_type_id": 9001,
"product_id": 812,
"name": "General admission",
"quantity": 2,
"unit_price": 25,
"total": 50,
"price_before_discount": null
}
],
"payment": null,
"metadata": {
"basket": "8812"
},
"created_at": "2026-11-20T10:15:00.000Z"
}3a. Hosted checkout
Redirect the buyer to the session’s url. It opens your EOS shop’s checkout with the tickets in it, where they enter their details and pay. They finish on their order page in your shop with their QR tickets, which are also emailed. The link works once the tickets are held and stops when the hold ends.
// Express route: hold, then hand over to the hosted checkout
app.post("/buy", async (req, res) => {
const session = await createSession(req.body); // POST /checkout/sessions, as above
res.redirect(303, session.url);
});3b. Your own checkout
Take the buyer’s name and email on your page, and each guest’s name if tickets are named. For a ticket type with an age limit, each of those guests’ date_of_birth is required: it is checked against the event’s date, and shown at the door. Then complete the session. That places the order.
curl -X POST "https://eos.aveoevents.com/api/v1/checkout/sessions/cs_9f2c4e1a7b3d5f8e0a6c2b4d/complete" \
-H "Authorization: Bearer $EOS_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"buyer":{"first_name":"Sam","last_name":"Taylor","email":"sam@example.com"},"payment_method":"card"}'{
"object": "checkout_session",
"id": "cs_9f2c4e1a7b3d5f8e0a6c2b4d",
"status": "complete",
"event_id": 41,
"order_id": "O-7KQ2M4X",
"url": "https://eos.aveoevents.com/acme-events/checkout-link/eyJhbGciOi...",
"expires_at": "2026-11-20T10:30:00.000Z",
"currency": "GBP",
"amount_items": 50,
"booking_fee": 1,
"booking_fee_payer": "buyer",
"amount_total": 51,
"discount_code": null,
"items": [
{
"ticket_type_id": 9001,
"product_id": 812,
"name": "General admission",
"quantity": 2,
"unit_price": 25,
"total": 50,
"price_before_discount": null
}
],
"payment": {
"method": "card",
"amount": 51,
"booking_fee": 1,
"client_secret": "pi_3Q..._secret_...",
"publishable_key": "pk_live_...",
"stripe_account": "acct_1Q..."
},
"metadata": {
"basket": "8812"
},
"created_at": "2026-11-20T10:15:00.000Z"
}- Free orders are done at this point: the order is complete and the tickets are emailed.
- Card: the answer’s
paymentblock has what Stripe.js needs, and itsamountis the order plus thebooking_fee. Go to step 4. - Paid at the door: a ticket type with
paid_at_dooris free online, so an order of only those is done at once like a free one. Itsdoor_priceis taken at the door: the scanner asks for it before the guest goes in. There is no pay later.
4. Take the card with Stripe
Mount Stripe’s Payment Element with the client_secret, on your company’s Stripe account (stripe_account). The card goes straight to Stripe. When Stripe confirms the payment, EOS marks the order paid and emails the tickets.
<form id="pay">
<div id="payment-element"></div>
<button>Pay</button>
</form>
<script src="https://js.stripe.com/v3/"></script>
<script>
// payment: the block from completing the checkout session (step 4)
const stripe = Stripe(payment.publishable_key, { stripeAccount: payment.stripe_account });
const elements = stripe.elements({ clientSecret: payment.client_secret });
elements.create("payment").mount("#payment-element");
document.getElementById("pay").addEventListener("submit", async (e) => {
e.preventDefault();
const { error } = await stripe.confirmPayment({
elements,
confirmParams: { return_url: "https://www.example.com/thanks?order=" + orderId },
});
if (error) showError(error.message); // otherwise the buyer is on their way to return_url
});
</script>Do not treat the buyer arriving at your return_url as proof of payment. Wait for the order.paid webhook, or read the order and check its payment_status. A card order not paid within 30 minutes is cancelled and its tickets go back on sale.
5. Confirm the order
Subscribe a webhook endpoint to order.created, order.paid, order.payment_failed, order.cancelled and order.refunded, and to checkout.session.completed, checkout.session.expired and checkout.session.cancelled for the holds themselves. Each carries the whole object, so you can update your own records without asking the API again.
Orders from your site say so: "channel": "api", with the checkout_session_id and the metadata you sent (your basket number, campaign or customer id), so every sale ties back to your own records.
All from a web page
A publishable key can read events and create, complete and cancel checkout sessions, from the web addresses you list on it. That is enough for a site with no server of its own. Webhooks still need a server, or a service that receives them for you.
// Everything from a web page, with a publishable key that allows this page's address
const KEY = "eos_pk_12_...";
const api = (path, body) =>
fetch("https://eos.aveoevents.com/api/v1" + path, {
method: body ? "POST" : "GET",
headers: { Authorization: "Bearer " + KEY, "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID() },
body: body ? JSON.stringify(body) : undefined,
}).then((r) => r.json());
const session = await api("/checkout/sessions", { event_id: 41, items: [{ ticket_type_id: 9001, quantity: 2 }] });
location.href = session.url; // hosted checkout, or complete it and use the Payment Element as aboveTrying it out
- Start with a free ticket type: the whole flow runs and the tickets arrive by email, with no payment.
- For card payments, buy one low-priced ticket and refund it in EOS or with refund.
- Every request appears on the API keys page with its status and request id, which helps when something does not work.