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

Shubo_BogPayment -- Bank of Georgia (iPay) Payment Module for Magento 2

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

• 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_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

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

Via Composer (recommended)

Manual Installation

1. Copy the module files to app/code/Shubo/BogPayment/.
2. Enable and install:

Configuration

Navigate to Stores > Configuration > Sales > Payment Methods > BOG Payments (Bank of Georgia).

Credentials

Payment Settings

Country Restrictions

Split Payments

Config paths (for programmatic access):

Supported Features

Unsupported Features

Payment Flow

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

Split Payments (Marketplace)

Split payments allow distributing order funds to multiple BOG merchants. This is designed for marketplace scenarios.

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:

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

Admin Actions

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

Technical Architecture

Key Classes

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

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

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

API Endpoints

BOG Payments API Endpoints Used

Base 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 Admin Routes

Logging

All module logs are written to a dedicated file:

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

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

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"

• 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

• 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

• 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

• 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

• 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

• 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

Apache License 2.0. See LICENSE for details.

Copyright 2026 Nikoloz Shubitidze (Shubo).