Download the PHP package dalpras/payment-core without Composer

DalPraS Payment Core

Provider-agnostic PHP payment orchestration for checkout, completion, capture, refund, cancel and reconciliation.

The package is designed to keep application code independent from provider-specific identifiers while still supporting real payment lifecycles such as:

• Nexi Hosted Payment Page: orderId for checkout/completion, operationId for capture/refund/cancel
• PayPal Orders v2: order id for checkout/completion, capture id for refund, authorization id for delayed capture/void

Goals

• Keep business entities decoupled from payment SDKs and provider payloads.
• Persist a normalized Payment aggregate and immutable PaymentOperation audit log.
• Make browser returns, retries, provider API calls and reconciliation idempotent.
• Let provider packages return normalized metadata once, then let core reuse it automatically.
• Allow application adapters to provide business metadata without knowing provider lifecycle IDs.

Package status

This package contains:

• DTOs and value objects for checkout and provider operations
• PaymentProviderInterface
• PaymentManager
• provider registry
• payment repository contract with in-memory and Redis implementations
• idempotency contract and in-memory/cache/Redis implementations
• normalized Payment aggregate
• immutable PaymentOperation audit entries
• basic state machine

Concrete providers live in separate packages:

• dalpras/payment-paypal
• dalpras/payment-nexi

Installation

Namespace

Core lifecycle

Metadata model

Payment::$metadata is intentionally part of the orchestration model. It contains:

1. Application metadata supplied by your adapter.
2. Provider checkout metadata returned by providers.
3. Provider operation metadata returned by completion/capture/refund/cancel/sync.

Common normalized keys:

Request-level metadata always wins over stored metadata, so applications can still override the selected provider identifier when needed.

Important DTOs

CheckoutResponse

Providers return metadata here to persist identifiers discovered at checkout creation.

OperationResult

All operation results carry transactionIds and metadata. Provider packages should normalize useful IDs here instead of making the application parse raw.

PaymentManager enrichment

PaymentManager automatically enriches requests before invoking providers:

• completeCheckout() receives stored provider order/payment id when the browser return does not include it.
• refund() receives the latest stored capture_id, operation_id, or provider-specific equivalent.
• cancel() receives the latest stored operation_id or authorization_id.
• capture() receives the latest stored authorization_id or provider-specific equivalent.
• sync() receives the stored order/payment id.

This means application code can usually call:

Core will merge the stored Nexi operation_id before calling the Nexi provider.

Application adapter guidance

Application adapters should provide business data, not provider-generated IDs.

Good adapter metadata:

Provider packages then add provider metadata after API calls.

Redis payment repository

RedisPaymentRepository is the recommended production replacement for InMemoryPaymentRepository when you need a lightweight cross-request repository for redirect-based providers.

It stores the Payment aggregate and related PaymentOperation entries in Redis using PHP serialization and a configurable TTL. This lets PaymentManager recover provider metadata after the customer returns from Nexi/PayPal:

Example Symfony wiring:

Use a TTL long enough for abandoned browser sessions and delayed redirects. 86400 seconds, or 24 hours, is a practical default.

Redis should still be treated as active-flow storage. For final accounting, support, reporting and later refunds/cancels, persist important provider metadata in your own durable entity/table, for example OrderEntity.paymentMetadata.

Persistence notes

If you replace InMemoryPaymentRepository with a durable database repository, persist at least:

Payment

• reference
• merchant reference
• provider code
• intent
• status
• customer snapshot
• line items snapshot
• amount breakdown
• provider payment id
• provider token
• idempotency key
• correlation id
• metadata JSON
• created/updated timestamps

PaymentOperation

• payment reference
• operation type
• status
• provider payment id
• transaction ids JSON
• metadata JSON
• raw payload JSON
• message
• created timestamp

The new metadata and transaction id fields are important. Without them, automatic refund/cancel/capture enrichment will lose provider lifecycle identifiers.

Basic usage

Production-style repository example:

Testing

Run syntax checks:

Run PHPUnit after installing development dependencies:

License

MIT