BTRL (Banca Transilvania iPay)

Description

BTRL integrates Laravel Enso payment flows with the Banca Transilvania iPay API.

The package stores the remote credentials, exposes the settings API used by the admin UI, registers payment intents against the Banca Transilvania gateway, persists card transaction attempts locally, and refreshes transaction status from the remote platform.

It is intended for private deployments that need Banca Transilvania iPay as an online card-payment gateway.

Installation

This is a proprietary package distributed through the private Enso registry or a private path repository.

Run the package migrations after installation:

php artisan migrate

Then configure the integration from the BTRL settings screen. The settings record stores:

• API endpoint URLs
• account credentials (username, password)
• enabled flag

Optional config publish:

php artisan vendor:publish --tag=btrl-config

Config file: config/enso/btrl.php

return [
    'settingsId' => env('BTRL_SETTINGS_ID', 1),
];

Features

• Settings API for enabling the integration and storing credentials.
• Register service for creating remote payment orders and returning the hosted formUrl.
• Status service for synchronizing an existing CardTransaction with the remote gateway response.
• Dedicated CardTransaction model with enum-casted local status, BT status, action code, request payload, and raw response data.
• Tradable contract for application-specific payment subjects that can be registered with the gateway.
• Standardized enums for transaction status, BT transaction status, action code, endpoint selection, and currency handling.
• API and transaction exception handling.

Usage

Enable the integration from the settings form before using the payment flow.

Transactions are initiated and verified through the registered integration services.

To register a payment:

use LaravelEnso\Btrl\Services\Register;
use LaravelEnso\Btrl\Services\TestTransaction;
use LaravelEnso\Btrl\Data\Address;
use LaravelEnso\Btrl\Data\Customer;

$address = new Address('642', 'Bucuresti', 'Strada Exemplu 1');
$customer = new Customer('client@example.com', '0700000000', $address, $address);
$registration = (new Register($customer, new TestTransaction()))->handle();
$paymentUrl = $registration->formUrl;

Register expects:

• a LaravelEnso\Btrl\Data\Customer
• a class implementing LaravelEnso\Btrl\Contracts\Tradable

Tradable::amount() returns the amount in the currency's major unit. The package converts it to the minor unit expected by BTRL when building the API payload.

The service creates a bt_card_transactions row before the remote call, stores the request payload, then returns a registration result containing the hosted form URL and the persisted transaction.

Both Register and Status accept an optional Settings instance. When it is omitted, the services use Settings::current(). Applications may inject a context-specific, unsaved settings copy without changing the package-level fallback:

$contextualSettings = Settings::current()->replicate()->fill([
    'username' => $username,
    'password' => $password,
]);

$registration = (new Register(
    $customer,
    $transaction,
    $contextualSettings,
))->handle();

To refresh a transaction:

use LaravelEnso\Btrl\Models\CardTransaction;
use LaravelEnso\Btrl\Services\Status;

(new Status(CardTransaction::find($id)))->handle();

The package exposes the following core service classes:

• LaravelEnso\Btrl\Services\Register
• LaravelEnso\Btrl\Services\Status
• LaravelEnso\Btrl\Services\TestTransaction

API

HTTP routes

Settings:

• GET api/integrations/btrl/settings
• PATCH api/integrations/btrl/settings/{settings}

Core classes

Depends On

Required Enso packages:

• laravel-enso/api:^1.14 ↗
• laravel-enso/forms:^5.2 for the settings form
• laravel-enso/helpers:^4.0 for encrypted settings casts and exceptions
• laravel-enso/migrator:^2.0 for menu and permission structure migrations
• laravel-enso/tables:^5.0 for TableCache on CardTransaction

Endpoint implementations return LaravelEnso\Api\Enums\Method, for example Method::POST.

Companion frontend package:

• @enso-ui/btrl