React checkout
Stripe wrappers
AXYN owns PaymentIntent creation. The SDK wraps Stripe.js so hosts never create PaymentIntents for AXYN inventory, and so card failures map to clear buyer-facing retry copy.
Use Stripe test card 4242 4242 4242 4242 with any future expiry and CVC when
the order was created with an axyn_sk_test_... key.
Hosted axyn.events already runs pay for you. Do not mount Stripe yourself on that site.
Embed
Mount CheckoutSpineRoot. Phase 6 opens CheckoutPaymentDrawer, which already
wires:
actions.startPayment()when the reservation has no client secret yetAxynStripeProvideraround wallet + card UIWalletPayButtonand/orPaymentFormPaymentReturn→actions.verify()after confirm / redirect return
The client secret comes from POST /v1/orders/{orderId}/payments/start after
order create. After Stripe confirms, call POST /v1/orders/{orderId}/verify-payment.
Headless
Start the PaymentIntent on the server (payments/start). Confirm the PI in
the browser with the publishable key only. Never put a Stripe secret key
in the browser. Then verify-payment with the buyer JWT.
You only need the primitives below for a custom payment surface. Do not invent
a second PI path. OpenAPI: payments/start, verify-payment.
Hard rules
- Never create a Stripe PaymentIntent outside AXYN for AXYN inventory.
- Pass a publishable key only (
stripePublishableKeyon the spine, orpublishableKeyonAxynStripeProvider). - Prefer the client secret (and optional Connect account / publishable key) returned on the reservation from AXYN — the provider reads those from checkout session state.
- After Stripe confirms, verify with AXYN (
verify-payment). Do not treat Stripe success alone as order paid. - Wait for
hydratedbefore your own code reads a saved order on page load. See When a buyer reloads.
Exports
| Export | Role |
|---|---|
AxynStripeProvider | Loads Stripe.js + Elements when session has a client secret |
PaymentForm | Payment Element + confirmPayment |
WalletPayButton | Apple Pay / Google Pay via Payment Request Button |
PaymentFailureMessage | Renders payment failure + retry CTA |
mapStripeJsError | Stripe.js error → CheckoutPaymentFailure |
createAxynStripeAppearance | Elements appearance from AXYN theme mode |
PaymentReturn | Runs actions.verify() on return / post-confirm |
AxynStripeProvider
Must sit under AxynProvider and CheckoutSessionProvider (the spine root
already does this).
import { AxynStripeProvider } from '@axyn/web-sdk';
<AxynStripeProvider publishableKey={stripePublishableKey}>
{/* PaymentForm / WalletPayButton */}
</AxynStripeProvider>;
Behavior:
- Uses
reservation.clientSecretfrom checkout session. Without it, children render withoutElements(drawer shows processing untilstartPayment). - Prefers
reservation.stripePublishableKeywhen AXYN returns one; else yourpublishableKey. - Passes Connect account id into Stripe.js when present.
- Appearance follows
themeModeviacreateAxynStripeAppearance.
PaymentForm
Requires an ancestor Elements (from AxynStripeProvider with a secret).
import { PaymentForm } from '@axyn/web-sdk';
<PaymentForm
returnUrl={returnUrl}
submitLabel="Pay now"
onConfirmed={() => {
/* spine then verifies via PaymentReturn / session actions */
}}
onFailure={(failure) => {
/* CheckoutPaymentFailure — show PaymentFailureMessage */
}}
/>;
Props that matter: returnUrl (Stripe redirect when required), submitLabel,
disabled, onConfirmed, onFailure, optional footer, and wallets.
wallets is the organizer's How buyers can pay switches, as preview-total,
payment start and event detail return them (apple_pay, google_pay,
link: auto or never). Pass it through; omitted, the form uses AXYN's
defaults (Apple Pay and Google Pay on, Saved card (Link) off). The ticket
panel and checkout drawer already pass it, and
resolveCheckoutPaymentMethods(…, { wallets }) drops a wallet choice the
organizer turned off.
Confirm uses redirect: 'if_required'. Hosts must still handle return URLs
(buildPaymentReturnUrl on the spine) for 3DS / redirect methods.
WalletPayButton
Same provider requirement. Shows only when the browser can make a payment request; otherwise the drawer falls back to card-only.
import { WalletPayButton } from '@axyn/web-sdk';
<WalletPayButton
onSuccess={() => {
/* then verify */
}}
onFailure={(failure) => {
/* show PaymentFailureMessage */
}}
onCancel={() => {
/* buyer dismissed sheet */
}}
/>;
Amount/currency come from checkout session preview (AXYN server totals).
Failure mapping
mapStripeJsError / toCheckoutPaymentFailure map Stripe codes and decline
codes to:
failureReasonrecommendedActionretryablecardCharged
Render with PaymentFailureMessage. Do not invent buyer-facing Stripe jargon
in the host.
Return and verify
| Piece | Job |
|---|---|
buildPaymentReturnUrl | Host builds URL Stripe may redirect to |
PaymentReturn | Calls actions.verify() → AXYN verify-payment |
onPaymentComplete | Spine handoff after paid |
When a buyer reloads or comes back from Stripe
A buyer might reload the page in the middle of paying. Or their bank might send them to another page to check it is really them, and then Stripe sends them back to you. Either way, the SDK remembers their order in that browser tab, so they can carry on where they stopped.
The SDK looks for that saved order only after your page has loaded in the browser. It never looks while your server is building the page, because the server cannot see what the browser saved. This keeps the page your server sends and the first thing the browser shows the same. If they differed, React would stop with a "Hydration failed" error.
What this means for you:
TicketPanel,CheckoutSpineRootandPaymentReturnalready wait for the saved order. You do not need to do anything for them.- If your own code uses
useCheckoutSession()and checks for an order when the page first loads, wait untilhydratedistrue. Until then,statelooks like an empty checkout, even when the buyer has an order in progress. - If your tests build a fake
useCheckoutSession()value by hand, addhydrated: trueto it.
import { useCheckoutSession } from '@axyn/web-sdk';
import { useEffect } from 'react';
const { state, hydrated } = useCheckoutSession();
useEffect(() => {
if (!hydrated) {
return; // The saved order has not been loaded yet.
}
if (state.reservation) {
// The buyer has an order in progress.
}
}, [hydrated, state.reservation]);
Fixture mode alone is not enough for live card entry — you need the live buyer stack (auth + payments). See Checkout spine.
Receipts vs tickets (dual email)
AXYN creates PaymentIntents with receipt_email when the order has a purchaser
email. Stripe may send its own payment receipt. Separately, AXYN sends the
ticket email (venue display name, PDF, hosted ticket link).
MVP keeps both. Do not turn off Stripe receipts in your integration. See Ticket delivery.
Card statement branding (merchant of record) comes from the venue’s Stripe Connect account descriptor on direct charges — not from the email From line.
Content Security Policy
If your page sends a CSP, it must let Stripe.js load, frame and call Stripe.
@axyn/web-sdk/security-headers exports the list as STRIPE_CSP_SOURCES
(from Stripe's security guide):
| Directive | Sources |
|---|---|
script-src | https://js.stripe.com, https://*.js.stripe.com, https://maps.googleapis.com |
frame-src | https://js.stripe.com, https://*.js.stripe.com, https://hooks.stripe.com (3DS), Link (*.link.com) |
connect-src | https://api.stripe.com, https://maps.googleapis.com, Link (*.link.com) |
The @axyn/web-sdk entry imports @stripe/stripe-js, which injects the
Stripe.js script as soon as it is imported, so every page that imports the SDK
needs these sources, not only the checkout page.
Do not restrict payment in Permissions-Policy: Apple Pay and Google Pay
run inside Stripe frames on js.stripe.com and its subdomains. Stripe.js has
no SRI hash and must not be self-hosted, so CSP is the integrity control.
Hosted AXYN pages send frame-ancestors 'none': they cannot be framed. Mount
the SDK in your page instead (Embed).
Anti-patterns
- Creating PIs in your backend for AXYN seats/tickets
- Skipping verify because Stripe.js said
succeeded - Putting secret keys in the browser
- Computing pay amounts only on the client
See Anti-patterns.