Skip to content

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:

  1. actions.startPayment() when the reservation has no client secret yet
  2. AxynStripeProvider around wallet + card UI
  3. WalletPayButton and/or PaymentForm
  4. PaymentReturn → 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

  1. Never create a Stripe PaymentIntent outside AXYN for AXYN inventory.
  2. Pass a publishable key only (stripePublishableKey on the spine, or publishableKey on AxynStripeProvider).
  3. Prefer the client secret (and optional Connect account / publishable key) returned on the reservation from AXYN — the provider reads those from checkout session state.
  4. After Stripe confirms, verify with AXYN (verify-payment). Do not treat Stripe success alone as order paid.
  5. Wait for hydrated before your own code reads a saved order on page load. See When a buyer reloads.

Exports

ExportRole
AxynStripeProviderLoads Stripe.js + Elements when session has a client secret
PaymentFormPayment Element + confirmPayment
WalletPayButtonApple Pay / Google Pay via Payment Request Button
PaymentFailureMessageRenders payment failure + retry CTA
mapStripeJsErrorStripe.js error → CheckoutPaymentFailure
createAxynStripeAppearanceElements appearance from AXYN theme mode
PaymentReturnRuns 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.clientSecret from checkout session. Without it, children render without Elements (drawer shows processing until startPayment).
  • Prefers reservation.stripePublishableKey when AXYN returns one; else your publishableKey.
  • Passes Connect account id into Stripe.js when present.
  • Appearance follows themeMode via createAxynStripeAppearance.

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:

  • failureReason
  • recommendedAction
  • retryable
  • cardCharged

Render with PaymentFailureMessage. Do not invent buyer-facing Stripe jargon in the host.

Return and verify

PieceJob
buildPaymentReturnUrlHost builds URL Stripe may redirect to
PaymentReturnCalls actions.verify() → AXYN verify-payment
onPaymentCompleteSpine 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, CheckoutSpineRoot and PaymentReturn already 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 until hydrated is true. Until then, state looks like an empty checkout, even when the buyer has an order in progress.
  • If your tests build a fake useCheckoutSession() value by hand, add hydrated: true to 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):

DirectiveSources
script-srchttps://js.stripe.com, https://*.js.stripe.com, https://maps.googleapis.com
frame-srchttps://js.stripe.com, https://*.js.stripe.com, https://hooks.stripe.com (3DS), Link (*.link.com)
connect-srchttps://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.

Next