A Laravel store in Georgia usually takes cards through a bank or provider's hosted payment page: TBC Bank (TBC Checkout, its API is called tpay), Bank of Georgia (BOG Payments) or Flitt. Your shop creates a payment, sends the shopper to the provider's page and learns the result afterwards. Card numbers never touch your server.
The redirect is the easy part. The hard part is marking an order paid exactly when the money really arrived, and never twice. This post walks through how I handle that, using Tetri, the Laravel package I wrote for these three providers. The principles hold whether you use it or write your own integration.
Honest status first. Tetri's TBC, BOG and Flitt drivers are tested against each provider's documented API and against local stub banks. Live production payments have not yet run through it. Every buyer gets personal setup help from me for their first live payments.
The redirect flow
Five steps:
- The shopper clicks Pay. Your app records a payment attempt before calling the bank, so nothing the bank sends later can arrive for a payment you have no record of.
- Your app asks the provider to create a payment and gets back the URL of its payment page.
- You redirect the shopper there. They pay with a card, Apple Pay or Google Pay.
- The provider posts a callback to your server and sends the shopper back to your site.
- Your app confirms the payment with the provider and marks the order paid, once.
Guard against double clicks: a second click should reuse the page that is already open, and an order that is already paid should not open a new one. With Tetri the first half is one call:
use Hackerman\Tetri\Facades\Tetri; public function pay(Order $order, Request $request) { $result = Tetri::start( $order, returnUrl: route('orders.show', $order), driver: $request->input('bank'), // 'tbc', 'bog', 'flitt'; null uses TETRI_DRIVER locale: app()->getLocale(), // the bank page language (ka, en; Flitt also ru) shopperIp: $request->ip(), expiresInMinutes: 15, // optional: how long the bank page stays payable ); if ($result->alreadyPaid) { return redirect()->route('orders.show', $order); } if (! $result->successful()) { return back()->withErrors(['payment' => $result->message()]); // translated, en and ka included } return $result->toRedirect(); // 303 to the bank page } Your Order tells Tetri what to charge by implementing Payable. Amounts are integers in minor units (tetri), never floats: 123.45 GEL is 12345.
class Order extends Model implements Payable { use IsPayable; public function payableReference(): string { return '#'.$this->number; } // shown on the bank page public function payableAmountMinor(): int { return $this->total_minor; } // 123.45 GEL = 12345 public function payableCurrency(): string { return 'GEL'; } } Callbacks are hints, not the truth
The callback is the server-to-server notification from the provider. It is how your store learns about a payment even when the shopper closes the tab. But it arrives at a public URL, and anyone can post to a public URL. Three rules keep it safe:
- Verify signatures where the provider signs. BOG signs callbacks with RSA: SHA256withRSA over the raw request body, checked against BOG's published public key. Verify against the raw bytes, not a re-encoded array, or the check fails. Flitt signs its callbacks with your payment key. TBC's callbacks are not signed and only name a payment.
- Ask the provider anyway. Even a valid signature only tells you something happened. Before recording anything, read the payment's status back from the provider's API. For TBC, that read-back is the only check there is.
- Process each outcome exactly once. Providers may resend the same callback, and a callback and the shopper's return can land together. Use a lock, and only ever move the status forward.
The callback route must sit outside Laravel's web middleware group, because the bank has no session and no CSRF token. Tetri registers its routes there and sends their URLs, built on APP_URL, with every payment:
POST /tetri/callback/{driver} # /tetri/callback/tbc, /bog, /flitt GET|POST /tetri/return/{attempt} # where the bank sends the shopper back (Flitt uses a POST) BOG may rotate its signing key. If it does, paste the new PEM into TETRI_BOG_CALLBACK_PUBLIC_KEY.
When a payment is confirmed, your code hears about it through an outcome handler (or the PaymentSucceeded, PaymentFailed and PaymentRefunded events). Keep it idempotent:
class OrderPayments implements PaymentOutcomeHandler { public function paymentSucceeded(Payable $order, PaymentAttempt $attempt): void { $order->markPaid(); // your code } public function paymentFailed(Payable $order, PaymentAttempt $attempt): void { // The shopper may still pay again through a new attempt. Cancel only by your own rules. } public function paymentRefunded(Payable $order, PaymentAttempt $attempt, int $amountMinor): void { $order->recordRefund($amountMinor); } } Status sync, not the return URL
The shopper landing back on your site proves nothing. A return URL with ?status=success can be typed by hand. Your return page should read the payment state, not the query string. Tetri asks the bank before it redirects the shopper to your $returnUrl, so the state is already current there:
$state = Tetri::state($order); $state->isPaid(); $state->canPay(); // show a pay / try again button $state->cardMask; // e.g. 411111******1111 Callbacks also get lost: a deploy, a timeout, a firewall. Without a safety net, a shopper who paid sees an unpaid order. So schedule a sweep, and ask the bank one last time before cancelling anything:
// routes/console.php Schedule::command('tetri:sweep')->everyMinute()->withoutOverlapping(); // before you cancel an unpaid order $state = Tetri::sync($order); if (! $state->isPaid() && ! $state->livePage) { $order->cancel(); } The sweep reconciles attempts nobody checked for two minutes (a lost callback is caught here), follows refunds the bank has not settled, and checks abandoned pages for 24 hours in case a late payment comes in before closing them.
Refunds and partial refunds
Tetri::refund($order); // everything left Tetri::refund($order, 2_500, 'Damaged box', 'staff:7'); // 25.00 GEL, with a reason and who asked Providers accept a refund and settle it later. Until the bank confirms, treat the amount as pending and held, so the same money can never be sent back twice. Never refund more than was captured minus what was already returned, and never refund blind when the provider cannot be reached. Tetri does all three, and a refusal throws RefundRefused with a staff-safe message (the bank's own words when the bank said no).
Partial refunds work on all three, with caveats:
- TBC: yes, but TBC's own rules apply (for example same-day limits), and its refusal is shown verbatim.
- BOG: yes for card, Apple Pay and Google Pay; other BOG methods refund in full only, and Tetri refuses before sending.
- Flitt: yes, as a reversal per refund request. Flitt shows no reversal in flight, so a held Flitt refund is never released by time. You check the Flitt portal, then release it with
Tetri::releaseRefundHold().
Testing without bank credentials
You can build the whole integration before a bank signs anything. Each driver has a local stub: the bank's API plus a bare hosted page with Pay, Decline and Let it expire buttons.
APP_ENV=local APP_URL=http://localhost:8000 TETRI_DRIVER=bog TETRI_BOG_ENABLED=true TETRI_BOG_STUB=true # also TETRI_TBC_STUB, TETRI_FLITT_STUB The driver calls the stub over HTTP on your own app, so the server must handle two requests at once:
PHP_CLI_SERVER_WORKERS=4 php artisan serve The stubs sign BOG callbacks with a key of their own, sign Flitt answers like Flitt, and honour BOG's Idempotency-Key, so callbacks and refunds run the way they will against the bank. They answer only in local and testing.
For your test suite there is a fake driver that needs no network:
$result = Tetri::start($order, route('orders.show', $order)); $this->get($result->redirectUrl); // the fake "bank page" is the return route: paid FakeGateway::simulate($attempt->reference, PaymentStatus::Failed); Going live
-
APP_ENV=production, anhttpsAPP_URL, the queue worker and the scheduler running. - Real credentials in
.env, stub flags off. -
php artisan tetri:status: every driver you enabled must readready: yes. It also prints the callback URL to give a bank during onboarding. - Send yourself a small real payment, refund it, and watch
PaymentSucceededandPaymentRefundedarrive.
None of this replaces the merchant agreement. Each provider sets its own requirements and fees, and no package can sign that for you.
Status, again
TBC, BOG and Flitt drivers are complete and tested against each provider's documented API and local stubs. Live production transactions have not yet run, and some behaviour is only documented, not yet observed on a live merchant account (for example the exact encoding of BOG's callback signature and TBC's partial refund rules). Tetri reads these defensively, any surprise from the first live payments gets fixed for every buyer, and every buyer gets personal help from me for their first live payments.
Links
- Full guide (English): https://plugins.hackerman.ge/guides/laravel-card-payments
- Full guide (Georgian): https://plugins.hackerman.ge/ka/guides/laravel-card-payments
- Provider pages: TBC, Bank of Georgia, Flitt (Georgian: TBC, BOG, Flitt)
- Pricing: https://plugins.hackerman.ge/#pricing
- Questions: support@plugins.hackerman.ge

