Skip to main content

Header

BDX Payment Overview & Supported Gateways

BDX.market is Bangladesh's premier gaming and digital goods escrow marketplace. To protect both buyers and sellers against fraud, account recovery scams, and non-delivery, BDX operates a strict buyer protection escrow architecture.

Under this architecture, when a buyer pays for an offer or top-up, funds are not sent directly to the seller's personal account. Instead, payments are securely captured and held by BDX. market in escrow until the order is successfully delivered and verified by the buyer or until the standard 7-day buyer protection window passes.

This document details the payment ecosystem powering BDX.market, including system configuration, active payment drivers, fees, security models, and provider technical specs.

Supported Payment Gateways & Adapters​

BDX.market implements a pluggable gateway architecture defined under App\Support\Payments\PaymentGatewayManager. The system dynamically selects and initializes payment providers based on environment configuration (.env) and site-wide administrative flags managed via App\Support\BdxSettings.

                      +----------------------------------+
                      |   PaymentGatewayManager          |
                      |   App\Support\Payments           |
                      +-----------------+----------------+
                                        |
      +--------------------+------------+------------+--------------------+
      |                    |                         |                    |
+-----v-------+    +-------v------+          +-------v------+     +-------v------+
|  Manual     |    |   PipraPay   |          |     EPS      |     | WooCommerce  |
|  Gateway    |    |   Gateway    |          |   Gateway    |     | Bridge (WC)  |
+-------------+    +--------------+          +--------------+     +--------------+
(bKash/Nagad/      (Self-hosted              (BB-Licensed         (Legacy WP/WC
 Rocket Proofs)     bKash/Nagad/              Aggregator           Integration)
                    Cards API)                Cards/MFS)

1. Manual Gateway (manual)​

  • Class: App\Support\Payments\ManualPaymentGateway
  • Supported Channels: Direct bKash, Nagad, Rocket, or Bank Transfers.
  • Mechanism: Buyers submit payment manually to administrative bKash/Nagad merchant/personal numbers provided during checkout, then upload proof of payment (Transaction ID and/or screenshot). Admins review the submission via the Filament Admin Panel (App\Filament\Resources\MarketplacePaymentResource) and approve or reject the proof.
  • Use Case: Zero gateway processing fee mode; default out-of-the-box system state.

2. PipraPay Gateway (piprapay)​

  • Class: App\Support\Payments\PipraPayGateway

  • Supported Channels: Automated bKash, Nagad, Rocket, Upay, Visa, MasterCard.

  • Mechanism: A self-hosted Bangladeshi automated payment gateway integration. It initiates charges via a RESTful API (POST /api/create-charge) and returns a hosted payment page URL (pp_url). After the buyer completes payment, PipraPay issues a server-to-server webhook containing an API key header (mh-piprapay-api-key). BDX double-verifies every transaction server-side via POST /api/verify-payments using the transaction reference (pp_id) before releasing escrow.

  • Configuration Requirements:

    BDX_PIPRAPAY_ENABLED=true
    BDX_PIPRAPAY_BASE_URL=https://your-piprapay-instance.com
    BDX_PIPRAPAY_API_KEY=your_secret_api_key
    BDX_PIPRAPAY_CURRENCY=BDT

3. EPS — Easy Payment System Gateway (eps)​

  • Class: App\Support\Payments\EpsPaymentGateway

  • Supported Channels: Bangladesh Bank-licensed aggregator covering major Bangladeshi bank cards, bKash, Nagad, Rocket, CellFin, and tap.

  • Mechanism: Fully automated hosted-redirect flow.

    1. Authenticates with EPS servers (POST /v1/Auth/GetToken) using an HMAC-SHA512 x-hash signature to receive an API bearer token.
    2. Initializes transaction (POST /v1/EPSEngine/InitializeEPS) with store credentials and parameters, obtaining an EPS RedirectURL.
    3. Receives encrypted AES-256-CBC IPNs at https://bdx.market/eps/ipn.
    4. Always executes an authoritative server-to-server verification call (GET /v1/EPSEngine/CheckMerchantTransactionStatus) using MerchantTransactionId before updating order status.

  • Configuration Requirements:

    BDX_EPS_ENABLED=true
    BDX_EPS_MODE=live # or sandbox
    BDX_EPS_FEE_RATE=3 # 3% gateway surcharge passed to buyer
    BDX_EPS_TRANSACTION_TYPE=1
    BDX_EPS_CURRENCY=BDT
    BDX_EPS_LIVE_BASE_URL=https://pgapi.eps.com.bd
    BDX_EPS_MERCHANT_ID=your_merchant_id
    BDX_EPS_STORE_ID=your_store_id
    BDX_EPS_USERNAME=your_username
    BDX_EPS_PASSWORD=your_password
    BDX_EPS_HASH_KEY=your_sha512_hash_key
    BDX_EPS_IPN_SECRET=your_aes_ipn_secret

4. BDX Balance (bdx_balance)​

  • Support Class: App\Support\BdxBuyerWallet
  • Mechanism: Instant off-the-ledger payment using pre-funded buyer store credit. BDX Balance requires zero external gateway steps at checkout. Stock is atomically reserved, the order is instantly marked paid, and digital auto-delivery triggers immediately where applicable.

Escrow Architecture & Fee Structures​

BDX enforces safe transaction limits and transparent fee calculations at checkout.

Financial Breakdown of an Order​

When a buyer creates an order, the final price is calculated in Bangladeshi Taka (BDT / ৳) using three core components:

Total Price = Item Price * Quantity + Protection Fee + Gateway Surcharge

  1. Item Subtotal: Base unit price set by the seller multiplied by selected quantity.
  2. Buyer Protection Fee: Calculated per marketplace category using MarketplaceCategory::resolvedBuyerFlatFee() and resolvedBuyerPctFee(). Defaults to a flat ৳15 platform fee if unconfigured. This fee finances dispute processing, 7-day buyer protection coverage, and platform infrastructure.
  3. Gateway Surcharge (MDR Pass-Through): Applied conditionally depending on the selected payment method. For standard manual payments and BDX Balance, the fee is ৳0. For online gateways with processing surcharges (e.g., EPS 3% MDR), EpsPaymentGateway::feeFor() calculates and appends the surcharge directly to the order snapshot (gateway_fee).

Seller Commission Model​

BDX does not charge listing or monthly subscription fees to sellers. Instead, BDX retains a category-based commission (defaulting to 5%) upon successful completion of an order.

When an order completes, net seller payout is calculated as:

Seller Earnings = (Item Subtotal) * (1 - Commission %)

Funds transition from BDX Escrow into the seller's clearing_balance and subsequently move to available_balance following the mandatory clearing window.

Security Models & Webhook Integrity​

Automated payment integrations must defend against forgery, transaction replay attacks, and parameter tampering. BDX implements strict validation protocols for all incoming webhooks and callback return endpoints:

  1. Server-Side Re-Verification Invariant: BDX never trusts raw IPNs or browser redirect query strings to mark an order as paid or credit a wallet. Regardless of the status reported in a webhook body, BDX issues an isolated, outbound HTTP call directly to the provider's official verification API (verifyByReference() or CheckMerchantTransactionStatus) using secret merchant credentials.
  2. Strict Amount Matching: Incoming webhooks are checked against Order::total_price. If the paid amount differs by even ৳0.01 from the record on file, the system halts with a 409 Conflict HTTP status code.
  3. Cryptographic Signatures & Decryption:
    • PipraPay: Validates the presence and match of the shared mh-piprapay-api-key header before parsing payloads.
    • EPS: Decrypts incoming AES-256-CBC payloads using the secret merchant ipn_secret. The initialization step generates a 10+ digit unique MerchantTransactionId incorporating timestamp micro-seconds and random entropy to prevent collision attacks.
  4. Race-Condition & Double-Spend Prevention: Order state transitions use database transactions with lockForUpdate() constraints to guarantee that duplicate callbacks or fast double-clicks cannot process payouts twice.
Last updated on