PHPackages shubo/module-tbc-payment - 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. shubo/module-tbc-payment ActiveMagento2-module[Payment Processing](/categories/payments) shubo/module-tbc-payment ======================== TBC Bank (Flitt Embed) payment gateway for Magento 2 v1.0.0(2mo ago)01Apache-2.0PHPPHP >=8.1 Since May 1Pushed 1mo agoCompare [ Source](https://github.com/nshubitidze/module-tbc-payment)[ Packagist](https://packagist.org/packages/shubo/module-tbc-payment)[ Docs](https://github.com/nshubitidze/module-tbc-payment)[ RSS](/packages/shubo-module-tbc-payment/feed)WikiDiscussions main Synced 3w ago READMEChangelogDependencies (6)Versions (2)Used By (0) Shubo\_TbcPayment -- TBC Bank (Flitt) Payment Module for Magento 2 ================================================================== [](#shubo_tbcpayment----tbc-bank-flitt-payment-module-for-magento-2) [![Packagist](https://camo.githubusercontent.com/b14aa3bd0814c2d7ad6da6a6d0826530b516228258e8dc9e3fb9673fbe80a017/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7061636b61676973742d736875626f2532466d6f64756c652d2d7462632d2d7061796d656e742d6f72616e67652e737667)](https://packagist.org/packages/shubo/module-tbc-payment)[![License: Apache 2.0](https://camo.githubusercontent.com/a549a7a30bacba7bfceebdc207a8e86c3f2c02995a2527640dca30048fd2b64e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d417061636865253230322e302d626c75652e737667)](./LICENSE)[![Magento](https://camo.githubusercontent.com/128e86f84d29af29a2ac8a6d0c378d4c819f7384260c3da4337578b4dfdf918a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4d6167656e746f2d322e342e782d3861326265322e737667)](https://magento.com) TBC Bank card payment integration for Magento 2 using the [Flitt](https://flitt.com) 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 ----------------- [](#table-of-contents) - [Overview](#overview) - [Requirements](#requirements) - [Installation](#installation) - [Configuration](#configuration) - [Supported Features](#supported-features) - [Unsupported Features](#unsupported-features) - [Payment Flow](#payment-flow) - [Order Status Flow](#order-status-flow) - [Split Payments (Marketplace)](#split-payments-marketplace) - [Admin Actions](#admin-actions) - [Technical Architecture](#technical-architecture) - [API Endpoints](#api-endpoints) - [Logging](#logging) - [Cron Jobs](#cron-jobs) - [Internationalization](#internationalization) - [Troubleshooting](#troubleshooting) - [License](#license) Overview -------- [](#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 ------------ [](#requirements) RequirementVersionMagento2.4.8+PHP8.1+`magento/framework`>= 103.0`magento/module-payment`>= 100.4`magento/module-sales`>= 103.0`magento/module-checkout`>= 100.4`magento/module-quote`>= 101.2`cloudipsp/php-sdk-v2`^1.0You also need a **Flitt merchant account** from TBC Bank with a Merchant ID and Secret Key (password). Installation ------------ [](#installation) ### Via Composer (recommended) [](#via-composer-recommended) ``` composer require shubo/module-tbc-payment bin/magento module:enable Shubo_TbcPayment bin/magento setup:upgrade bin/magento cache:flush ``` ### Manual Installation [](#manual-installation) 1. Copy the module files to `app/code/Shubo/TbcPayment/`. 2. Install the Cloudipsp SDK dependency: ``` composer require cloudipsp/php-sdk-v2:^1.0 ``` 3. Enable and install: ``` bin/magento module:enable Shubo_TbcPayment bin/magento setup:upgrade bin/magento cache:flush ``` Configuration ------------- [](#configuration) Navigate to **Stores > Configuration > Sales > Payment Methods > TBC Bank (Flitt Embed)**. ### Credentials [](#credentials) FieldDescription**Enabled**Enable or disable the payment method.**Title**Display name shown to customers at checkout. Default: `TBC Bank (Card Payment)`.**Merchant ID**Your Flitt merchant ID, provided by TBC Bank.**Password (Secret Key)**Your Flitt payment password / secret key. Stored encrypted.### Payment Settings [](#payment-settings) FieldDescription**Payment Action**`Authorize & Capture` (default) -- charges immediately and creates an invoice. `Authorize Only` -- holds funds, requiring manual capture from admin.**Sandbox Mode**When enabled, uses the sandbox API URL.**Sandbox API URL**API base URL for sandbox. Default: `https://pay.flitt.com`.**Production API URL**API base URL for production. Default: `https://pay.flitt.com`.**Payment Lifetime (seconds)**How long the payment session stays valid. Default: 3600 (1 hour). Range: 300 to 86400 (5 minutes to 24 hours).**Debug**When enabled, logs all API requests and responses to the dedicated log file.**Sort Order**Controls the display order of the payment method at checkout.### Embed Appearance [](#embed-appearance) FieldDescription**Checkout Theme**`Light` or `Dark` theme for the embedded card form.**Checkout Theme Preset**Color preset: Default, Black, Silver, Vibrant Gold, Euphoric Pink, Heated Steel, Nude Pink, Tropical Gold, Navy Shimmer.**Checkout Layout**`Default`, `Plain`, or `Wallets Only`.**Advanced Embed Options (JSON)**Raw JSON to override any Flitt embed option. Example: `{"show_email": true, "logo_url": "https://example.com/logo.png"}`. See [Flitt embed docs](https://docs.flitt.com/api/embedded-custom/).**Enable Apple Pay / Google Pay**Allow customers to pay with Apple Pay and Google Pay in the embed.### Split Payments [](#split-payments) FieldDescription**Enable Split Payments**Enable fund distribution to multiple Flitt merchants.**Auto-Settle After Approval**Automatically send settlement request when payment is approved. If disabled, use the "Settle Payment" button in admin.**Split Receivers**Dynamic rows table to configure receivers. Each row has: Merchant ID (Flitt), Amount Type (Percentage or Fixed), Amount, Description.Config paths (for programmatic access): ``` payment/shubo_tbc/active payment/shubo_tbc/merchant_id payment/shubo_tbc/password payment/shubo_tbc/sandbox_mode payment/shubo_tbc/api_url payment/shubo_tbc/sandbox_api_url payment/shubo_tbc/payment_action_mode payment/shubo_tbc/payment_lifetime payment/shubo_tbc/embed_theme_type payment/shubo_tbc/embed_theme_preset payment/shubo_tbc/embed_layout payment/shubo_tbc/embed_options_json payment/shubo_tbc/enable_wallets payment/shubo_tbc/split_payments_enabled payment/shubo_tbc/split_auto_settle payment/shubo_tbc/split_receivers payment/shubo_tbc/debug payment/shubo_tbc/sort_order ``` Supported Features ------------------ [](#supported-features) FeatureStatusDetailsEmbedded card form (no redirect)SupportedFlitt Embed SDK renders inside checkoutAuthorize & Capture (auto-invoice)SupportedPayment charged on approval, invoice created automaticallyAuthorize Only (pre-authorization)SupportedFunds held, manual capture via admin buttonManual capture from adminSupported"Capture Payment" button on order viewVoid pre-authorized paymentSupported"Void Payment" button cancels the order; hold expires on bank sideFull refundSupportedVia Magento credit memoPartial refundSupportedVia Magento credit memo with partial amountServer-to-server callbacksSupportedFlitt POSTs to `/shubo_tbc/payment/callback`Frontend confirmationSupportedJS calls `/shubo_tbc/payment/confirm` after embed successCron reconcilerSupportedChecks stuck orders every 5 minutesManual status check from adminSupported"Check Flitt Status" button queries API and syncs orderSplit payments (settlement)SupportedPost-payment fund distribution to sub-merchantsAuto-settle after approvalSupportedConfigurable per-storeManual settlement from adminSupported"Settle Payment" button on order viewApple Pay / Google PaySupportedVia Flitt embed wallets (requires Flitt-side setup)Multi-currencySupportedSends quote currency code to FlittMulti-store / multi-websiteSupportedAll config fields are website-scopedPayment info in adminSupportedShows Payment ID, card, RRN, 3DS status, fees, settlement detailsLocalization (EN/KA)SupportedCard form and API requests use store locale3D SecureSupportedHandled by Flitt embed -- 3DS status shown in admin (ECI values)Signature verificationSupportedSHA1 signature on all API calls and callback validationCSP whitelistingSupported`pay.flitt.com` whitelisted for scripts, styles, frames, etc.Sensitive data protectionSupportedSecrets encrypted in config, masked in logsUnsupported Features -------------------- [](#unsupported-features) FeatureStatusRecurring / subscription paymentsNot implementedSaved card / tokenizationNot implementedInstallment paymentsNot implementedRedirect-based checkout (non-embed)Not implemented (embed only)Partial capture of pre-authorized amountNot implemented (full capture only)Admin order creation (phone orders)Not supported (`can_use_internal` = 0)Country restrictionNot implemented (no country validator pool)Payment page on separate URLNot applicable (embed approach)Payment Flow ------------ [](#payment-flow) ``` Customer selects TBC payment at checkout | v JS calls POST /shubo_tbc/payment/params -> Backend signs params, requests token from Flitt API -> Returns checkout token to frontend | v Flitt Embed SDK renders card form in checkout (Customer enters card details + 3DS if required) | v Customer clicks "Place Order" -> JS calls paymentService.submit() -> Flitt processes the payment | +-----+-----+ | | Success Error | | v v JS places Show error Magento order message | v JS calls POST /shubo_tbc/payment/confirm -> Backend checks Flitt status API -> If approved: captures payment, creates invoice -> Redirects to success page | v (Meanwhile) Flitt sends POST callback to /shubo_tbc/payment/callback -> Verifies signature -> Updates order if not already processed -> Triggers settlement if configured | v (Every 5 min) Cron reconciler checks stuck orders -> Queries Flitt status API -> Processes approved / cancels declined or expired ``` **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 ----------------- [](#order-status-flow) ``` Order Placed ──> pending_payment | +----------+----------+ | | | Approved Declined Expired | | | v v v processing canceled canceled (invoice) If Payment Action = "Authorize Only": Approved ──> processing (funds held, no invoice) | +------+------+ | | Capture Void | | v v processing canceled (invoice) ``` Split Payments (Marketplace) ---------------------------- [](#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 [](#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 [](#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 [](#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-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 ------------- [](#admin-actions) The following buttons appear on the order view page for TBC-paid orders: ButtonAppears WhenAction**Check Flitt Status**Any TBC order with a Flitt order IDQueries Flitt API, displays status, auto-processes if approved**Capture Payment**Pre-authorized order (not yet captured)Sends capture request to Flitt API, creates invoice**Void Payment**Pre-authorized order (not yet captured)Cancels the Magento order; bank hold expires automatically**Settle Payment**Split payments enabled, not yet settledSends settlement request to distribute funds to receiversTechnical Architecture ---------------------- [](#technical-architecture) ### Key Classes [](#key-classes) ClassPurpose`Gateway\Config\Config`Configuration reader with typed accessors; signature generation`Gateway\Http\Client\RefundClient`Sends refund requests to Flitt `/api/reverse/order_id``Gateway\Http\Client\CaptureClient`Captures pre-authorized payments via `/api/capture/order_id``Gateway\Http\Client\StatusClient`Checks payment status via `/api/status/order_id``Gateway\Http\Client\SettlementClient`Distributes funds via `/api/settlement``Gateway\Request\RefundRequestBuilder`Builds the refund request payload`Gateway\Request\SplitDataBuilder`Adds split receiver data to the settlement request (kept; not wired into a command pool)`Gateway\Response\RefundHandler`Processes refund response, stores refund status`Gateway\Validator\CallbackValidator`Verifies SHA1 callback signatures`Controller\Payment\Params`AJAX endpoint returning the Flitt checkout token`Controller\Payment\Callback`Server-to-server callback from Flitt`Controller\Payment\Confirm`Frontend confirmation after embed success`Service\SettlementService`Orchestrates split payment settlement`Cron\PendingOrderReconciler`Reconciles stuck pending orders`Observer\SetPendingPaymentState`Sets order to `pending_payment` on placement`Plugin\AddSettleButton`Adds admin toolbar buttons`Model\Ui\ConfigProvider`Provides checkout JS configuration`Block\Payment\Info`Renders payment details in admin### Magento Payment Gateway Pattern [](#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 [](#events-dispatched) EventPurpose`shubo_tbc_payment_split_data`Allows modules to add split receivers to the payment request`shubo_tbc_settlement_collect_receivers`Allows modules to provide per-order settlement receiversAPI Endpoints ------------- [](#api-endpoints) ### Flitt API Endpoints Used [](#flitt-api-endpoints-used) EndpointMethodPurpose`/api/checkout/token`POSTCreate checkout session token`/api/status/order_id`POSTCheck payment status`/api/reverse/order_id`POSTRefund / reverse payment`/api/capture/order_id`POSTCapture pre-authorized payment`/api/settlement`POSTDistribute funds (split payments)Base URL: `https://pay.flitt.com` (same for sandbox and production; sandbox is controlled by merchant credentials). ### Module Frontend Routes [](#module-frontend-routes) URLMethodControllerPurpose`/shubo_tbc/payment/params`POST`Params`Get Flitt checkout token (AJAX)`/shubo_tbc/payment/callback`POST`Callback`Server-to-server callback (CSRF exempt)`/shubo_tbc/payment/confirm`POST`Confirm`Frontend payment confirmation (AJAX)### Module Admin Routes [](#module-admin-routes) URLControllerPurpose`/shubo_tbc/order/checkStatus``CheckStatus`Query Flitt API and sync order status`/shubo_tbc/order/capture``Capture`Capture a pre-authorized payment`/shubo_tbc/order/voidPayment``VoidPayment`Void payment and cancel order`/shubo_tbc/order/settle``Settle`Trigger manual settlementLogging ------- [](#logging) All module logs are written to a dedicated file: ``` var/log/shubo_tbc_payment.log ``` 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 --------- [](#cron-jobs) JobSchedulePurpose`shubo_tbc_pending_order_reconciler`Every 5 minutesChecks orders in `pending_payment` state older than 15 minutes. Queries Flitt API and processes approved/declined/expired orders. Max 50 orders per run.Internationalization -------------------- [](#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 --------------- [](#troubleshooting) ### Payment form does not load [](#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" [](#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 [](#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 [](#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 [](#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 ------- [](#license) Apache License 2.0. See [LICENSE](LICENSE) for details. Copyright 2026 Nikoloz Shubitidze (Shubo). ### Health Score 36 — LowBetter than 79% of packages Maintenance86 Actively maintained with recent releases Popularity2 Limited adoption so far Community8 Small or concentrated contributor base Maturity42 Maturing project, gaining track record Bus Factor1 Top contributor holds 96.9% of commits — single point of failure 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 85d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/25e03e1c788be1ce1b2067241fb98d4b40e916fb9e9ea61d257a06ce871db916?d=identicon)[shubodev](/maintainers/shubodev) --- Top Contributors [![fl0px](https://avatars.githubusercontent.com/u/87697481?v=4)](https://github.com/fl0px "fl0px (31 commits)")[![nshubitidze](https://avatars.githubusercontent.com/u/64857194?v=4)](https://github.com/nshubitidze "nshubitidze (1 commits)") --- Tags paymentgeorgiamagento2tbcflitt ### Embed Badge ![Health badge](/badges/shubo-module-tbc-payment/health.svg) ``` [![Health](https://phpackages.com/badges/shubo-module-tbc-payment/health.svg)](https://phpackages.com/packages/shubo-module-tbc-payment) ``` ### Alternatives [mollie/magento2 Mollie Payment Module for Magento 2 1131.9M16](/packages/mollie-magento2)[buckaroo/magento2 Buckaroo Magento 2 extension 32420.3k8](/packages/buckaroo-magento2)[paynl/magento2-plugin Pay. Payment methods for Magento 2 31329.9k6](/packages/paynl-magento2-plugin)[amzn/amazon-pay-magento-2-module Official Magento2 Plugin to integrate with Amazon Pay 108531.2k1](/packages/amzn-amazon-pay-magento-2-module)[run-as-root/magento2-prometheus-exporter Magento2 Prometheus Exporter 68357.9k](/packages/run-as-root-magento2-prometheus-exporter)[vipps/module-payment Vipps MobilePay Payment Module for Magento 2 1098.4k](/packages/vipps-module-payment) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)