Payments & Webhooks

NXCart supports Stripe and PayPal hosted payment flows with webhook-based order confirmation.

Stripe setup checklist

You'll need a Stripe account. Stripe keeps test and live data apart, so each page below has a test and a live version; use the one that matches the Mode you choose in NXCart.

What	Test mode	Live mode
Publishable and secret keys	Test API keys	Live API keys
Webhook endpoint and its signing secret	Test webhooks	Live webhooks
Payment methods shown at checkout	Test payment methods	Live payment methods

1. Open the API keys page (test or live) and copy the Publishable key (pk_test_... or pk_live_...) and the Secret key (sk_test_... or sk_live_...; click Reveal to see it).
2. Open the Webhooks page (test or live) and add an endpoint. For its URL, copy the one shown in Settings → Payments → Stripe in NXCart (it looks like this): https://yoursite.com/index.php?option=com_nxcart&task=webhook.stripe
3. Select these events for the endpoint:
   • checkout.session.completed (required: settles the order once payment clears)
   • checkout.session.expired (recommended: cancels an abandoned checkout and releases the reserved stock promptly)
   • checkout.session.async_payment_succeeded and checkout.session.async_payment_failed (required if you offer payment methods that take days to clear, such as SEPA Direct Debit: they confirm or cancel those orders)
4. Open the endpoint you just created and copy its Signing secret (whsec_...).
5. In NXCart, enter the publishable key, secret key and signing secret in Settings → Payments → Stripe, choose the mode, and enable Stripe.
6. Choose which payment methods buyers see (cards, Apple Pay, Google Pay, Link, Klarna, iDEAL, SEPA and others) on the Payment methods page (test or live). NXCart offers whatever you turn on there.

Stripe's own guides: API keys and webhook endpoints.

Which events to send

NXCart settles strictly from the Checkout Session lifecycle, so those four events are all it needs. You don't need to add payment_intent.* events: they're ignored (they share the session's payment id, so acting on them could interfere with settlement). A failed card attempt simply leaves the order pending; the buyer can retry, and an unfinished checkout is cleaned up when its session expires.

PayPal setup checklist

NXCart uses PayPal's current REST integration (Orders API v2 with a client ID and secret). You don't need the older API username, password and signature, or IPN.

You'll need a PayPal business account. Log in to the PayPal Developer Dashboard with it; sandbox (test) and live apps are listed separately, and their credentials only work with the matching Mode in NXCart.

What	Sandbox mode	Live mode
Apps: client ID, secret and webhooks	Sandbox apps	Live apps
Test buyer and seller accounts	Sandbox accounts	not needed

1. Open Apps & Credentials (sandbox or live) and click Create App, or open an app you already have.
2. On the app's page, copy the Client ID and the Secret (click Show to see it).
3. On the same page, scroll to Webhooks, click Add Webhook, and paste the URL shown in Settings → Payments → PayPal in NXCart (it looks like this): https://yoursite.com/index.php?option=com_nxcart&task=webhook.paypal
4. Tick these event types and save:
   • CHECKOUT.ORDER.APPROVED (required)
   • PAYMENT.CAPTURE.COMPLETED (required)
   • PAYMENT.CAPTURE.DENIED and PAYMENT.CAPTURE.DECLINED (recommended: mark failed captures)
5. The new webhook appears in the list with its Webhook ID. Copy that ID (not the URL).
6. In NXCart, enter the client ID, secret and webhook ID in Settings → Payments → PayPal, choose the mode and checkout style, and enable PayPal.

PayPal's own guides: getting your credentials and webhooks.

Webhook behavior

• Webhooks transition orders from pending to paid/refunded states.
• Signature validation is mandatory for both gateways.
• Duplicate gateway notifications are handled safely, so orders are not charged or recorded twice.

Troubleshooting

Orders stuck in pending

Check:

1. Endpoint URL is reachable from the gateway.
2. Correct webhook secret/ID is saved.
3. Required events are enabled.
4. SSL and firewall configuration allow webhook POST requests.

Signature validation errors

• Re-copy Stripe signing secret (whsec_...).
• For PayPal, verify you stored the webhook ID, not endpoint URL.
• Ensure sandbox/live credentials match the active gateway mode.

Monitoring

• Review webhook attempts in Stripe/PayPal dashboards.
• Review component audit trail and logs in admin for failed webhook processing.