跳到主要内容

Header

BDX 支付总览与支持的网关

BDX.market 是孟加拉国领先的游戏与数字商品托管市场。为保护买卖双方免受欺诈、账号找回诈骗和不交付的影响，BDX 实行严格的买家保障托管架构。

在该架构下，买家为报价或充值付款时，资金不会直接转入卖家个人账户，而是由 BDX.market 安全收取并托管，直到订单成功交付并经买家核验，或经过标准的 7 天买家保障期。

本文档详细介绍支撑 BDX.market 的支付生态，包括系统配置、已启用的支付驱动、费用、安全模型和服务商技术规格。

支持的支付网关与适配器​

BDX.market 实现可插拔网关架构，定义于 App\Support\Payments\PaymentGatewayManager。系统根据环境配置（.env）和通过 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)​

  • 类： App\Support\Payments\ManualPaymentGateway
  • **支持的渠道：**直接 bKash、Nagad、Rocket 或银行转账。
  • **机制：**买家在结账时按提示向管理 bKash/Nagad 商户/个人号码手动付款，然后上传付款凭证（交易号和/或截图）。管理员通过 Filament 管理面板（App\Filament\Resources\MarketplacePaymentResource）审核凭证并批准或拒绝。
  • **适用场景：**零网关手续费模式；开箱即用的默认系统状态。

2. PipraPay 网关 (piprapay)​

  • 类： App\Support\Payments\PipraPayGateway

  • **支持的渠道：**自动 bKash、Nagad、Rocket、Upay、Visa、MasterCard。

  • **机制：**自托管的孟加拉国自动支付网关集成。通过 RESTful API 发起收费（POST /api/create-charge）并返回托管支付页 URL（pp_url）。买家完成支付后，PipraPay 发出包含 API 密钥标头（mh-piprapay-api-key）的服务器对服务器 Webhook。BDX 在释放托管前，通过交易参考（pp_id）经 POST /api/verify-payments 对每笔交易进行服务器端二次验证。

  • 配置要求：

    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 网关 (eps)​

  • 类： App\Support\Payments\EpsPaymentGateway

  • **支持的渠道：**Bangladesh Bank 持牌聚合商，覆盖孟加拉国主要银行卡、bKash、Nagad、Rocket、CellFin 和 tap。

  • **机制：**全自动托管跳转流程。

    1. 使用 HMAC-SHA512 x-hash 签名向 EPS 服务器认证（POST /v1/Auth/GetToken）以获取 API 令牌。
    2. 使用商户凭证和参数初始化交易（POST /v1/EPSEngine/InitializeEPS），获取 EPS RedirectURL。
    3. 在 https://bdx.market/eps/ipn 接收 AES-256-CBC 加密的 IPN。
    4. 在更新订单状态前，始终使用 MerchantTransactionId 执行权威的服务器对服务器验证调用（GET /v1/EPSEngine/CheckMerchantTransactionStatus）。

  • 配置要求：

    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 余额 (bdx_balance)​

  • 支持类： App\Support\BdxBuyerWallet
  • **机制：**使用预存买家店内余额的即时账本内支付。BDX 余额在结账时无需任何外部网关步骤。库存被原子预留，订单即时标记为 paid，适用时即时触发数字自动交付。

托管架构与费用结构​

BDX 在结账时执行安全的交易限额和透明的费用计算。

订单财务明细​

买家创建订单时，最终价格以孟加拉塔卡 (BDT / ৳) 按三个核心部分计算：

总价 = 商品单价 × 数量 + 保障费 + 网关附加费

  1. **商品小计：**卖家设定的基础单价乘以所选数量。
  2. **买家保障费：**按市场分类使用 MarketplaceCategory::resolvedBuyerFlatFee() 和 resolvedBuyerPctFee() 计算。未配置时默认为 ৳15 平台固定费。该费用用于纠纷处理、7 天买家保障覆盖和平台基础设施。
  3. **网关附加费 (MDR 转嫁)：**根据所选支付方式有条件收取。标准手动支付和 BDX 余额的费用为 ৳0。有处理附加费的在线网关（例如 EPS 3% MDR），EpsPaymentGateway::feeFor() 计算附加费并直接追加到订单快照（gateway_fee）中。

卖家佣金模式​

BDX 不向卖家收取上架费或月订阅费。订单成功完成后，BDX 按分类保留佣金（默认 5%）。

订单完成时，卖家净收入计算如下：

卖家收入 =（商品小计）× (1 − 佣金 %)

资金从 BDX 托管转入卖家的 clearing_balance，经过强制清算窗口后转入 available_balance。

安全模型与 Webhook 完整性​

自动支付集成必须防御伪造、交易重放攻击和参数篡改。BDX 对所有传入 Webhook 和回调返回端点实施严格验证协议：

  1. 服务器端复核不变量： BDX _绝不_信任原始 IPN 或浏览器跳转查询字符串来将订单标记为已付款或为钱包入账。无论 Webhook 正文报告何种状态，BDX 都会使用商户密钥直接向服务商官方验证 API 发起隔离的出站 HTTP 调用（verifyByReference() 或 CheckMerchantTransactionStatus）。
  2. **严格金额匹配：**传入 Webhook 与 Order::total_price 比对。如果实付金额与记录相差哪怕 ৳0.01，系统即以 409 Conflict HTTP 状态码中止。
  3. 加密签名与解密：
    • **PipraPay：**解析载荷前验证共享 mh-piprapay-api-key 标头的存在与匹配。
    • **EPS：**使用商户密钥 ipn_secret 解密传入的 AES-256-CBC 载荷。初始化步骤生成包含时间戳微秒和随机熵的 10 位以上唯一 MerchantTransactionId，防止碰撞攻击。
  4. **竞态条件与双花防范：**订单状态流转使用带 lockForUpdate() 约束的数据库事务，保证重复回调或快速双击不能重复处理结算。

相关指南​

最后于 更新