Skip to main content

Stripe

Stripe is a payment processor that handles credit card and alternative payment transactions for checkout and invoice payments. It uses the Stripe Payment Intents API to authorize, capture, and manage payments with support for manual capture workflows. Stores use this integration to securely process customer payments without handling sensitive card data directly.

How to set it up​

Where to find it: Admin → Payments → Stripe

When you'd use this: When you need to accept credit card payments at checkout or for paying open invoices using Stripe as your payment gateway.

What you need first:

  • An active Stripe account
  • Stripe API credentials (secret key)
  • Access to the Stripe dashboard to retrieve your API keys

Set it up:

  1. Log in to your Stripe account at stripe.com and navigate to Developers → API keys
  2. Copy your Secret key (starts with sk_)
  3. In CommerceBuild Admin, go to Payments and select Stripe
  4. Paste your Stripe Secret key into the authentication configuration
  5. Save the configuration and test with a small transaction to confirm connectivity

Configuration options​

The Stripe integration connects to https://api.stripe.com/v1 and does not expose configurable settings fields in the interface definition. Authentication is handled through API key headers configured at the connector level.

Using it day-to-day​

For checkout payments:

  1. Customer adds items to cart and proceeds to checkout
  2. Stripe payment form appears embedded in the checkout page
  3. Customer enters card details, which are tokenized by Stripe
  4. Payment is authorized but not captured (manual capture mode)
  5. Order is created with the payment in pre-authorized state
  6. Payment is captured when the order is fulfilled or invoiced

For invoice payments:

  1. Customer navigates to their open invoices in their account
  2. Customer selects one or more invoices to pay
  3. Stripe payment form appears for card entry
  4. Payment is authorized and captured immediately upon successful authorization
  5. Invoice is marked as paid and synced to the ERP system

For administrators:

  1. Pre-authorized payments appear in order management with expiry warnings
  2. Capture payments manually from the order detail page if needed
  3. View payment logs to troubleshoot authorization or capture issues
  4. Monitor payment metadata (order ID, username) in Stripe dashboard

Troubleshooting​

Payment iframe appears truncated when payment surcharge is enabled: Ensure that the container element for the payment iframe has sufficient height allocated. Payment surcharge displays may push content and cause clipping if the iframe height is fixed.

Pre-authorized payment expired before capture: Stripe payment authorizations typically expire after 7 days. Capture payments before the authorization window closes, or configure expiry warnings to flag orders requiring attention.

Invoice payment succeeded but not synced to ERP: Check that the postPayment webhook or callback executed successfully after capture. Review payment logs for the specific invoice to identify where the sync process failed.

Payment authorized twice for single invoice payment: This can occur if the authorize endpoint is called redundantly during the payment flow. Check for duplicate API calls in the payment logs and ensure the payment form is not being submitted multiple times.

Payment captured but order still shows as unpaid: Verify that the payment amount in Stripe matches the order total, and confirm that the payment response was processed correctly. Check payment logs for transformation errors between Stripe's response and the order system.