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\People\Models\Person;

$paymentUrl = (new Register($customer, new TestTransaction()))->handle();

Register expects:

• a LaravelEnso\People\Models\Person or LaravelEnso\Companies\Models\Company
• a class implementing LaravelEnso\Btrl\Contracts\Tradable

The service creates a bt_card_transactions row before the remote call, stores the request payload, then persists the returned order reference and raw response.

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/{setting}

Core classes

Depends On

Required Enso packages:

• laravel-enso/api:^1.14 ↗
• laravel-enso/helpers for encrypted settings casts and exceptions
• laravel-enso/people and laravel-enso/companies for supported customer models
• laravel-enso/tables for TableCache on CardTransaction

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

Companion frontend package:

• @enso-ui/btrl