PHPackages shubo/module-bog-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-bog-payment ActiveMagento2-module[Payment Processing](/categories/payments) shubo/module-bog-payment ======================== Bank of Georgia (BOG) iPay payment integration for Duka marketplace v1.1.4(2mo ago)02Apache-2.0PHPPHP >=8.4 Since May 1Pushed 2mo agoCompare [ Source](https://github.com/nshubitidze/module-bog-payment)[ Packagist](https://packagist.org/packages/shubo/module-bog-payment)[ Docs](https://github.com/nshubitidze/module-bog-payment)[ RSS](/packages/shubo-module-bog-payment/feed)WikiDiscussions main Synced 3w ago READMEChangelogDependencies (6)Versions (7)Used By (0) Shubo\_BogPayment -- Bank of Georgia (iPay) Payment Module for Magento 2 ======================================================================== [](#shubo_bogpayment----bank-of-georgia-ipay-payment-module-for-magento-2) [![Packagist](https://camo.githubusercontent.com/8ed09261d7e1c853975c04563eb41d0af615d78c03fa00f4b3d0ae89d442906d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7061636b61676973742d736875626f2532466d6f64756c652d2d626f672d2d7061796d656e742d6f72616e67652e737667)](https://packagist.org/packages/shubo/module-bog-payment)[![License: Apache 2.0](https://camo.githubusercontent.com/a549a7a30bacba7bfceebdc207a8e86c3f2c02995a2527640dca30048fd2b64e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d417061636865253230322e302d626c75652e737667)](./LICENSE)[![Magento](https://camo.githubusercontent.com/128e86f84d29af29a2ac8a6d0c378d4c819f7384260c3da4337578b4dfdf918a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4d6167656e746f2d322e342e782d3861326265322e737667)](https://magento.com) Bank of Georgia payment integration for Magento 2 using the BOG Payments REST API. Customers are redirected to the BOG-hosted payment page to complete their payment and returned to your store afterward. > **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\_BogPayment integrates Bank of Georgia payments into Magento 2 via the BOG Payments API (also known as iPay). The module uses a **redirect-based flow**: the customer clicks "Place Order", is redirected to the BOG-hosted payment page, and returns to the store after payment completes. Key highlights: - Redirect to BOG-hosted payment page - OAuth2 client credentials authentication - Pre-authorization (manual capture) and automatic capture modes - Full and partial refunds via Magento credit memos - Multiple payment methods: Card, Google Pay, Apple Pay, BOG P2P, BOG Loyalty - Split payments for marketplace/multi-vendor scenarios (via IBAN-based distribution) - SHA256withRSA callback signature verification - Server-to-server callback + cron reconciler for reliable order processing - Country restriction support - Light/Dark payment page themes **Key design decision**: The Magento order is created *after* the customer returns from the BOG payment page with a successful payment, not before. This prevents ghost orders from abandoned payment flows. Requirements ------------ [](#requirements) RequirementVersionMagento2.4.8+PHP8.4+`magento/framework`\*`magento/module-payment`\*`magento/module-sales`\*`magento/module-checkout`\*`magento/module-store`\*`magento/module-backend`\*You need a **BOG Payments API account** with a Client ID and Client Secret. These are obtained from the Bank of Georgia merchant portal. No external PHP SDK dependency is required -- the module communicates directly with the BOG REST API using cURL. Installation ------------ [](#installation) ### Via Composer (recommended) [](#via-composer-recommended) ``` composer require shubo/module-bog-payment bin/magento module:enable Shubo_BogPayment bin/magento setup:upgrade bin/magento cache:flush ``` ### Manual Installation [](#manual-installation) 1. Copy the module files to `app/code/Shubo/BogPayment/`. 2. Enable and install: ``` bin/magento module:enable Shubo_BogPayment bin/magento setup:upgrade bin/magento cache:flush ``` Configuration ------------- [](#configuration) Navigate to **Stores > Configuration > Sales > Payment Methods > BOG Payments (Bank of Georgia)**. ### Credentials [](#credentials) FieldDescription**Enabled**Enable or disable the payment method.**Title**Display name shown to customers at checkout. Default: `BOG Payments`.**Environment**`Test` or `Live`. Controls which credentials and environment are active.**Client ID**Your BOG Payments API client ID.**Client Secret**Your BOG Payments API client secret. Stored encrypted.### Payment Settings [](#payment-settings) FieldDescription**Payment Action**`Automatic Capture` (default) -- charges immediately and creates an invoice. `Manual Capture` -- pre-authorizes funds, requiring manual capture from admin.**API URL**Base URL for the BOG Payments API. Default: `https://api.bog.ge/payments/v1`.**OAuth URL**OAuth2 token endpoint URL. Default: `https://oauth2.bog.ge/auth/realms/bog/protocol/openid-connect/token`.**Payment Lifetime (minutes)**How long the payment session stays valid. Default: 15 minutes. Range: 2 to 1440 (24 hours).**Payment Page Theme**`Light` or `Dark` theme for the BOG-hosted payment page.**Allowed Payment Methods**Multi-select: Card, Google Pay, Apple Pay, BOG P2P, BOG Loyalty.**Debug**When enabled, logs all API requests and responses to the dedicated log file.**New Order Status**Initial order status. Default: `pending_payment`.**Sort Order**Controls the display order of the payment method at checkout.### Country Restrictions [](#country-restrictions) FieldDescription**Payment from Applicable Countries**All Allowed Countries or Specific Countries.**Payment from Specific Countries**If "Specific Countries" is selected, only these countries can use this payment method.### Split Payments [](#split-payments) FieldDescription**Enable Split Payments**Enable fund distribution to multiple BOG merchants.**Auto-Settle After Approval**Automatically distribute funds when payment is approved.**Split Receivers**Dynamic rows table. Each row has: IBAN, Amount Type (Percentage or Fixed), Amount, Description.Config paths (for programmatic access): ``` payment/shubo_bog/active payment/shubo_bog/title payment/shubo_bog/environment payment/shubo_bog/client_id payment/shubo_bog/client_secret payment/shubo_bog/api_url payment/shubo_bog/oauth_url payment/shubo_bog/payment_action_mode payment/shubo_bog/payment_lifetime payment/shubo_bog/payment_theme payment/shubo_bog/payment_methods payment/shubo_bog/split_enabled payment/shubo_bog/split_auto_settle payment/shubo_bog/split_receivers payment/shubo_bog/debug payment/shubo_bog/order_status payment/shubo_bog/sort_order payment/shubo_bog/allowspecific payment/shubo_bog/specificcountry ``` Supported Features ------------------ [](#supported-features) FeatureStatusDetailsRedirect-based paymentSupportedCustomer redirected to BOG-hosted payment pageCard paymentsSupportedVisa, Mastercard, etc. via BOGGoogle PaySupportedConfigurable in Allowed Payment MethodsApple PaySupportedConfigurable in Allowed Payment MethodsBOG P2PSupportedConfigurable in Allowed Payment MethodsBOG LoyaltySupportedConfigurable in Allowed Payment MethodsAutomatic Capture (auto-invoice)SupportedPayment charged on approval, invoice created automaticallyManual Capture (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 orderFull refundSupportedVia Magento credit memoPartial refundSupportedVia Magento credit memo with partial amountServer-to-server callbacksSupportedBOG POSTs to `/shubo_bog/payment/callback`SHA256withRSA signature verificationSupportedVerifies callback authenticity using BOG's RSA public keyStatus API fallback verificationSupportedFalls back to checking BOG Receipt API if signature verification failsCron reconcilerSupportedChecks stuck orders every 5 minutesManual status check from adminSupported"Check BOG Status" button queries API and syncs orderSplit payments (IBAN-based)SupportedFund distribution to sub-merchants via IBAN + percentageOAuth2 authenticationSupportedClient credentials grant with automatic token refreshMulti-currencySupportedSends quote currency code to BOGMulti-store / multi-websiteSupportedAll config fields are website-scopedCountry restrictionsSupportedAllow all or specific countriesPayment info in adminSupportedShows BOG Order ID, status, card type, PAN, payment methodLocalization (EN/KA)SupportedPayment page and API requests use store localePayment page themeSupportedLight or Dark theme for the BOG payment pageSensitive data protectionSupportedClient secret encrypted in configOrder confirmation emailsSupportedSent after payment is confirmedIdempotencySupportedUUID v4 Idempotency-Key header on create-order requestsUnsupported Features -------------------- [](#unsupported-features) FeatureStatusEmbedded payment form (no redirect)Not implemented (redirect only)Recurring / subscription paymentsNot implementedSaved card / tokenizationNot implementedInstallment paymentsNot implementedPartial capture of pre-authorized amountSupported but untested -- the capture API call sends the full amountAdmin order creation (phone orders)Not supported (`can_use_internal` = 0)Settlement API for split distributionThe split data is sent at order creation time via the `config.split` payload, not as a separate post-payment settlement call (unlike the TBC module)Multiple address checkoutDisabled in `payment.xml`Payment Flow ------------ [](#payment-flow) ``` Customer selects BOG payment at checkout | v Customer clicks "Place Order" -> JS calls POST /shubo_bog/payment/initiate -> Backend authenticates via OAuth2 (client_credentials) -> Backend calls BOG API: POST /ecommerce/orders -> BOG returns order ID + redirect URL -> Frontend redirects to BOG payment page | v Customer completes payment on BOG page (Card entry, 3DS, Google Pay, etc.) | +-----+-----+ | | Success Failure | | v v Redirect to Redirect to /shubo_bog/ checkout/ payment/return onepage/failure | v ReturnAction controller: -> Checks BOG Status API (GET /receipt/{id}) -> If completed: creates Magento order, captures, invoices -> If pending: creates order in pending_payment state -> Redirects to success page | v (Meanwhile) BOG sends POST callback to /shubo_bog/payment/callback -> Verifies SHA256withRSA signature (or falls back to Status API) -> Updates order if not already processed -> Sends order confirmation email | v (Every 5 min) Cron reconciler checks stuck orders -> Queries BOG Status API -> Processes completed / cancels failed or expired ``` **Key design decision**: No Magento order exists until the customer returns from BOG. The `Initiate` controller works with the quote only. The `ReturnAction` controller creates the actual Magento order via `CartManagementInterface::placeOrder()`. This prevents ghost orders. Order Status Flow ----------------- [](#order-status-flow) ``` Customer returns from BOG | +---+---+ | | Success Pending | | v v processing pending_payment (invoice) | +----+----+ | | | Approved Failed Expired | | | v v v processing canceled canceled (invoice) If Payment Action = "Manual Capture": Success ──> 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 BOG merchants. This is designed for marketplace scenarios. ### How It Works (BOG) [](#how-it-works-bog) Unlike the TBC/Flitt module which uses a post-payment settlement API, the BOG module sends split payment data **at order creation time** as part of the create-order API request: ``` { "config": { "split": { "split_payments": [ { "iban": "GE12TB1234567890123456", "percent": 60.0, "description": "Vendor payment" } ] } } } ``` ### Configuration Methods [](#configuration-methods) **Admin-configured receivers** (static): Set fixed receivers in the admin panel using IBANs. **Event-based receivers** (dynamic): Other modules can listen to the `shubo_bog_payment_split_before` event and call `addSplitPayment()` on the `SplitPaymentDataInterface` object. ### Key Differences from TBC Module [](#key-differences-from-tbc-module) AspectTBC (Flitt)BOGSplit identifierMerchant ID (Flitt)IBAN (bank account)Split timingPost-payment settlement APIAt order creation timeAmount typesFixed + PercentagePercentage only (in API payload)Settlement buttonYes (manual trigger)No (sent with order)Admin Actions ------------- [](#admin-actions) The following buttons appear on the order view page for BOG-paid orders: ButtonAppears WhenAction**Check BOG Status**Any BOG order with a BOG order IDQueries BOG Status API, displays status, auto-processes if completed**Capture Payment**Pre-authorized order (not yet captured)Sends capture request to BOG API, creates invoice**Void Payment**Pre-authorized order (not yet captured)Cancels the Magento order; hold expires on bank sideTechnical Architecture ---------------------- [](#technical-architecture) ### Key Classes [](#key-classes) ClassPurpose`Gateway\Config\Config`Configuration reader; URL builders for all API endpoints`Gateway\Http\Client\CreatePaymentClient`Creates orders via BOG `/ecommerce/orders` with OAuth2 bearer token`Gateway\Http\Client\RefundClient`Sends refunds via BOG `/checkout/refund``Gateway\Http\Client\CaptureClient`Captures pre-authorized payments via `/payment/authorization/approve/{id}``Gateway\Http\Client\StatusClient`Checks status via `/receipt/{id}``Gateway\Request\InitializeRequestBuilder`Builds the create-order request with basket, URLs, capture mode, TTL`Gateway\Request\RefundRequestBuilder`Builds the refund request with BOG order ID and amount`Gateway\Request\SplitDataBuilder`Adds split payment config to the create-order request`Gateway\Response\InitializeHandler`Stores BOG order ID, redirect URL, details URL on payment`Gateway\Response\RefundHandler`Stores refund status and transaction ID`Gateway\Validator\ResponseValidator`Validates HTTP status codes from BOG API`Gateway\Validator\CallbackValidator`SHA256withRSA signature verification + Status API fallback`Model\OAuthTokenProvider`OAuth2 client\_credentials token management with in-memory caching`Controller\Payment\Initiate`AJAX endpoint: creates BOG order from quote, returns redirect URL`Controller\Payment\ReturnAction`Handles customer return: creates Magento order, processes payment`Controller\Payment\Callback`Server-to-server callback from BOG`Controller\Payment\Confirm`Safety net confirmation endpoint`Cron\PendingOrderReconciler`Reconciles stuck pending orders`Observer\SetPendingPaymentState`Sets order to `pending_payment` on placement`Plugin\AddOrderButtons`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**: `ShuboBogPaymentFacade` (virtual type of `Magento\Payment\Model\Method\Adapter`) - **Command Pool**: `initialize` and `refund` commands - **Request Builders**: Composite builder with `InitializeRequestBuilder` + `SplitDataBuilder` - **HTTP Clients**: Direct cURL calls with OAuth2 bearer token - **Response Handlers**: Store BOG order IDs, redirect URLs, refund status - **Validators**: `ResponseValidator` for HTTP status, `CallbackValidator` for signatures, `CountryValidator` for country restrictions ### OAuth2 Authentication [](#oauth2-authentication) The BOG Payments API uses OAuth2 client credentials grant: - Token endpoint: `https://oauth2.bog.ge/auth/realms/bog/protocol/openid-connect/token` - Grant type: `client_credentials` - Auth: HTTP Basic (Client ID : Client Secret) - Token is cached in memory with a 60-second buffer before expiry ### Callback Signature Verification [](#callback-signature-verification) BOG callbacks include a `Callback-Signature` header containing a base64-encoded SHA256withRSA signature. The module verifies this signature using BOG's RSA public key, which is loaded from encrypted system config at `payment/shubo_bog/rsa_public_key` (Stores → Configuration → Sales → Payment Methods → BOG Payments → RSA Public Key, or via `bin/magento shubo:payment:switch-to-prod:bog --rsa-key-path=...`). If the key is unset or signature verification fails, the module falls back to checking the payment status via the BOG Receipt/Status API. ### Events Dispatched [](#events-dispatched) EventPurpose`shubo_bog_payment_split_before`Allows modules to populate split payment data via `SplitPaymentDataInterface`API Endpoints ------------- [](#api-endpoints) ### BOG Payments API Endpoints Used [](#bog-payments-api-endpoints-used) EndpointMethodPurpose`/ecommerce/orders`POSTCreate payment order`/receipt/{order_id}`GETCheck payment status`/checkout/refund`POSTRefund payment`/payment/authorization/approve/{order_id}`POSTCapture pre-authorized paymentBase URL: `https://api.bog.ge/payments/v1` OAuth token endpoint: `https://oauth2.bog.ge/auth/realms/bog/protocol/openid-connect/token` ### Module Frontend Routes [](#module-frontend-routes) URLMethodControllerPurpose`/shubo_bog/payment/initiate`POST`Initiate`Create BOG order and get redirect URL (AJAX)`/shubo_bog/payment/return`GET`ReturnAction`Handle customer return from BOG`/shubo_bog/payment/callback`POST`Callback`Server-to-server callback (CSRF exempt)`/shubo_bog/payment/confirm`POST`Confirm`Safety net payment confirmation (AJAX)### Module Admin Routes [](#module-admin-routes) URLControllerPurpose`/shubo_bog/order/checkStatus``CheckStatus`Query BOG API and sync order status`/shubo_bog/order/capture``Capture`Capture a pre-authorized payment`/shubo_bog/order/voidPayment``VoidPayment`Void payment and cancel orderLogging ------- [](#logging) All module logs are written to a dedicated file: ``` var/log/shubo_bog_payment.log ``` Enable **Debug** mode in configuration to log full API request/response bodies including OAuth token requests, create-order calls, status checks, and callback processing. Cron Jobs --------- [](#cron-jobs) JobSchedulePurpose`shubo_bog_pending_order_reconciler`Every 5 minutesChecks orders in `pending_payment` state older than 15 minutes. Queries BOG Status API and processes completed/failed/expired orders. Max 50 orders per run.Internationalization -------------------- [](#internationalization) The module includes translations for: - **English** (`en_US`) - **Georgian** (`ka_GE`) The BOG payment page language is automatically set based on the Magento store locale via the `Accept-Language` header on API requests. Supported languages: `en`, `ka`. Troubleshooting --------------- [](#troubleshooting) ### Customer redirected but order not created [](#customer-redirected-but-order-not-created) - This is by design. The Magento order is only created when the customer returns from BOG. - If the customer closes the browser on the BOG page, the callback and cron reconciler will not create an order since the quote has not been converted. - Check `var/log/shubo_bog_payment.log` for details. ### Order stuck in "pending\_payment" [](#order-stuck-in-pending_payment) - Use the "Check BOG 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_bog/payment/callback`) is accessible from the internet (HTTPS required). - Check that your OAuth2 credentials are valid and not expired. ### OAuth2 authentication fails [](#oauth2-authentication-fails) - Verify Client ID and Client Secret are correctly set. - Ensure the OAuth URL is correct: `https://oauth2.bog.ge/auth/realms/bog/protocol/openid-connect/token`. - Check if the credentials are for the correct environment (test vs. live). - Check `var/log/shubo_bog_payment.log` for the HTTP response from the token endpoint. ### Callback signature verification fails [](#callback-signature-verification-fails) - The RSA public key is loaded from encrypted admin config at `payment/shubo_bog/rsa_public_key`. If BOG rotates their key, paste the new PEM into the admin field (or re-run `bin/magento shubo:payment:switch-to-prod:bog --rsa-key-path=...`) — no code change. - An empty config (pre-cutover state) logs at INFO; a malformed PEM logs at WARNING. Both fall through to the Status API. - The module falls back to the Status API when signature verification fails, so orders should still process correctly. - Check `var/log/shubo_bog_payment.log` for "signature verification failed" or "not a valid PEM" messages. ### Refund fails [](#refund-fails) - Ensure the BOG order ID is stored on the payment (`bog_order_id` in additional info). - Check `var/log/shubo_bog_payment.log` for the BOG API error response. - Verify your OAuth2 credentials have refund permissions. ### Payment page shows wrong language [](#payment-page-shows-wrong-language) - The language is derived from the Magento store locale. Set the store locale to `ka_GE` for Georgian or any English locale for English. ### Split payments not working [](#split-payments-not-working) - BOG split payments use IBANs, not merchant IDs. - Verify the IBANs are valid Georgian bank accounts. - The split data is sent at order creation time. If the create-order call fails, check the API response in debug logs. - The `shubo_bog_payment_split_before` event must be observed by your module to provide dynamic split data. License ------- [](#license) Apache License 2.0. See [LICENSE](LICENSE) for details. Copyright 2026 Nikoloz Shubitidze (Shubo). ### Health Score 40 — FairBetter than 86% of packages Maintenance84 Actively maintained with recent releases Popularity3 Limited adoption so far Community8 Small or concentrated contributor base Maturity56 Maturing project, gaining track record Bus Factor1 Top contributor holds 97.3% 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 Every ~0 days Total 6 Last Release 82d 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 (36 commits)")[![nshubitidze](https://avatars.githubusercontent.com/u/64857194?v=4)](https://github.com/nshubitidze "nshubitidze (1 commits)") --- Tags paymentgeorgiamagento2ipaybog ### Embed Badge ![Health badge](/badges/shubo-module-bog-payment/health.svg) ``` [![Health](https://phpackages.com/badges/shubo-module-bog-payment/health.svg)](https://phpackages.com/packages/shubo-module-bog-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)[run-as-root/magento2-prometheus-exporter Magento2 Prometheus Exporter 68357.9k](/packages/run-as-root-magento2-prometheus-exporter)[amzn/amazon-pay-magento-2-module Official Magento2 Plugin to integrate with Amazon Pay 108531.2k1](/packages/amzn-amazon-pay-magento-2-module)[vipps/module-payment Vipps MobilePay Payment Module for Magento 2 1098.4k](/packages/vipps-module-payment)[loki/magento2-components Core module for defining Alpine.js components with advanced AJAX features 1011.8k26](/packages/loki-magento2-components) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)