Looking to hire Laravel developers? Try LaraJobs

laravel-escrow maintained by itmosoft

Description
Escrow workflow records for Laravel applications, with integer minor-unit amounts, polymorphic parties, transaction-safe state transitions, and event history.
Last update
2026/11/17 13:26 (dev-main)
License
Links
Downloads
2

Comments
comments powered by Disqus

ITMOSOFT Laravel Escrow

A reusable escrow workflow foundation for Laravel applications. It tracks escrow obligations between polymorphic parties, linked to any polymorphic subject, with integer minor-unit amounts and transactional state transitions.

Requirements

  • PHP 8.3+
  • Laravel 12 or 13

Installation

composer require itmosoft/laravel-escrow
php artisan vendor:publish --tag=escrow-config
php artisan migrate

Laravel package discovery registers the service provider automatically.

Create an escrow

use ITMOSOFT\Escrow\Models\Escrow;

$escrow = Escrow::query()->create([
    'reference' => (string) Str::uuid(),
    'subject_type' => $order->getMorphClass(),
    'subject_id' => $order->getKey(),
    'payer_type' => $buyer->getMorphClass(),
    'payer_id' => $buyer->getKey(),
    'payee_type' => $seller->getMorphClass(),
    'payee_id' => $seller->getKey(),
    'amount_minor' => 12500, // e.g. USD 125.00; interpretation depends on currency
    'currency' => 'USD',
    'description' => 'Funds held until order acceptance.',
]);

amount_minor is a non-negative integer in the currency's minor unit. Do not pass a decimal or floating-point amount. Currency exponent rules vary; your application must convert and validate amounts using a currency-aware money library or its own trusted rules. The database enforces a 3-character currency code but does not validate ISO currency membership.

Workflow

$escrow->fund($paymentWebhookActor, 'Provider confirmed capture.');
$escrow->release($moderator, 'Buyer accepted delivery.');

// Or dispute and resolve:
$escrow->dispute($buyer, 'Item arrived damaged.');
$escrow->resolveDispute('refund', $moderator, 'Refund approved.');

Other transitions:

  • cancel() — pending only.
  • refund() — funded only.
  • dispute() — funded only.
  • resolveDispute('release'|'refund') — disputed only.

Statuses: pending, funded, disputed, released, refunded, cancelled.

State changes lock the escrow row inside a database transaction and append an event record in the same transaction. This helps prevent concurrent duplicate transitions. Database drivers that do not implement row-level locking (such as SQLite) do not provide production-grade concurrency guarantees.

Event history

Every successful state transition appends an EscrowEvent with event name, previous and next status, optional actor, and note. Treat this as application-level workflow history, not a tamper-proof audit log. Restrict database write access and add an external audit mechanism if regulatory or evidentiary immutability is required.

Party relationships

Add ITMOSOFT\Escrow\Concerns\HasEscrows to party models to expose payerEscrows() and payeeEscrows().

Critical boundaries

This package does not receive, custody, safeguard, transfer, or return real money. fund(), release(), and refund() only update your application's workflow records; they do not call a payment gateway or move funds. Your application must reconcile verified provider webhooks, perform actual payment/refund/payout operations, handle idempotency at provider boundaries, authorize every transition, and comply with applicable financial and escrow regulations. Do not represent this package alone as a regulated escrow service.

It also does not calculate fees, split payments, support partial releases/refunds, enforce settlement windows, or guarantee external payment execution.

Testing

composer install
composer test

License

MIT. See LICENSE.