PHPackages                             andreighioc/btipay - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Payment Processing](/categories/payments)
4. /
5. andreighioc/btipay

ActiveLibrary[Payment Processing](/categories/payments)

andreighioc/btipay
==================

Banca Transilvania Payment Gateway for Laravel

v1.0.0(1mo ago)00MITPHPPHP ^8.1

Since Apr 14Pushed 1mo agoCompare

[ Source](https://github.com/andreighioc/btipay)[ Packagist](https://packagist.org/packages/andreighioc/btipay)[ RSS](/packages/andreighioc-btipay/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (5)Versions (2)Used By (0)

BT iPay - Laravel Package
=========================

[](#bt-ipay---laravel-package)

> 🇷🇴 [Versiunea în română](README_RO.md)

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
------------

[](#requirements)

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

Installation
------------

[](#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
-------------

[](#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

[](#available-environments)

EnvironmentDescription`sandbox`Test environment ()`production`Production environment ()### Supported Currencies (ISO 4217)

[](#supported-currencies-iso-4217)

CurrencyCodeRON946EUR978USD840Usage
-----

[](#usage)

### 1. Simple Payment (1-Phase)

[](#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)

[](#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)

[](#3-reversal-cancel-pre-authorization)

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

### 4. Refund

[](#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

[](#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

[](#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)

[](#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

[](#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

[](#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)

[](#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
------

[](#events)

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

EventDescription`PaymentRegistered`Payment has been registered with iPay`PaymentCompleted`Payment completed successfully (DEPOSITED)`PaymentDeclined`Payment was declined`PaymentRefunded`Refund processed (partial or full)```
// 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)
--------------------------

[](#error-codes-action-codes)

The 22 required error codes to handle per BT documentation:

CodeDescription104Restricted card124Transaction cannot be authorized per regulations320Inactive card801Issuer unavailable803Card blocked ⚠️ Do NOT retry with the same card!804Transaction not allowed ⚠️ Do NOT retry with the same card!805Transaction declined861Invalid expiration date871Invalid CVV905Invalid card906Expired card913Invalid transaction ⚠️ Do NOT retry with the same card!914Invalid account915Insufficient funds917Transaction limit exceeded952Suspected fraud998Installments not allowed with this card3410163DS2 authentication declined3410173DS2 status unknown3410183DS2 cancelled by customer3410193DS2 authentication failed3410203DS2 unknown statusPackage Structure
-----------------

[](#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
-------

[](#license)

MIT License

Contact
-------

[](#contact)

For BT iPay API issues:

###  Health Score

35

—

LowBetter than 77% of packages

Maintenance89

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity42

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

56d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/82b6cb88da2e43e1c0d384c85e553575d60f4629bb599570871cfb4f3bed3f49?d=identicon)[andreighioc](/maintainers/andreighioc)

---

Tags

laravelpaymentgatewayipayRomania3dsecurebtbanca-transilvania

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/andreighioc-btipay/health.svg)

```
[![Health](https://phpackages.com/badges/andreighioc-btipay/health.svg)](https://phpackages.com/packages/andreighioc-btipay)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3325.1M337](/packages/psalm-plugin-laravel)[sebdesign/laravel-viva-payments

A Laravel package for integrating the Viva Payments gateway

4849.3k](/packages/sebdesign-laravel-viva-payments)[simplestats-io/laravel-client

Analytics for Laravel. Track visitors, registrations, and payments. Discover which channels actually drive revenue, not just traffic. Server-side, GDPR compliant, ad-blocker proof.

5019.3k](/packages/simplestats-io-laravel-client)[parsisolution/gateway

A Laravel package for connecting to all Iraninan payment gateways

231.7k](/packages/parsisolution-gateway)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)