webrteu / btipay

v1.0.0 2026-11-04 05:09 UTC

Requires

• php: ^8.2
• illuminate/console: ^12.0|^13.0
• illuminate/database: ^12.0|^13.0
• illuminate/http: ^12.0|^13.0
• illuminate/routing: ^12.0|^13.0
• illuminate/support: ^12.0|^13.0
• illuminate/translation: ^12.0|^13.0
• webrteu/payments: ^1.0

Requires (Dev)

• larastan/larastan: ^3.13
• laravel/pint: ^1.32
• orchestra/testbench: ^10.0|^11.0
• peckphp/peck: ^0.3
• pestphp/pest: ^3.8|^4.7
• pestphp/pest-plugin-laravel: ^3.2|^4.1
• pestphp/pest-plugin-type-coverage: ^3.6|^4.0.4
• phpstan/phpstan: ^2.3.3,!=2.3.4
• rector/rector: ^2.8

MIT

• WeBRTeu

• payments
• laravel
• payment-gateway
• Romania
• banca-transilvania
• btipay

Published on Packagist.org on 2026-11-04 05:09 UTC

README

Integrare Laravel pentru BT iPay (Banca Transilvania), API REST *.do: plată într-un pas sau pre-autorizare + capturare, refund, confirmare prin API (callback sau ruta de return), mesajele actionCode cerute la certificarea BT. Implementează Gateway, Refundable, Capturable și ConfirmsWebhooks din webrteu/payments.

Nu este un pachet oficial Banca Transilvania.

Cerințe

• PHP ^8.2, Laravel 12–13
• contract e-commerce BT (utilizator API + parolă, separate pentru test și producție)
• certificare pe mediul de test înainte de producție (inclusiv mesajele pentru codurile de eroare)
• webrteu/payments

Instalare

composer require webrteu/btipay
php artisan vendor:publish --tag=btipay-config
php artisan vendor:publish --tag=btipay-lang     # opțional, pentru a personaliza mesajele

Configurare

BTIPAY_SANDBOX=true           # ecclients.btrl.ro:5443 (test)
BTIPAY_USERNAME=              # utilizator API primit de la BT
BTIPAY_PASSWORD=
BTIPAY_CALLBACK_TOKEN=        # doar dacă BT activează callback cu checksum
BTIPAY_TWO_STEP=false         # true = pre-autorizare + capturare manuală
BTIPAY_RETURN_URL=            # gol = ruta btipay.return din pachet
BTIPAY_AFTER_RETURN_URL=/     # unde ajunge clientul după ruta de return (?order=&btipay_order=)
BTIPAY_TIMEOUT=30

⚠️ URL-urile de test/producție și lista de coduri se confirmă din documentația BT primită la contract.

Utilizare

$redirect = Payments::start('btipay', $paymentRequest, payable: $order);   // register.do (sau registerPreAuth.do)
return $redirect->toResponse();

Suma se trimite în bani (14170), moneda 946 (RON), plus orderBundle (date client pentru 3DS2).

Metodă	BT iPay
status($orderId)	getOrderStatusExtended.do
BtiPay::capture($orderId, $bani)	deposit.do
BtiPay::void($orderId)	reverse.do
BtiPay::refund($orderId, $bani)	refund.do

Confirmarea plății

1. Callback (dacă BT îl activează): https://site.ro/webhooks/payments/btipay. Cu BTIPAY_CALLBACK_TOKEN, checksum-ul HMAC-SHA256 pe parametrii sortați („cheie;valoare;”) e obligatoriu. Fără token, callback-ul e tratat doar ca semnal.
2. Return (întotdeauna): returnUrl = GET /payments/btipay/return?orderId=... (ruta btipay.return). Parametrii din URL nu sunt crezuți: se pune pe coadă jobul din core, care cere statusul prin getOrderStatusExtended.do.

Combinat cu payments:reconcile, plata se confirmă chiar dacă clientul închide pagina.

Mesajul pentru client la eșec (cerut la certificare):

use WeBRTeu\BtiPay\Facades\BtiPay;

$message = BtiPay::messageFor($status->raw['actionCode'] ?? null);   // „Fonduri insuficiente.”

Statusuri

orderStatus	PaymentStatus
0, 5	Pending
1	Authorized
2	Paid
3	Cancelled
4	Refunded sau PartiallyRefunded (după depositedAmount vs refundedAmount)
6	Failed

Ce nu face pachetul

• nu suportă callback cu semnătură asimetrică
• nu colectează date de card

Testare

composer test
BTIPAY_SANDBOX_USERNAME=... BTIPAY_SANDBOX_PASSWORD=... vendor/bin/pest --group=sandbox

Fixture-urile sunt după documentație. De înlocuit cu răspunsuri reale.

Changelog

Vezi CHANGELOG.md.

Autor

WeBRTeu

Licență

MIT. Vezi LICENSE.md.