Download the PHP package shubo/module-tbc-payment without Composer

Shubo_TbcPayment -- TBC Bank (Flitt) Payment Module for Magento 2

TBC Bank card payment integration for Magento 2 using the Flitt Embed Checkout SDK. Customers enter card details directly on your checkout page without being redirected to an external payment page.

IMPORTANT DISCLAIMER: This module has NOT been tested in production with real transactions. It has been developed and tested against sandbox/test environments only. Thorough testing with real payment credentials and real cards is required before going live.

Table of Contents

• Overview
• Requirements
• Installation
• Configuration
• Supported Features
• Unsupported Features
• Payment Flow
• Order Status Flow
• Split Payments (Marketplace)
• Admin Actions
• Technical Architecture
• API Endpoints
• Logging
• Cron Jobs
• Internationalization
• Troubleshooting
• License

Overview

Shubo_TbcPayment integrates TBC Bank card payments into Magento 2 via the Flitt payment platform (formerly known as Fondy/Cloudipsp). The module uses the Flitt Embed Checkout approach: an embedded card form renders directly inside the Magento checkout page. The customer never leaves your site during the payment process.

Key highlights:

• Embedded card form on checkout (no redirect)
• Pre-authorization (hold) and automatic capture modes
• Full and partial refunds via Magento credit memos
• Split payment settlement for marketplace/multi-vendor scenarios
• Server-to-server callback + cron reconciler for reliable order processing
• Apple Pay / Google Pay support (via Flitt wallets)
• Customizable card form theme, layout, and color presets

Requirements

You also need a Flitt merchant account from TBC Bank with a Merchant ID and Secret Key (password).

Installation

Via Composer (recommended)

Manual Installation

1. Copy the module files to app/code/Shubo/TbcPayment/.

2. Install the Cloudipsp SDK dependency:

3. Enable and install:

Configuration

Navigate to Stores > Configuration > Sales > Payment Methods > TBC Bank (Flitt Embed).

Credentials

Payment Settings

Embed Appearance

Split Payments

Config paths (for programmatic access):

Supported Features

Unsupported Features

Payment Flow

Key design decision: The Magento order is created after Flitt processes the payment (embed success event), not before. This prevents ghost orders from abandoned 3DS flows or invalid card data.

Order Status Flow

Split Payments (Marketplace)

Split payments allow distributing order funds to multiple Flitt merchants after a payment is approved. This is designed for marketplace scenarios where the platform takes a commission and vendors receive their share.

How It Works

1. The full payment amount is collected by your main Merchant ID.
2. After approval, a settlement request distributes funds to configured receivers.
3. The remainder always stays with the main merchant.

Configuration Methods

Admin-configured receivers (static): Set fixed receivers in the admin panel. Every order uses the same split rules.

Event-based receivers (dynamic): Other modules (e.g., a Commission module) can listen to the shubo_tbc_settlement_collect_receivers event and provide per-order split data. Event-based receivers take priority over admin-configured ones.

Amount Calculation

Settlement supports mixed modes:

• Fixed amounts are deducted first from the order total.
• Percentage amounts are then applied to the remaining amount.

Example: Order total = 100 GEL, Receiver A = 5 GEL fixed, Receiver B = 20%

• Receiver A gets 5 GEL
• Receiver B gets 20% of (100 - 5) = 19 GEL
• Main merchant keeps 76 GEL

Settlement API Format

Settlement uses a different request format than other Flitt APIs: the order data is base64-encoded and signed with sha1(password|base64_data) (version 2.0 signature).

Admin Actions

The following buttons appear on the order view page for TBC-paid orders:

Technical Architecture

Key Classes

Magento Payment Gateway Pattern

The module uses Magento's Payment Gateway framework with virtual types:

• Facade: ShuboTbcPaymentFacade (virtual type of Magento\Payment\Model\Method\Adapter)
• Command Pool: a single refund command. Checkout-token creation, capture, status checks and settlement run through standalone clients (CaptureClient, StatusClient, SettlementClient) and the controllers, not the command pool.
• Request Builders: RefundRequestBuilder (refund payload). SplitDataBuilder is retained for split-receiver data but is not currently wired into a command pool.
• HTTP Clients: Direct cURL calls to the Flitt REST API
• Response Handlers: RefundHandler stores refund status
• Validators: CallbackValidator verifies SHA1 callback/status signatures

Events Dispatched

API Endpoints

Flitt API Endpoints Used

Base URL: https://pay.flitt.com (same for sandbox and production; sandbox is controlled by merchant credentials).

Module Frontend Routes

Module Admin Routes

Logging

All module logs are written to a dedicated file:

Enable Debug mode in configuration to log full API request/response bodies. Sensitive data (merchant ID, signature, password) is automatically masked in debug logs.

Cron Jobs

Internationalization

The module includes translations for:

• English (en_US)
• Georgian (ka_GE)

The Flitt embed card form language is automatically set based on the Magento store locale. Supported languages: en, ka, ru.

Troubleshooting

Payment form does not load

• Verify Merchant ID and Password are correctly set in configuration.
• Check the browser console for CSP errors. The module whitelists pay.flitt.com but custom CSP configurations may block it.
• Check var/log/shubo_tbc_payment.log with debug mode enabled.

Order stuck in "pending_payment"

• Use the "Check Flitt Status" button in admin to manually query and sync.
• The cron reconciler should automatically process stuck orders after 15 minutes.
• Verify the callback URL (/shubo_tbc/payment/callback) is accessible from the internet.

Refund fails

• Ensure the Flitt order ID is stored on the payment (flitt_order_id in additional info).
• Check var/log/shubo_tbc_payment.log for the Flitt API error response.
• Partial refunds are supported; the amount is sent in minor units (cents).

Settlement fails

• Verify split payments are enabled and receivers are configured.
• Check that receiver Merchant IDs are valid Flitt merchants.
• Total percentages must not exceed 100%.
• Fixed amounts must not exceed the order total.
• Check logs for the Flitt settlement API response.

Signature validation failed

• Ensure the Password (Secret Key) matches what is configured in the Flitt merchant dashboard.
• The signature is generated using all non-empty parameters sorted alphabetically.

License

Apache License 2.0. See LICENSE for details.

Copyright 2026 Nikoloz Shubitidze (Shubo).