README

The canonical, framework-agnostic business logic engine for Wallee payment integrations.

This library abstracts the complexity of the Wallee SDK and provides a standardized, robust implementation of payment flows. It is designed to be used as a core dependency by platform-specific plugins (Magento, WooCommerce, Shopware, etc.), decoupling business logic from platform infrastructure.

Core Philosophy

The goal of this project is to centralize all payment business logic into a single, reusable library, decoupling it from the specific constraints of platforms like Magento or WooCommerce.

Instead of duplicating complex logic across different shop systems, plugin-core implements the payment workflows once, using pure PHP. This shifts the role of the shop-specific plugin:

• Plugin Core: Implements the business logic, manages state machines, and handles all API interactions via the SDK.
• Shop Plugin: Acts as an adapter. It interchanges data between the shop and the Core, handles database persistence, manages configuration, and integrates into the shop's frontend/backend events.

Key Architectural Benefits

• Pure PHP: Framework-agnostic code that runs anywhere PHP runs.
• Minimal Dependencies: Depends only on the official wallee/php-sdk, making it lightweight and easy to port to any environment.
• Type Safety: Written with strict typing to catch errors early.
• Testability: Designed for 100% unit test coverage with isolated components.
• PSR Standards: Fully compliant with PSR-3 (Logging) and other standard interfaces.
• Contract-Driven: Clear Interfaces and Abstract Base Classes guide developers to implement the necessary platform-specific adapters correctly.

Key Features

The library is divided into major functional components, each designed for robustness and ease of integration.

1. Checkout Engine

The core of the payment flow. Handles transaction creation and management with a sophisticated "upsert" strategy, ensuring seamless navigation without duplicate charges.

• Read Checkout Docs

2. Webhook Processor

The engine for handling asynchronous events from the Wallee Portal. It's built for scale and high concurrency.

• Read Webhook Processor Docs

3. Webhook Management

Tools for programmatically managing webhooks in the Wallee Portal, including URL creation and Listener setup.

• Read Webhook Management Docs

4. Transaction Completion (Capture & Void)

Manage the final stages of the transaction lifecycle. Finalize payments (Capture) or cancel them (Void) with dedicated service handlers.

• Read Completion Docs

5. Recurring Payments

Enables Merchant Initiated Transactions (MIT) for seamless subscription renewals and unscheduled subsequent charges using saved tokens.

• Read Recurring Docs

6. Refund Management

Support for full and partial refunds. Includes precise line-item logic and validation to prevent over-refunding.

• Read Refund Docs

7. Document Management

Retrieve official PDF documents (Invoices, Packing Slips, Credit Notes) directly from the Wallee Portal for the merchants.

• Read Document Docs

8. Payment Method Service

A centralized service to fetch available payment method configurations from the Wallee Portal, ensuring the shop systems have an up-to-date view of available payment methods.

• Read Payment Method Docs

Documentation

For a detailed look at how to implement each module, refer to the guides in the docs/ directory:

• Checkout & Transaction Flow: Handling the initial payment process.
• Webhook Integration: Master guide for both Processing and Management.
• Webhook Processor: Detailed guide for handling incoming notifications.
• Webhook Management: Programmatic setup of listeners in the Wallee Portal.
• Transaction Completion: Capturing and voiding authorized transactions.
• Recurring Charges: Implementing tokenized subsequent payments.
• Refund Process: Managing customer returns and credit notes.
• Official Documents: Downloading invoices and other PDF assets.
• Payment Method Service: Retrieving and synchronizing payment methods configurations.

Examples

For a runnable example for each of the modules, refer to the examples subdirectories in each of the module directories.

• Checkout & Transaction Flow: Handling the initial payment process.
• Webhook Processor: Simulating state transitions and concurrent processing.
• Webhook Management: Lifecycle management (CLI scripts).
• Transaction Completion: Capturing and voiding authorized transactions.
• Recurring Charges: Implementing tokenized subsequent payments.
• Refund Process: Managing customer returns and credit notes.
• Official Documents: Downloading invoices and other PDF assets.
• Payment Method Service: Retrieving and synchronizing payment methods configurations.

Installation

composer require wallee/plugin-core

Unit Tests

You can run the test suite to verify the library's behavior.

composer test

License

Apache License. See [LICENSE.txt].