Integrating Stripe payments with Spring Boot

Stripe is a widely used payment platform that lets Australian merchants accept cards and eligible digital wallets while keeping sensitive card data outside their application servers.

Integrating the Stripe payment gateway into a Spring Boot application normally means creating a payment intent, confirming it in the browser, and accepting signed webhook events for fulfilment.

Local details matter: prices are generally shown in Australian dollars with GST included, and shoppers often call a card or wallet payment a “card payment.” Afterpay also shapes payment expectations in Australia, even when it is offered separately from Stripe.

The following design keeps secret keys on the server, calculates totals from trusted order data, and treats Stripe webhooks as the authoritative signal that an order has been paid.

Configure Stripe and Spring Boot

Start with a Stripe test account, then keep test and live credentials separate. The publishable key is safe for browser code, while the secret key and webhook signing secret must remain server-side.

stripe:
  secret-key: ${STRIPE_SECRET_KEY}
  webhook-secret: ${STRIPE_WEBHOOK_SECRET}
  publishable-key: ${STRIPE_PUBLISHABLE_KEY}

Load these values through environment variables and map them with Spring Boot’s configuration-properties support. Add the current Stripe Java SDK, Spring Web, and Validation starter, then create one StripeClient bean for the application.

Create PaymentIntents on the server

Create the intent in a POST service only for an authenticated customer’s order. Read the product and total from your database, set the currency to aud, and add an order identifier as metadata. Never trust a browser-supplied price.

PaymentIntentCreateParams params = PaymentIntentCreateParams.builder()
    .setAmount(order.totalInCents())
    .setCurrency("aud")
    .setAutomaticPaymentMethods(true)
    .putMetadata("orderId", order.id())
    .build();

RequestOptions options = RequestOptions.builder()
    .setIdempotencyKey("checkout-" + order.id())
    .build();

PaymentIntent intent = stripeClient.paymentIntents()
    .create(params, options);

Reuse a stable idempotency key for retries of the same checkout attempt so a double click cannot create duplicate intents. Return the PaymentIntent ID and client_secret to the browser; the client secret authorises confirmation, while your Stripe secret key must never leave the server.

Choose the checkout experience

PaymentIntents power a flexible embedded checkout, but Stripe also provides hosted choices. Compare the common approaches before writing the storefront:

Approach Customer flow Best suited to Main trade-off
Payment Element and PaymentIntent Embedded in your page Custom designs and dynamic carts Requires the most storefront code
Checkout Session Stripe-hosted payment page Fast, standard checkout Less control during the redirect
Payment Link Fixed Stripe payment page Simple products or invoices Limited order customisation

For most Spring Boot stores needing order-specific totals and a branded checkout, the Payment Element provides a practical balance. It keeps the payment interface responsive while the server remains responsible for pricing, inventory, customer accounts, and fulfilment.

Connect Stripe.js to the frontend

Load Stripe.js with the publishable key, create Elements from the client secret, and mount the Payment Element inside the order form. A typical confirmation flow is:

const stripe = Stripe(STRIPE_PUBLISHABLE_KEY);
const elements = stripe.elements({ clientSecret });
const paymentElement = elements.create("payment");

paymentElement.mount("#payment-element");

const result = await stripe.confirmPayment({
  elements,
  confirmParams: {
    return_url: `${window.location.origin}/orders/${orderId}/complete`
  },
  redirect: "if_required"
});

Handle inline errors and redirects for authentication methods such as 3D Secure. Stripe.js and the Payment Element collect the card details directly from the customer, so raw card numbers must never pass through your Spring Boot controllers, logs, or database.

Verify Stripe webhook events

Expose a POST endpoint for Stripe webhooks and verify the Stripe-Signature header against the endpoint’s signing secret before acting on an event. Preserve the raw request body so signature verification succeeds.

@PostMapping("/webhooks/stripe")
public ResponseEntity<Void> stripeWebhook(
        @RequestBody byte[] payload,
        @RequestHeader("Stripe-Signature") String signature)
        throws EventConstructionException {

    Event event = Webhook.constructEvent(payload, signature, webhookSecret);
    handle(event);
    return ResponseEntity.ok().build();
}

Treat payment_intent.succeeded as the trigger for fulfilment and record payment_intent.payment_failed for recovery or customer notification. Store processed event IDs to prevent duplicate fulfilment when Stripe retries a webhook. During local testing, the Stripe CLI can forward signed events to a development endpoint.

Persist payment state safely

Persist the internal order ID, Stripe PaymentIntent ID, amount in cents, AUD currency, status, and processed Stripe event IDs. Add unique constraints so repeated webhooks cannot create duplicate payments or fulfilment records.

Do not mark an order paid merely because the customer returned to the success page; that page can be closed or refreshed. Fulfil from a verified event, handle failed or cancelled states, and issue refunds through Stripe so its records remain consistent. Keep GST and total amounts available for Australian accounting and reconciliation.

Launch checks for an Australian deployment

Before launch, prove the important paths:

After launch, monitor service health and customer behaviour: