README

Vendor-agnostic abstractions for building fiat and crypto gateway integrations with a single reusable contract layer.

Purpose

Shared contracts and capabilities for gateway services.
Immutable data objects for request and response exchange.
Generic validation and exception primitives.
No provider-specific business logic.

Installation

composer require rublex/laravel-core-gateway

Contracts Overview

Common

Rublex\CoreGateway\Contracts\Common\GatewayInterface
- code(): string
- type(): GatewayType

Payment capabilities

Rublex\CoreGateway\Contracts\Payment\InitiatesPaymentInterface
Rublex\CoreGateway\Contracts\Payment\VerifiesPaymentInterface
Rublex\CoreGateway\Contracts\Payment\QueriesPaymentStatusInterface (optional)
Rublex\CoreGateway\Contracts\Payment\HandlesCallbackInterface (optional)

Use only the capabilities supported by a specific provider package.

Dynamic Meta Usage

DynamicDataBag stores extensible payload fields without adding provider-specific fields to core DTOs.

use Rublex\CoreGateway\Data\DynamicDataBag;

$meta = new DynamicDataBag([
    'customer' => [
        'email' => 'customer@example.com',
    ],
    'provider' => [
        'channel' => 'card',
    ],
]);

$email = $meta->requireString('customer.email');
$meta2 = $meta->with('provider.traceId', 'trace-123');

Fiat/Crypto Readiness

Gateway category is declared via GatewayType (FIAT or CRYPTO).
Lifecycle result state is standardized via PaymentStatus.
Provider-specific fields remain in meta/raw bags, so crypto providers can reuse the same DTOs.

Example Implementation

use Rublex\CoreGateway\Contracts\Common\GatewayInterface;
use Rublex\CoreGateway\Contracts\Payment\InitiatesPaymentInterface;
use Rublex\CoreGateway\Data\PaymentInitResultData;
use Rublex\CoreGateway\Data\PaymentRequestData;
use Rublex\CoreGateway\Enums\GatewayType;
use Rublex\CoreGateway\Enums\PaymentStatus;

final class ExampleGateway implements GatewayInterface, InitiatesPaymentInterface
{
    public function code(): string
    {
        return 'example';
    }

    public function type(): GatewayType
    {
        return GatewayType::FIAT;
    }

    public function initiate(PaymentRequestData $request): PaymentInitResultData
    {
        // map provider response into the core result shape
        return new PaymentInitResultData(PaymentStatus::PENDING);
    }
}

Migration Notes

Previous releases exposed only package metadata.
v1.0.0 now includes reusable contracts, enums, exceptions, and DTOs for all gateway packages.
Existing provider packages can keep their public methods and map them to the new contract methods internally.

License

This package is open-sourced software licensed under the MIT license.

rublex / laravel-core-gateway

Maintainers

Package info

Statistics

Security