README

Provider-agnostic payment foundation with Smart-Contract Architecture for e-commerce platforms.

Overview

Payment Base is a universal, event-driven payment library that enables seamless integration of multiple payment providers (Stripe, PayPal, Unzer, Adyen, etc.) with 95% code reusability. Built on the Smart-Contract Architecture pattern where "Place Order" creates a contract, not an order—orders are created only when conditions are fulfilled.

Key Benefits

95% Reusability - Provider-agnostic core, only ~5% provider-specific code needed
70% Faster Integration - New payment providers in 35-50 hours vs 120-160 hours
Event-Driven - All business logic triggered via PSR-14 domain events
Smart Contracts - Two-step authorization with condition-based fulfillment
Type-Safe - PHP 8.1+ with strict typing and PHPStan level 6 compliance

Installation

composer require oxid-esales/payment-base

Migrations

oxid-esales/oxid-shop-doctrine-migration-wrapper is required to run migrations.

composer require oxid-esales/oxid-shop-doctrine-migration-wrapper

Migrations are running automatically on composer install/update via ComposerPlugin ./src/Composer/MigrationPlugin.php

composer update oxid-esales/payment-base

Force Migrations

To run migrations manually use:

./bin/run-migrations.sh

Requirements

PHP 8.1+
PSR-3 Logger (psr/log ^2.0 || ^3.0)
PSR-14 Event Dispatcher (psr/event-dispatcher ^1.0)
Doctrine DBAL ^2.13 || ^3.0

Smart-Contract Architecture

Traditional payment flow creates orders immediately, then handles payment failures with complex rollback logic. The Smart-Contract pattern reverses this:

Traditional:  User clicks "Order" → Order created → Payment → Update order on failure
Smart-Contract: User clicks "Order" → Contract created → Conditions resolved → Order created

Contract Lifecycle

DRAFT → PENDING → READY_TO_COMMIT → COMMITTED → FULFILLED
                                  ↘ CANCELLED / EXPIRED / FAILED

States:

DRAFT - Contract initialized, basket captured
PENDING - Awaiting conditions (payment auth, fraud check, stock)
READY_TO_COMMIT - All conditions fulfilled
COMMITTED - Order created in shop system
FULFILLED - Payment captured, process complete

Contract Conditions

Contracts track multiple conditions that must be satisfied:

$contract->addCondition(new ContractCondition('payment_authorized'));
$contract->addCondition(new ContractCondition('fraud_check_passed'));
$contract->addCondition(new ContractCondition('stock_reserved'));

// Conditions fulfilled asynchronously via webhooks/events
$contract->fulfillCondition('payment_authorized');

Architecture

┌─────────────────────────────────────────────────────────────┐
│  CONTROLLER LAYER - Thin controllers, emit events only      │
└────────────────────────────┬────────────────────────────────┘
                             │ emits
┌────────────────────────────▼────────────────────────────────┐
│  EVENT SYSTEM - Domain Events (PSR-14 compatible)           │
└────────────────────────────┬────────────────────────────────┘
                             │ triggers
┌────────────────────────────▼────────────────────────────────┐
│  SERVICE LAYER - ContractService, PaymentService            │
└────────────────────────────┬────────────────────────────────┘
                             │ uses
┌────────────────────────────▼────────────────────────────────┐
│  ADAPTER LAYER - PaymentAdapterInterface (provider-agnostic)│
└────────────────────────────┬────────────────────────────────┘
                             │ persists
┌────────────────────────────▼────────────────────────────────┐
│  REPOSITORY LAYER - ContractRepository, TransactionRepository│
└─────────────────────────────────────────────────────────────┘

Directory Structure

src/
├── Adapter/            # Payment provider abstraction
│   ├── PaymentAdapterInterface.php
│   ├── Dto/            # Data transfer objects
│   └── Response/       # Standardized adapter responses
├── Contract/           # Smart-contract domain
│   ├── PaymentContract.php        # Aggregate root
│   ├── ContractCondition.php      # Condition entity
│   └── BasketSnapshot.php         # Immutable basket value object
├── Controller/         # Base controllers
│   └── Webhook/        # Webhook handling base classes
├── EventSystem/        # Event-driven architecture
│   ├── Event/          # Domain events
│   │   ├── Contract/   # Contract lifecycle events
│   │   └── Payment/    # Payment lifecycle events
│   ├── EventDispatcher.php
│   └── EventListenerProvider.php
├── GraphQL/            # Headless API support
├── Middleware/         # Request/response middleware
├── Model/              # Domain models
├── Order/              # Order integration
├── Repository/         # Data access layer
├── Service/            # Business logic services
│   ├── ContractService.php
│   ├── CheckoutOrchestrator.php
│   └── Idempotency/    # Duplicate payment prevention
├── Traits/             # Reusable traits
├── Transaction/        # Transaction tracking
└── Webhook/            # Webhook processing

Usage

Implementing a Payment Provider

Create an adapter implementing PaymentAdapterInterface:

use OxidEsales\PaymentBase\Adapter\PaymentAdapterInterface;
use OxidEsales\PaymentBase\Adapter\Response\AuthorizationResponse;

class StripeAdapter implements PaymentAdapterInterface
{
    public function authorize(PaymentRequest $request): AuthorizationResponse
    {
        $paymentIntent = $this->stripeClient->paymentIntents->create([
            'amount' => $request->getAmount(),
            'currency' => $request->getCurrency(),
            'capture_method' => 'manual',
        ]);

        return new AuthorizationResponse(
            success: true,
            transactionId: $paymentIntent->id,
            providerReference: $paymentIntent->client_secret
        );
    }

    public function capture(CaptureRequest $request): CaptureResponse
    {
        // Capture implementation
    }

    public function refund(RefundRequest $request): RefundResponse
    {
        // Refund implementation
    }
}

Creating a Payment Contract

use OxidEsales\PaymentBase\Contract\PaymentContract;
use OxidEsales\PaymentBase\Contract\BasketSnapshot;

// Capture basket state immutably
$basketSnapshot = BasketSnapshot::fromBasket($basket);

// Create contract
$contract = new PaymentContract(
    shopId: $shopId,
    userId: $userId,
    basketSnapshot: $basketSnapshot
);

// Add conditions that must be fulfilled
$contract->addCondition('payment_authorized');
$contract->addCondition('fraud_check_passed');

// Persist contract
$contractRepository->save($contract);

Handling Webhooks

use OxidEsales\PaymentBase\Webhook\AbstractWebhookHandler;

class StripeWebhookHandler extends AbstractWebhookHandler
{
    protected function getTransactionIdFromPayload(array $payload): string
    {
        return $payload['data']['object']['id'];
    }

    protected function getEventTypeFromPayload(array $payload): string
    {
        return $payload['type'];
    }

    protected function processPaymentSucceeded(array $payload): void
    {
        $contract = $this->contractRepository->findByProviderReference(
            $payload['data']['object']['id']
        );

        $contract->fulfillCondition('payment_authorized');
        $this->contractRepository->save($contract);

        $this->eventDispatcher->dispatch(
            new PaymentAuthorizedEvent($contract)
        );
    }
}

Event Handling

use OxidEsales\PaymentBase\EventSystem\Event\Contract\ContractReadyToCommitEvent;
use OxidEsales\PaymentBase\EventSystem\SubscriberInterface;

class OrderCreationSubscriber implements SubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            ContractReadyToCommitEvent::class => 'onContractReady',
        ];
    }

    public function onContractReady(ContractReadyToCommitEvent $event): void
    {
        $contract = $event->getContract();

        // Create order from contract's basket snapshot
        $order = $this->orderService->createFromContract($contract);

        $contract->commit($order->getId());
        $this->contractRepository->save($contract);
    }
}

Domain Events

Contract Events

Event	Trigger
`ContractCreatedEvent`	New contract initialized
`ContractTransitionedToPendingEvent`	Contract submitted for processing
`ContractConditionFulfilledEvent`	A condition was satisfied
`ContractReadyToCommitEvent`	All conditions fulfilled
`ContractCommittedEvent`	Order created from contract
`ContractFulfilledEvent`	Payment captured, process complete
`ContractCancelledEvent`	Contract cancelled by user/system
`ContractExpiredEvent`	Contract timed out

Payment Events

Event	Trigger
`PaymentInitiatedEvent`	User starts checkout
`PaymentAuthorizedEvent`	Funds reserved
`PaymentCapturedEvent`	Funds transferred
`PaymentRefundedEvent`	Refund processed
`PaymentFailedEvent`	Payment declined
`WebhookReceivedEvent`	Provider webhook received

Development

Running Tests

# All tests
vendor/bin/phpunit

# Unit tests only
vendor/bin/phpunit --testsuite Unit

# Integration tests only
vendor/bin/phpunit --testsuite Integration

# Single test file
vendor/bin/phpunit tests/Unit/Contract/PaymentContractTest.php

# Single test method
vendor/bin/phpunit --filter testContractTransitionsToPending

Static Analysis

vendor/bin/phpstan analyse

Supported Providers

The Payment Base is designed to support any payment provider with REST/SOAP API and webhooks:

Stripe
PayPal
Amazon Pay
Unzer
TeleCash
Adyen
Mollie
Klarna
Braintree
Square

License

proprietary - See LICENSE for details.

Credits

Developed by OXID eSales AG with AI assistance from Claude (Anthropic).

oxid-esales / payment-base

Maintainers

Package info

Statistics

Security