Checkout & Gateways Chapter 12 of 22

Chapter 12: Payment Gateways & Visual Logos Hub

Production payment configurations (Stripe, PayPal, SSLCommerz, CoinGate, Cash on Delivery, Manual Transfer) and high-res checkout logos.

Production Ready

Engineered for mission-critical enterprise commerce with zero latency overhead.

Granular Controls

Fully customizable via the modern MartX Admin Dashboard with real-time feedback.

Instant Sync

Automated state propagation across multi-device clients, cache, and database layers.

Module Architecture & Workflow

This chapter details the comprehensive configuration, operational controls, and best practices for Chapter 12: Payment Gateways & Visual Logos Hub. Follow the guided procedures below to maintain peak operational performance and security.

Admin Navigation Path:
Admin Dashboard > Ecommerce & Sales > Payment Gateways > Gateway Settings

12.1 Gateway Selection Console & Architectural Overview

MartX provides a unified, enterprise-grade payment processing architecture supporting 6 core payment methods across credit/debit cards, digital wallets, domestic Bangladesh banking, borderless cryptocurrency rails, and localized offline payments. Administrators manage all payment channels through the centralized Gateway Settings console (Ecommerce & Sales > Payment Gateways > Gateway Settings).

Global Cards

Stripe (Cards, Apple Pay, Google Pay)

Global Wallet

PayPal (Express Checkout & Wallet)

Local Gateway

SSLCommerz (bKash, Nagad, BD Cards)

Crypto Rails

CoinGate (BTC, ETH, 70+ Coins)

Doorstep COD

Cash on Delivery (Advance / Full)

Manual Direct

Manual Payment (Bank Wire & TrxID)

Visual Flowchart: Customer Checkout & Payment Routing Engine

When a customer reaches the MartX checkout page, the routing engine processes transactions across three primary channels:

Channel 1
Online Gateways

Stripe • PayPal • SSLCommerz • CoinGate

Success: Order PAID & Stock Locked Abandoned: Web Cron Auto-Cancels
Channel 2
Cash on Delivery

Doorstep Payment Collection

Advance Shipping: Pay Delivery Fee First Standard COD: Pay Full Amount at Door
Channel 3
Manual Transfer

Direct Bank Wire • Personal Mobile Money

Buyer Submits TrxID in Checkout Store Admin Confirms & Approves
Multi-Currency Exchange Rate Engine:

When your storefront operates in a regional base currency (such as BDT or EUR) while utilizing international gateways that settle in USD (such as PayPal or CoinGate), the administrative console provides a dedicated Exchange Rate Field. The checkout engine converts order subtotals by this multiplier in real time, ensuring accurate international billing without discrepancy.

Multi-Currency Exchange Rate Reference Matrix
Market-Driven • Dynamic Floating Rates
Notice: Rates Below Are Illustrative Real-World Examples:

Foreign exchange currency rates fluctuate based on international forex markets and central bank regulations. The numerical conversion rates shown below are illustrative examples (নমুনা উদাহরণ) to explain calculation logic. Store administrators must input their current, actual live exchange rates corresponding to active bank or settlement terms.

Store Base Currency Gateway Configured Admin Input Field Sample Value Checkout Result
BDT (৳) - Bangladeshi Taka PayPal Express 1 USD = ? Base Currency 122.50 A ৳1,225 cart charges $10.00 USD at checkout \((1225 \div 122.50)\).
BDT (৳) - Bangladeshi Taka CoinGate (Crypto) 1 USD = ? Base Currency 122.50 Locks a $10.00 USD equivalent in BTC/ETH for 20 minutes.
EUR (€) - Euro PayPal / CoinGate 1 USD = ? Base Currency 0.92 A €92 cart charges $100.00 USD on PayPal.
USD ($) - US Dollar PayPal / Stripe / CoinGate 1 USD = ? Base Currency 1.00 A $50.00 cart charges exactly $50.00 USD (1:1 parity).

12.2 Global Card & Mobile Wallet Processing: Stripe

Stripe is the premier international card processing infrastructure for MartX. It accepts all major credit and debit cards (Visa, MasterCard, American Express, Discover, JCB) alongside 1-click mobile wallets including Apple Pay and Google Pay via Stripe Elements.

Admin Panel — Stripe Configuration: Global Cards, Apple Pay & Google Pay
Stripe Gateway Configuration (images/payments/admin_gateway_stripe.png)
Interactive Full-Screen Lightbox enabled. Click image or "Full View" to zoom. Stripe Processing Engine
Stripe Parameter Specification
Field Name Sample Value Merchant Operational Purpose
Status Toggle Active / Inactive Enables or disables Stripe across customer checkout without erasing stored API credentials.
Stripe Key * pk_test_... / pk_live_... Your Stripe Publishable API key. Used on customer checkout for direct client-side tokenization (PCI-DSS compliant).
Stripe Secret * sk_test_... / sk_live_... Your confidential Stripe Secret API key. Securely stored and used server-side to authorize payment charges.
Webhook Secret (Optional) whsec_... Allows Stripe servers to send asynchronous background notifications when payments succeed or fail.

12.3 Global Digital Wallet & Express Checkout: PayPal

PayPal offers worldwide brand recognition, enabling buyers to pay with their stored PayPal wallet balances, linked bank accounts, or debit/credit cards without entering card details on your website.

Admin Panel — PayPal Configuration: Global Express Checkout & Wallets
PayPal Gateway Configuration (images/payments/admin_gateway_paypal.png)
Dual-mode Sandbox & Live credential configuration with instant dropdown selector. PayPal Express Engine
PayPal Parameter Specification
Field Name Configuration Type Merchant Operational Purpose
Exchange Rate * 1 USD = ? Base Currency Multiplies checkout subtotals into equivalent USD for PayPal settlement. If your store currency is USD, set to 1.00. Never enter 0.
Environment Mode Sandbox / Live Switch between Sandbox test mode and Live production payments with a single click.
Sandbox Credentials Client ID & Secret Test credentials obtained from PayPal Developer Portal (Apps & Credentials > Sandbox).
Live Credentials Client ID & Secret Production credentials from your verified business PayPal account for processing real customer payments.

12.4 Bangladesh Domestic Payment Gateway: SSLCommerz

SSLCommerz is Bangladesh's premier licensed payment aggregator. It enables eCommerce stores to accept payments from bKash, Nagad, Rocket, Upay, domestic and international Visa/MasterCard, and internet banking portals across all major Bangladeshi commercial banks.

Admin Panel — SSLCommerz Configuration: Bangladesh Cards, bKash, Nagad & Rocket
SSLCommerz Gateway Configuration (images/payments/admin_gateway_sslcommerz.png)
Domestic card & MFS aggregator integration with 3D-Secure bank OTP handling. SSLCommerz Aggregator
SSLCommerz Parameter Specification
Field Name Input Format Merchant Operational Purpose
Environment Mode Sandbox / Live Toggle between the SSLCommerz testing sandbox and active production gateway.
Store ID * Text string Unique merchant store identifier issued during SSLCommerz merchant onboarding.
Store Password * Password / Key Secure authentication secret provided by SSLCommerz for encrypted server-to-server API validation.

12.5 Borderless Web3 & Cryptocurrency Processing: CoinGate

For global decentralized commerce, MartX integrates CoinGate, enabling customers to pay using Bitcoin (BTC), Ethereum (ETH), Tether (USDT), Litecoin (LTC), and 70+ leading cryptocurrencies with automated invoice rate locking.

Admin Panel — CoinGate Configuration: Bitcoin, Ethereum & 70+ Leading Cryptocurrencies
CoinGate Gateway Configuration (images/payments/admin_gateway_coingate.png)
Multi-coin invoice generation with dynamic network rate locking. CoinGate Crypto Platform
CoinGate Parameter Specification
Field Name Configuration Type Merchant Operational Purpose
Exchange Rate * 1 USD = ? Base Currency Converts store order totals into USD before creating the CoinGate cryptocurrency payment invoice.
Environment Mode Sandbox / Live Toggle between the CoinGate Sandbox (testnet cryptocurrency) and Live production blockchain network.
Auth Token * API Secret Token CoinGate API authentication token generated from your CoinGate merchant portal under API > Apps.

12.6 Cash on Delivery (COD) & Advance Shipping Charge Enforcement

Cash on Delivery is a vital payment method in emerging markets but carries high return and refusal risks (RTO). MartX features a sophisticated Advance Delivery Charge Architecture that eliminates fake orders by requiring buyers to pay the courier shipping fee online before confirming their COD shipment.

Admin Panel — Cash On Delivery: Advance Shipping Charge & Mandatory Method Selection
Cash On Delivery Configuration Interface (images/payments/admin_gateway_cod.png)
Live Screenshot: Red warning banner enforcing minimum 1 active advance payment method. Advance COD Security
Mandatory Selection Validation Architecture
1. Client-Side Instant Prevention

When "Require Advance Shipping Charge?" is toggled ON, the system inspects the Allowed Advance Payment Methods checkboxes. If an administrator clicks "Save And Update" without selecting at least one active gateway, submission is halted instantly (e.preventDefault()), the screen scrolls smoothly to the container, and an inline red warning is revealed: "Selection Required: Please select at least one active payment gateway to collect advance shipping charges."

2. Server-Side Backend Safeguard

The backend controller (PaymentMethodController::updateGateways) strictly validates that when payment_cod_advance_shipping == '1', the payment_cod_advance_methods payload must not be empty. Any malformed request is rejected with a session flash error, completely preventing database corruption or headless checkout deadlocks.

12.7 Manual Bank & Direct Mobile Transfers (Manual Payment)

For stores accepting direct bank wire transfers, offline deposits, or personal mobile wallet "Send Money" transactions (bKash/Nagad personal numbers), the Manual Payment module allows administrators to specify custom buyer instructions.

Admin Panel — Manual Payment Configuration: Direct Transfer Instructions & TrxID Protocols
Manual Payment Configuration Interface (images/payments/admin_gateway_manual.png)
Rich text instructions rendered directly on the customer checkout modal. Manual Payment
Manual Payment Customer Instruction Best Practices

In the Payment Instructions for Customers textarea, clearly state:

  1. Your exact Bank Account Number, Routing Number, and Account Name.
  2. Personal bKash / Nagad / Rocket numbers if using direct mobile transfers.
  3. Instruction for the buyer to submit their bank deposit slip or Mobile Transaction ID (TrxID) into the checkout notes.

12.7.1 Direct Bank Transfer & Extended Gateways Pipeline (Paystack, Razorpay, BinancePay, WayForPay)

In addition to standard manual mobile payments, MartX incorporates a dedicated Direct Bank Transfer enum case (PaymentMethodEnums::BANK_TRANSFER) for high-value B2B invoicing, wholesale checkouts, and international SWIFT/IBAN wire remittances. Furthermore, the core framework comes with pre-configured, CSRF-exempted webhook callback endpoints for regional international expansion:

Paystack (Africa)

Nigeria, Ghana, Kenya & South Africa card and mobile money processing.

/payment/paystack/callback
Razorpay (India)

UPI, NetBanking, RuPay, and domestic Indian digital wallets.

/payment/razorpay/callback
BinancePay (Crypto)

Instant Web3 crypto payment via QR code and Binance App wallet.

/payment/binancepay/callback
WayForPay (E. Europe)

Fast checkout for Ukraine, Poland, and international multi-currency cards.

/payment/wayforpay/callback
Zero-Configuration CSRF Exemption: In bootstrap/app.php, all callback endpoints (/payment/stripe/webhook, /payment/ssl/*, /payment/coingate/callback, /payment/paystack/callback, /payment/razorpay/callback, /payment/binancepay/callback, /payment/wayforpay/callback) are pre-whitelisted in validateCsrfTokens(), eliminating 419 Page Expired errors when remote payment servers send background IPN status notifications.

12.8 Payment Logos & Visual Trust Badges Hub (Storefront Footer & Checkout)

Beyond backend transaction processing, displaying recognized payment brand logos (MasterCard, Visa, bKash, PayPal, Amex) on the storefront Footer and checkout summary is proven to enhance buyer confidence and checkout conversion rates. The Payment Logos Console (Ecommerce & Sales > Payment Gateways > Payment Logos) manages these visual assets.

Admin Panel — Payment Methods Information: Visual Logos Directory & Add Console
Payment Logos Management Interface (images/payments/admin_payment_methods_table.png)
Drag-and-drop position ordering on the left; instant creation on the right. Visual Logos Hub
Admin Panel — Edit Payment Method: master card — Asset Revision Console
Edit Payment Method Interface (images/payments/admin_payment_method_edit.png)
Live asset preview with one-click Media Manager asset replacement. Payment Logo Revision
Payment Logos Management Interface Elements
Control / Column UI Interaction Storefront Operational Impact
Drag Handle (SL) ::: 1, ::: 2 Drag-and-drop table row reordering via HTML5 draggable JS. Controls the exact horizontal sequence of payment logos displayed across the storefront website footer.
LOGO Preview Thumbnail Image Tag Displays a crisp thumbnail of the brand asset (PNG, SVG, WEBP) currently published in the database.
Payment Method Name * Text Input (Required) Brand title (e.g., master card, visa card, bKash). Used as the image alt tag for accessibility and SEO compliance.
Logo Image * (Media Manager) Select Image Launches the central MartX Media Manager modal. Allows instant asset selection from uploaded media or direct disk upload.
Action Dropdown Contextual Menu Provides immediate administrative access to Edit the record or Delete the brand asset from the storefront footer.

12.9 Payment Settlement, Webhooks & Security SOP

Adhere to enterprise financial engineering best practices when deploying live payment channels on MartX:

Security & Key Management
  • Encrypted Credential Storage: All Secret Keys, Auth Tokens, and Passwords are automatically AES-256 encrypted in the database before storage.
  • Sandbox Verification: Always run complete checkout transactions using Sandbox test cards before flipping environment toggles to Live Mode.
  • Webhook URL Whitelisting: Configure your gateway portal webhooks to point to your store's secure SSL endpoint to guarantee instant payment state callbacks.
Financial Accounting & Conversion
  • Never Enter 0 for Exchange Rates: Setting an exchange rate to 0 causes payment calculation failure. If your store currency matches the gateway, set it to 1.00.
  • Mitigate COD Abandonment: Keep Require Advance Shipping Charge? active to ensure customer commitment and protect logistics capital.
  • Footer Trust Badges: Keep 4–6 high-resolution payment logos in the visual logos hub to optimize buyer checkout conversion.

12.10 Payment Logs & Forensic Financial Audit Hub

MartX includes a centralized Payment & Financial Audit Hub designed specifically for store owners, accountants, and financial auditors. While the standard Order Management screen tracks packages, shipping labels, and fulfillment statuses, this hub acts as an immutable legal ledger of raw gateway callbacks, settlement figures, and bank communication records.

How to Access the Hub: Navigate to Admin Dashboard → Payment Gateways → Payment & Audit Logs.
Executive Financial Telemetry Cards

Four executive cards provide an instant snapshot of your store's digital cashflow and checkout conversion efficiency:

Settled Revenue

Total confirmed digital revenue successfully captured and credited across all gateways for the selected period.

Settlement Rate (%)

Percentage of initiated payment attempts that resulted in successful settlements vs customer drop-offs.

Auto-Cancellations

Orders where customers abandoned checkout midway, automatically cancelled and inventory restocked by background cron rules.

Declined / Failed

Transactions rejected by issuing banks (e.g., insufficient balance, expired cards, or incorrect CVV) requiring forensic review.

Multi-Criteria Filtering with Instant AJAX Live Sync

The audit toolbar provides instant, zero-reload filtering. Whenever you select an option, the page seamlessly updates both the data table and the top 4 metric cards simultaneously:

  • All Gateways Filter: Isolate transactions by provider: Stripe, PayPal, SSLCommerz, or CoinGate.
  • All Statuses Filter: Filter by outcome: SUCCESS, FAILED, or PENDING.
  • Date Range Filter: Fast presets for Today, Yesterday, This Week, Last 7 Days, This Month, Last Month, This Year, or a custom calendar date picker.
  • Live Debounced Search: Find transactions by Order Number (e.g., #ORD-202610...), Customer Name, Email, or Gateway.
  • Floating Reset Button: A subtle floating pill bar appears when filters are active, allowing one-click restoration to all-time view.
Forensic Payload Inspector: Resolving Customer Disputes & Chargebacks

When a customer claims funds were deducted or when an issuing bank requests verification for a disputed charge, clicking the Inspect button on any row opens the dark-themed Forensic Payload Modal:

Gateway Response / Webhook Tab

Displays the authentic, raw response sent back by Stripe, PayPal, or SSLCommerz. Includes the official Gateway Transaction ID, customer card brand (Visa, Mastercard), last 4 digits, and exact bank failure codes (e.g., insufficient_funds, do_not_honor).

One-Click Clipboard Copy

Store managers can click the Copy button to instantly copy the complete technical payload to the clipboard, providing definitive proof to submit directly to payment gateway support or banking dispute portals.

Export Audit (CSV) for Accounting & Tax Filing: Click the green Export Audit (CSV) button at the top right of the page to download a filtered, Excel-compliant spreadsheet containing exact timestamps, customer details, gateways, amounts, and settlement statuses for your CA firm or tax filings.
Documentation
⚡ 3-Minute Quick Start 1. Introduction & Overview 2. Server Requirements 3. Installation Guide 4. License Activation 5. Dashboard Telemetry 6. Media Manager 7. Catalog Management 8. Products Management 9. Orders & Fulfillment 10. Couriers & Shipping Costs 11. Coupons & Marketing 12. Payment Gateways 13. Theme Layouts Hub 14. Navigation & Mega Menus 15. Sliders & Banners 16. Pages, FAQ & About 17. Blogs & Editorial 18. Reviews & Messages 19. Team Members & Staff Roles 20. Locations & Coverage 21. System Settings Hub 22. Web Cron & FAQs 23. Extra Security & Speed Boost