README

Curbstone Payments for Shopware 6

Introduction

The Curbstone Payments Plugin integrates the Curbstone payment gateway into your Shopware 6 store, enabling secure credit card processing through Curbstone's hosted Payment Landing Page (PLP) with PCI-aware UX patterns designed for high-conversion checkouts.

The plugin supports authorize-only and immediate authorize-and-capture flows, saved card management (vaulting), and automatic refunds and voids driven by Shopware's own order transaction states. All gateway communication is handled server-side, keeping sensitive card data off your servers.

Key Features

Credit Card Processing

Accepts credit card payments via Curbstone's hosted Payment Landing Page (PLP), redirecting card data handling to Curbstone's PCI-compliant environment.

Authorize & Capture Flow

Choose between Authorize Only (capture later, e.g. via ERP or manual capture) or Authorize & Capture (immediate charge) per Sales Channel.

Inline Pre-Authorization (0.00 Auth)

On the checkout confirmation page, a Curbstone-hosted iframe collects and tokenizes card details via a zero-amount pre-authorization, keeping card data entirely off your servers before the order is placed.

Saved Cards (Vault)

Customers can save cards during checkout or from their account for faster repeat purchases. Saved cards are stored as vaulted tokens (MFUKEY/MFKEYP) against the customer's account and can be managed from the Account > Saved Cards page, which displays a paginated grid (5 cards per page).

Automatic Refunds

When an order transaction moves to Refunded or Refunded (partially) in Shopware, the plugin automatically sends a refund request to Curbstone and stores the refund metadata on the transaction.

Void Authorization

When an authorized (not yet captured) transaction is cancelled, the plugin sends a void request to Curbstone to release the authorization hold.

Multi-Environment Support

Switch between Sandbox (c3sbx.net) and Live (c3plp.net) environments from the Admin config — no code changes required.

TLS Verification

TLS certificate validation is enforced by default. Can be overridden via the Admin toggle or the CURBSTONE_HTTP_VERIFY environment variable for controlled environments.

Transaction Metadata

All gateway request and response payloads (sanitized of sensitive data) are stored as order transaction custom fields for full traceability in the Admin order view.

Comprehensive Logging

Detailed logging of all payment, refund, void, and pre-authorization events for troubleshooting and audit purposes. Sensitive fields (card numbers, CVV, tokens) are redacted before being written to logs.

Saved-Card Metadata Backfill (CLI)

A console command, curbstone:backfill-saved-card-metadata, normalizes and backfills vaulted card metadata for existing customers. Supports --dry-run (preview without persisting changes) and --limit (batch size, default 250).

Extensibility Hook

A CurbstonePaymentCompletedEvent is dispatched after every successful charge, letting other plugins or custom code react to completed Curbstone payments without modifying the core plugin.

Compatibility

✅ Shopware 6.7.x
✅ PHP 8.1+

Get Started

Installation & Activation

GitHub

Clone the plugin into your Shopware plugins directory:

git clone https://github.com/solution25com/curbstone-payment-shopware-6-solution25.git

Install the Plugin in Shopware 6
- Log in to your Shopware 6 Administration panel.
- Navigate to Extensions > My Extensions.
- Locate the plugin and click Install.
Activate the Plugin
- After installation, click Activate to enable the plugin.
- Run the following commands from your Shopware root:

bin/console plugin:refresh
bin/console plugin:install --activate Curbstone
bin/console cache:clear

Build Storefront Assets

bin/console bundle:dump
bin/build-storefront.sh
bin/console cache:clear

Verify Installation
- After activation, you will see Curbstone Payments in the list of installed plugins.
- The plugin name, version, and installation date should appear.

Plugin Configuration

After installing the plugin, configure your Curbstone credentials and options through the Shopware Administration panel.

Accessing the Configuration

Go to Settings > Curbstone Payments
Select the Sales Channel you want to configure
Set the following fields:

General Settings

Field	Description
Sandbox Mode	Enable to use Curbstone sandbox endpoints (`c3sbx.net`). Disable for production (`c3plp.net`)
Verify TLS Certificates	Validates the Curbstone server certificate on all HTTPS calls (recommended). Can also be controlled via the `CURBSTONE_HTTP_VERIFY` environment variable

API Credentials

Field	Description
Merchant DSI Key (MFDSIK)	Your Curbstone Merchant DSI key. Currently stored for forward compatibility — see Roadmap
Customer ID (MFCUST)	Your Curbstone Customer ID
Merchant Code (MFMRCH)	Your Curbstone Merchant Code

Payment Settings

Field	Description
Auth / Capture Flow	`Auth Only` — authorizes the card and defers capture. `Auth & Capture` — authorizes and captures immediately

How It Works

1. Card Pre-Authorization at Checkout

On the checkout confirmation page, a Curbstone-hosted iframe is rendered inline inside the payment section. The customer enters their card details directly into Curbstone's secure environment. A zero-amount pre-authorization is sent to Curbstone's PLP endpoint, which returns a payment token (MFUKEY/MFKEYP) stored in the session — no raw card data ever touches your server.

2. Payment on Order Placement

When the customer submits the order, Shopware triggers the payment handler. The plugin resolves the card token (either from the session pre-auth or from a selected saved card) and sends a real charge request to Curbstone's PLP endpoint with the full order amount and billing details. Whether the request is sent as a pre-authorization (PA) or an immediate authorize-and-capture (SA) is determined by the configured Auth/Capture flow.

3. Saved Cards

If the customer checks Save card during checkout (or adds a card from their account) and the pre-authorization succeeds, Curbstone returns a vaulted card token along with the card's last 4 digits, brand, and expiry. This is stored against the customer's Shopware account. On future checkouts, the customer can select a saved card from a paginated grid — bypassing the iframe entirely.

4. Refunds

When an order transaction is moved to Refunded or Refunded (partially) in Shopware, the plugin reads the stored token and session metadata from the transaction's custom fields and sends a refund request to Curbstone. The refund response is stored back on the transaction for audit purposes.

5. Void

When an authorized transaction is cancelled before capture, the plugin sends a void request to Curbstone to release the authorization hold. The void response is stored on the transaction's custom fields.

Saved Cards — Customer Account

Customers can manage their vaulted cards via Account > Saved Cards in the storefront. From this page they can:

View saved cards (brand, last 4 digits, expiry) in a paginated grid
Delete individual saved cards
Select a saved card at checkout without re-entering card details

Roadmap / Known Limitations

The following items are present in configuration as forward-compatible fields but are not yet functional in this release. They're listed here so integrators don't assume behavior that isn't implemented yet:

DSI (Direct Server Integration): The Merchant DSI Key field is stored, but all requests (charge, pre-auth, refund, void) currently route through the PLP endpoint. A true server-to-server DSI request path is not yet wired up.
PLP presentation mode: The checkout iframe is always rendered in embedded mode; there is no redirect-based full-page fallback yet.
High-value order deferral / ERP hand-off: Not implemented in this release — all orders are processed through the standard authorize/capture flow regardless of amount.
Configurable retry/backoff: Not implemented in this release — gateway requests are sent once, with a fixed 10-second timeout, and no automatic retry on transient failures.

Uninstallation

bin/console plugin:deactivate Curbstone
bin/console plugin:uninstall Curbstone
bin/console cache:clear

License

MIT — see LICENSE for details.

Support

For questions or issues, please open a GitHub Issue or contact Solution25.

solution25 / curbstone

Maintainers

Package info

Statistics

Security