README

Fintech Utils — a lightweight, strict, and extensible PHP library for modern fintech projects.
It provides a set of Value Objects, Validation Rules, and DTOs for safe and consistent handling of banking, cryptocurrency, and KYC (Know Your Customer) data.

Laravel friendly.

Installation

composer require zxc0zxc0zxc/fintech-utils

Features

Cryptocurrency

• Validation rules for major blockchain addresses:
  • Bitcoin (BTC) — BitcoinWalletAddress
  • Ethereum (ETH) — EthereumWalletAddress
  • Dash (DASH) — DashWalletAddress
  • Monero (XMR) — MoneroWalletAddress
  • Solana (SOL) — SolanaWalletAddress
• CurrencySymbolRule and Amount Value Object

Banking

• Validation for:
  • IBAN
  • CardNumber, CardCvv, CardExpiryDate
• Immutable Value Objects and DTOs:
  • CardNumber, CardCvv, CardExpiryDate
  • CardDto - combines all card-related VOs

Base KYC

• RussianInn (INN)
• UsSnn (SSN)
• Common interface PersonalIdInterface

Unified Payment provider interface

Use the PaymentProviderInterface and RefundablePaymentProviderInterface to define your own concrete payment provider classes. These interfaces allow you to standardize how different payment gateways (e.g., Stripe, YooKassa, PayPal) are integrated into your system.

Later, you can use these implementations inside a payment provider factory, which dynamically selects the appropriate provider based on your own business rules — for example:

• the user’s region or currency,
• the minimum or maximum allowed payment amount,

or specific provider preferences.

Helpers

• AmountHelper helps formatting bcmath values to readable format
• EncryptionHelper helps you easily encrypt or decrypt data via AES-256-GCM

Example Usage

In a Laravel FormRequest

use Zxc0zxc0zxc\FintechUtils\Rules\Banking\CardNumberRule;
use Zxc0zxc0zxc\FintechUtils\Rules\Banking\CardCvvRule;
use Zxc0zxc0zxc\FintechUtils\Rules\Banking\CardExpiryDateRule;
use Zxc0zxc0zxc\FintechUtils\Rules\Crypto\BitcoinWalletAddress;
use Zxc0zxc0zxc\FintechUtils\Rules\Crypto\EthereumWalletAddress;
use Zxc0zxc0zxc\FintechUtils\Rules\Crypto\SolanaWalletAddress;
use Zxc0zxc0zxc\FintechUtils\Rules\Kyc\RussianInn;

public function rules(): array
{
    return [
        'card_number' => ['required', new CardNumberRule()],
        'card_expiry' => ['required', new CardExpiryDateRule()],
        'card_cvv'    => ['required', new CardCvvRule()],
        'inn'         => ['required', new RussianInn()],
        'btc_address' => ['required', new BitcoinWalletAddress()],
        'eth_address' => ['required', new EthereumWalletAddress()],
        'sol_address' => ['required', new SolanaWalletAddress()],
    ];
}

Working with cards via DTO and Value Objects

use Zxc0zxc0zxc\FintechUtils\Dto\CardDto;
use Zxc0zxc0zxc\FintechUtils\ValueObjects\CardNumber;
use Zxc0zxc0zxc\FintechUtils\ValueObjects\CardCvv;
use Zxc0zxc0zxc\FintechUtils\ValueObjects\CardExpiryDate;

$card = new CardDto(
    new CardNumber('4111 1111 1111 1111'),
    new CardExpiryDate('12/26'),
    new CardCvv('123')
);

echo $card->getBrand();         // Visa
echo $card->getMaskedNumber();  // ************1111
echo $card;                     // [Visa] ************1111 exp:12/26 cvv:***

KYC Example

use Zxc0zxc0zxc\FintechUtils\ValueObjects\Kyc\RussianInn;

$inn = new RussianInn('500100732259');
echo $inn->getMasked(); // ********2259

IBAN Example

use Zxc0zxc0zxc\FintechUtils\ValueObjects\Iban;

$iban = new Iban('GB82 WEST 1234 5698 7654 32');

echo $iban->getCountry();     // GB
echo $iban->getFormatted();   // GB82 WEST 1234 5698 7654 32

Crypto Validation Example

use Zxc0zxc0zxc\FintechUtils\Rules\Crypto\BitcoinWalletAddress;

$request->validate([
    'wallet' => ['required', 'string', new BitcoinWalletAddress()],
]);

// Valid examples:
// 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa
// 3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy
// bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq

Eloquent casts example

class Customer extends Model
{
    protected $casts = [
        'iban' => IbanCast::class,
        'card_number' => CardNumberCast::class,
        'inn' => RussianInn::class,
    ];
}

// ---

$customer = Customer::find(1);

// Returns VO instead of string
$iban = $customer->iban; 
echo $iban->getCountry(); // GB

// Assign using either string or VO
$customer->iban = new Iban('GB82 WEST 1234 5698 7654 32');
$customer->save();

// Or assign raw string — it will be cast automatically
$customer->iban = 'GB82 WEST 1234 5698 7654 32';

Unified PaymentProvider example

class YooKassaProvider implements PaymentProviderInterface
{
    public function __construct(
        private YooKassaClient $client, // Your client to implement
        private string $webhookSecret
    ) {}

    public function getProviderName(): string
    {
        return 'yookassa';
    }

    public function createPayment(PaymentRequest $request): PaymentResponse
    {
        // An example
        $response = $this->client->createPayment([
            'amount' => [
                'value' => number_format($request->amount / 100, 2, '.', ''),
                'currency' => $request->currency,
            ],
            'confirmation' => [
                'type' => 'redirect',
                'return_url' => $request->returnUrl,
            ],
            'description' => $request->description,
            'metadata' => $request->metadata,
        ], uniqid('', true));

        return new PaymentResponse(
            $response->getId(),
            PaymentStatus::from($response->getStatus()),
            $response->getConfirmation()->getConfirmationUrl(),
            $response->toArray()
        );
    }

    public function getPaymentStatus(string $paymentId): PaymentStatus
    {
        $payment = $this->client->getPaymentInfo($paymentId);
        return PaymentStatus::from($payment->getStatus());
    }

    public function verifyWebhookSignature(string $payload, string $signature): bool
    {
        // Verifying webhook
    }

    public function handleWebhook(array $payload): PaymentResponse
    {
        // Handling webhook
    }
}

Contributing

Pull requests are welcome!

If you’re using Fintech Utils in production — drop a star on the repo and share feedback.