README

🇷🇴 Versiunea în română

Laravel package for integrating with the Banca Transilvania iPay payment platform.

Supports 1-Phase payments (automatic capture) and 2-Phase payments (pre-authorization + manual deposit), refunds, reversals, transaction status verification, and loyalty point payments (StarBT).

Requirements

• PHP 8.1+ (Laravel 13 requires PHP 8.3+)
• Laravel 10, 11, 12 or 13
• API credentials from Banca Transilvania

Installation

composer require BtiPay/laravel

Full installation (config, migrations, controller, routes, views):

php artisan BtiPay:install
php artisan migrate

The BtiPay:install command creates:

• config/BtiPay.php — configuration
• database/migrations/ — BtiPay_transactions table
• app/Http/Controllers/BtiPayController.php — complete controller with pay, process, finish
• routes/BtiPay.php — web routes (/BtiPay/pay, /BtiPay/process, /BtiPay/finish)
• resources/views/BtiPay/ — Blade views (pay.blade.php, finish.blade.php)

Optionally, publish only what you need:

php artisan BtiPay:install --controller   # controller only
php artisan BtiPay:install --routes       # routes only
php artisan BtiPay:install --views        # views only
php artisan BtiPay:install --force        # overwrite existing files

After installation, include the routes in your app. In routes/web.php:

require __DIR__.'/BtiPay.php';

Or in bootstrap/app.php (Laravel 11+):

->withRouting(
    web: __DIR__.'/../routes/web.php',
    then: function () {
        require base_path('routes/BtiPay.php');
    },
)

Configuration

Add to your .env:

BTIPAY_ENVIRONMENT=sandbox
BTIPAY_USERNAME=your_api_username
BTIPAY_PASSWORD=your_api_password
BTIPAY_AUTH_METHOD=header
BTIPAY_RETURN_URL=https://your-site.com/BtiPay/finish
BTIPAY_CURRENCY=946
BTIPAY_LANGUAGE=ro
BTIPAY_PAYMENT_TYPE=1phase
BTIPAY_LOGGING=true

Available Environments

Supported Currencies (ISO 4217)

Usage

1. Simple Payment (1-Phase)

use BtiPay\Laravel\Facades\BtiPay;
use BtiPay\Laravel\Builders\OrderBundle;

// Build orderBundle
$bundle = OrderBundle::make()
    ->orderCreationDate(now()->format('Y-m-d'))
    ->email('client@example.com')
    ->phone('40740123456')
    ->deliveryInfo('delivery', '642', 'Cluj-Napoca', 'Str. Example 10', '400000')
    ->billingInfo('642', 'Cluj-Napoca', 'Str. Example 10', '400000');

// Register order
$response = BtiPay::register([
    'orderNumber'  => 'ORD-' . time(),
    'amount'       => 1500, // 15.00 RON (in minor units / bani)
    'currency'     => 946,
    'returnUrl'    => route('BtiPay.finish'),
    'description'  => 'Order #123',
    'email'        => 'client@example.com',
    'orderBundle'  => $bundle->toArray(),
]);

if ($response->isSuccessful()) {
    // Redirect to the BT payment page
    return redirect($response->getFormUrl());
} else {
    // Registration error
    echo $response->getErrorMessage();
}

2. Pre-Authorized Payment (2-Phase)

// Register pre-authorization
$response = BtiPay::registerPreAuth([
    'orderNumber'  => 'ORD-' . time(),
    'amount'       => 5000, // 50.00 RON
    'returnUrl'    => route('BtiPay.finish'),
    'description'  => 'Delivery order #456',
    'orderBundle'  => $bundle->toArray(),
]);

// Redirect customer to formUrl...

// --- Later, upon delivery: Capture (deposit) ---
$depositResponse = BtiPay::deposit(
    orderId: $response->getOrderId(),
    amount: 5000
);

if ($depositResponse->isSuccessful()) {
    echo 'Payment captured successfully!';
}

3. Reversal (Cancel Pre-Authorization)

$reverseResponse = BtiPay::reverse(
    orderId: 'uuid-order-id'
);

4. Refund

// Partial refund
$refundResponse = BtiPay::refund(
    orderId: 'uuid-order-id',
    amount: 500 // Refund 5.00 RON
);

// Full refund
$refundResponse = BtiPay::refund(
    orderId: 'uuid-order-id',
    amount: 5000 // Refund full amount
);

5. Transaction Status Check

$status = BtiPay::getOrderStatus(orderId: 'uuid-order-id');

// or by orderNumber
$status = BtiPay::getOrderStatus(orderNumber: 'ORD-123');

if ($status->isPaid()) {
    echo 'Transaction completed successfully!';
    echo 'Amount: ' . $status->getAmountFormatted() . ' RON';
    echo 'Card: ' . $status->getMaskedPan();
} elseif ($status->isDeclined()) {
    echo 'Transaction declined: ' . $status->getActionCodeMessage();
}

6. Shortcut: Get Payment URL

$paymentUrl = BtiPay::getPaymentUrl(
    orderNumber: 'ORD-' . time(),
    amount: 2500,
    returnUrl: route('BtiPay.finish'),
    options: [
        'description' => 'Service payment',
        'email' => 'client@email.com',
    ]
);

return redirect($paymentUrl);

7. Finish Page (Return URL)

If you ran php artisan BtiPay:install, the controller and views are already created. The route GET /BtiPay/finish is automatically registered as BtiPay.finish.

The generated controller (BtiPayController) automatically handles:

• Status verification via getOrderStatusExtended.do
• Transaction update in the database (card, amount, RRN, ECI, etc.)
• Display of all 22 required error messages
• Retry restrictions for action codes 803, 804, 913
• Event dispatch: PaymentCompleted / PaymentDeclined

For custom integration, you can use the facade directly:

$status = BtiPay::getOrderStatus(orderId: $request->get('orderId'));

if ($status->isPaid()) {
    // Payment successful - card, amount, RRN available
    $status->getMaskedPan();
    $status->getAmountFormatted();
    $status->getAuthRefNum();
}

if ($status->isDeclined()) {
    $status->getActionCodeMessage(); // message in the configured language
}

8. Tracking with BtiPayTransaction Model

use BtiPay\Laravel\Models\BtiPayTransaction;

// Create transaction
$transaction = BtiPayTransaction::create([
    'order_id'       => $response->getOrderId(),
    'order_number'   => 'ORD-123',
    'payment_type'   => '1phase',
    'amount'         => 1500,
    'currency'       => '946',
    'status'         => 'CREATED',
    'form_url'       => $response->getFormUrl(),
    'customer_email' => 'client@email.com',
]);

// Associate with a model (e.g. Order)
$order = Order::find(1);
$transaction->payable()->associate($order);
$transaction->save();

// Queries
BtiPayTransaction::successful()->get();     // All paid transactions
BtiPayTransaction::declined()->get();       // All declined
BtiPayTransaction::preAuthorized()->get();  // Awaiting deposit

9. Model Trait

use BtiPay\Laravel\Traits\HasBtiPayPayments;

class Order extends Model
{
    use HasBtiPayPayments;
}

// Usage
$order = Order::find(1);
$order->BtiPayTransactions;          // All transactions
$order->latestBtiPayTransaction;     // Latest transaction
$order->isPaidViaBtiPay();           // Is it paid?
$order->getTotalPaidViaBtiPay();     // Total paid (in minor units)
$order->getTotalRefundedViaBtiPay(); // Total refunded

10. Loyalty Point Payments (StarBT)

// Deposit with loyalty
$response = BtiPay::deposit(
    orderId: 'uuid-ron-order-id',
    amount: 3000, // Total amount RON + LOY
    depositLoyalty: true
);

// Refund with loyalty
$response = BtiPay::refund(
    orderId: 'uuid-ron-order-id',
    amount: 4000,
    refundLoyalty: true
);

// Reverse with loyalty
$response = BtiPay::reverse(
    orderId: 'uuid-ron-order-id',
    reverseLoyalty: true
);

Events

The package dispatches the following events that you can listen for:

// EventServiceProvider.php
protected $listen = [
    \BtiPay\Laravel\Events\PaymentCompleted::class => [
        \App\Listeners\SendPaymentConfirmation::class,
    ],
    \BtiPay\Laravel\Events\PaymentDeclined::class => [
        \App\Listeners\HandleFailedPayment::class,
    ],
];

Error Codes (Action Codes)

The 22 required error codes to handle per BT documentation:

Package Structure

BtiPay/
├── config/
│   └── BtiPay.php                 # Configuration
├── database/
│   └── migrations/                # Transactions table migration
├── stubs/
│   ├── BtiPayController.php.stub  # Controller (published via BtiPay:install)
│   ├── BtiPay-routes.php.stub     # Routes (published via BtiPay:install)
│   └── views/
│       ├── pay.blade.php.stub     # Payment form
│       └── finish.blade.php.stub  # Finish page (success/error)
├── src/
│   ├── Builders/
│   │   └── OrderBundle.php        # Fluent builder for orderBundle
│   ├── Console/
│   │   └── InstallCommand.php     # php artisan BtiPay:install
│   ├── Enums/
│   │   ├── Currency.php           # Currency enum (RON/EUR/USD)
│   │   ├── OrderStatus.php        # Transaction status enum
│   │   └── PaymentType.php        # Payment type enum (1phase/2phase)
│   ├── Events/
│   │   ├── PaymentCompleted.php
│   │   ├── PaymentDeclined.php
│   │   ├── PaymentRefunded.php
│   │   └── PaymentRegistered.php
│   ├── Exceptions/
│   │   ├── BtiPayAuthenticationException.php
│   │   ├── BtiPayConnectionException.php
│   │   ├── BtiPayException.php
│   │   └── BtiPayValidationException.php
│   ├── Facades/
│   │   └── BtiPay.php             # Laravel Facade
│   ├── Models/
│   │   └── BtiPayTransaction.php  # Eloquent Model
│   ├── Responses/
│   │   ├── ActionCodeMessages.php  # Error messages (RO/EN)
│   │   ├── BaseResponse.php
│   │   ├── DepositResponse.php
│   │   ├── FinishedPaymentInfoResponse.php
│   │   ├── OrderStatusResponse.php
│   │   ├── RefundResponse.php
│   │   ├── RegisterResponse.php
│   │   └── ReverseResponse.php
│   ├── Traits/
│   │   └── HasBtiPayPayments.php  # Trait for models
│   ├── BtiPayClient.php           # HTTP Client
│   ├── BtiPayGateway.php          # Main Gateway
│   └── BtiPayServiceProvider.php  # Service Provider
├── composer.json
├── README.md
└── README_RO.md

License

MIT License

Contact

For BT iPay API issues: aplicatiiecommerce@btrl.ro