Stripe payment provider
This module implements Stripe Checkout and Stripe webhook handling behind the Payment Gateway provider SPI. Stripe-specific API calls, payload parsing, signature verification, and status mapping stay inside this module.
Provider configuration
Every Stripe PaymentProvider must contain these configuration fields:
| Field | Required | Purpose |
|---|---|---|
secretKey | yes | Stripe secret or restricted API key used to create and retrieve Checkout Sessions. Test keys normally start with sk_test_. |
webhookSecret | yes | Signing secret of the configured Stripe webhook endpoint. It starts with whsec_. |
Example configuration:
{
"provider": "stripe",
"config": {
"secretKey": "sk_test_...",
"webhookSecret": "whsec_..."
}
}
Never commit real keys. The Stripe CLI signing secret and the Dashboard endpoint signing secret are different values. Store the secret belonging to the endpoint that sends events to the current environment.
API endpoint override
By default, the provider lets the Stripe SDK use Stripe’s official API endpoint. Isolated integration environments may set the provider-owned Spring property:
payment-provider:
stripe:
api-base-url: http://localhost:8090
Spring’s environment-variable equivalent is:
PAYMENT_PROVIDER_STRIPE_API_BASE_URL=http://localhost:8090
This is process-level test infrastructure configuration, not tenant PaymentProvider config. The Stripe provider’s auto-configuration owns the property and applies it only while constructing the Stripe SDK client. If it is absent, the SDK default is unchanged. Payment Gateway does not contain Stripe-specific configuration binding.
Webhook endpoint
The backend route is:
POST /providers/stripe/webhooks
Typical URLs are:
# Backend accessed directly
http://localhost:8080/providers/stripe/webhooks
# Default Labs64 gateway route
https://gateway.example.com/payment-gateway/api/v1/providers/stripe/webhooks
The external gateway prefix is deployment-specific. Confirm it before registering the endpoint. Stripe must be able to reach the URL over the internet; it cannot call localhost directly.
Required webhook events
Configure the Stripe endpoint for these events:
| Stripe event | Gateway result |
|---|---|
checkout.session.completed | SUCCESS when payment_status is paid or no_payment_required; otherwise PENDING |
checkout.session.async_payment_succeeded | SUCCESS |
checkout.session.async_payment_failed | FAILED |
checkout.session.expired | FAILED |
The provider stores paymentTransactionId in Checkout Session and Payment Intent metadata. The webhook uses this metadata to restore the correct transaction and provider configuration before signature verification.
Dashboard setup
- Open Stripe Dashboard and select the correct Test or Live mode.
- Go to Developers → Webhooks and add the public Payment Gateway webhook URL.
- Select the events listed above.
- Reveal the endpoint signing secret.
- Save that value as
webhookSecretin the corresponding Payment Gateway Stripe provider configuration.
Stripe documentation:
Local development with Stripe CLI
Authenticate the CLI and forward only the supported events:
stripe login
stripe listen \
--events checkout.session.completed,checkout.session.async_payment_succeeded,checkout.session.async_payment_failed,checkout.session.expired \
--forward-to http://localhost:8080/providers/stripe/webhooks
stripe listen prints a temporary whsec_... signing secret. Put that value in the local Stripe provider configuration while the listener is in use.
Checkout flow
- The client calls
/payments/{paymentId}/payand supplies absolutecheckout.returnUrlandcheckout.cancelUrlvalues. These are the final tenant/client destinations. - Payment Gateway validates the request before creating the payment attempt.
- Payment Gateway creates the transaction and Checkout Session, then builds its own provider callback URLs.
- The Stripe provider creates a Stripe Checkout Session using the gateway callback URLs and stores the gateway transaction ID in Stripe metadata.
- The client follows the returned redirect action to Stripe Checkout.
- Completion can reach Payment Gateway through the browser return, a Stripe webhook, or both.
- The provider verifies the webhook using the exact raw body and
Stripe-Signature, then returns a normalized provider result. - Payment Gateway applies the result under a database lock. A duplicate terminal result cannot overwrite the transaction.
- For a successful one-time payment, the transaction becomes
SUCCESS, the payment becomesCLOSED, and finalized/closed events are published.
Troubleshooting
- Controller breakpoint is not reached: verify the route and external gateway prefix. Check that the endpoint is publicly reachable.
- HTTP 400 / signature verification failed: the configured
webhookSecretdoes not belong to the sending endpoint, or the raw request body was modified before verification. - Webhook cannot restore the transaction: confirm the event belongs to a Checkout Session created by this provider version and contains
paymentTransactionIdmetadata. - Stripe CLI remains on
Getting ready: run it with--log-level debugand check proxy/firewall access to Stripe WebSocket endpoints. - Browser return and webhook arrive together: this is expected. The transaction update lock and terminal-state guard make processing idempotent.