Stripe

Prerequisites#

• A Stripe account at dashboard.stripe.com
• Your Opterius Commerce installation accessible over HTTPS (required for Stripe Elements and webhooks)

Configuration#

Go to Admin → Settings → Payment Gateways → Stripe and fill in:

Click Save. Enable the Stripe toggle. Stripe is now active.

Getting Your API Keys#

1. Go to dashboard.stripe.com
2. Click Developers in the top navigation
3. Click API keys
4. Copy the Publishable key and Secret key

[!WARNING] Keep your Secret Key private. It must never be committed to version control or exposed in client-side code. Only the Publishable Key is safe to use in JavaScript.

Setting Up the Webhook#

Commerce needs Stripe to send payment confirmation events. Without a webhook, invoices will not be marked paid after a successful charge.

1. In Stripe Dashboard, go to Developers → Webhooks
2. Click Add endpoint
3. Enter your webhook URL: https://yourdomain.com/webhooks/stripe
4. Under Events to send, select:
   • payment_intent.succeeded
   • payment_intent.payment_failed
   • charge.refunded
5. Click Add endpoint
6. Copy the Signing secret (starts with whsec_) and paste it into the Webhook Secret field in Commerce

[!IMPORTANT] The Webhook Secret is required for Commerce to verify that webhook events genuinely come from Stripe and have not been tampered with. Without it, Commerce will reject all incoming webhook events.

How Stripe Payments Work#

Commerce uses Stripe Elements — an embeddable card form rendered directly on the invoice payment page. The flow:

1. Stripe Elements renders the card input in a secure iframe
2. The client enters their card details
3. Stripe tokenises the card in the browser — raw card numbers never reach your server
4. Commerce creates a PaymentIntent server-side for the invoice amount
5. Stripe confirms the intent (including any 3DS2 authentication if required)
6. Stripe fires payment_intent.succeeded webhook
7. Commerce marks the invoice paid and sends the receipt email

Saved Payment Methods#

Clients can save their card at checkout by checking "Save card for future payments". Saved cards are stored in Stripe (as PaymentMethod objects) and referenced in Commerce by a token — full card data is never stored locally.

Managing saved cards:

• Clients: Client → Billing → Saved Cards — list and delete saved cards
• Admins: Admin → Clients → [client] → Billing — view saved cards

Auto-charge on renewal: If a client has a saved card and Settings → Billing → Auto-charge saved cards is enabled, Commerce automatically charges the saved card when a renewal invoice is generated. No client action required.

Test Mode#

To test without processing real payments:

1. Use your Stripe test keys (pk_test_... and sk_test_...)
2. In Stripe Dashboard, create a test webhook endpoint and use its signing secret
3. Use Stripe's test card numbers:

Expiry: any future date. CVC: any 3 digits. ZIP: any 5 digits.

[!TIP] Use the Stripe CLI to forward webhook events to your local development environment: stripe listen --forward-to localhost:8000/webhooks/stripe

Refunds#

Stripe refunds are processed automatically through the Commerce refund interface (Admin → Invoice → Payments → Refund). Partial and full refunds are supported. The refund appears in Stripe Dashboard under the original payment.

Related Topics#

• Payment Gateways Overview
• Paying an Invoice (Client)
• Credit Notes & Refunds