BeePay — Bangladesh-first WooCommerce Payment Gateway

BeePay is a WordPress WooCommerce payment gateway plugin supporting Bangladesh's major payment methods:

• bKash — Mobile financial service
• Nagad — Mobile financial service
• Rocket — DBBL card/MFS
• SSLCommerz — Cards and internet banking

Requirements

• WordPress 6.4+
• WooCommerce 7.0+
• PHP 8.1+
• Composer
• GPL-2.0-or-later license

Installation

1. Install via Composer: composer create-project taibur-rahaman/beepay
2. Activate the plugin through the 'Plugins' menu in WordPress
3. Navigate to WooCommerce → Settings → Payments to configure gateways
4. Enter credentials for each enabled gateway

Configuration

Each gateway has its own settings page with:

• Enable/Disable — Toggle the gateway
• Title — Display title at checkout
• Description — Description shown at checkout
• Sandbox — Use test environment (default: enabled for testing)
• Merchant ID — Provider-specific identifier (stored encrypted)
• API credentials — Private keys, passwords, store IDs (stored encrypted at rest)
• Debug logging — Write detailed logs to WooCommerce status

Sandbox Mode

All gateways support sandbox/test mode for development and testing. Enable the Sandbox option to use test endpoints.

Credentials

Credentials are stored encrypted using WordPress wp_options with AES-256-GCM encryption and an additional XOR salt derived from the site LOGGED_IN_SALT. Never commit real credentials to version control.

Supported Gateways

Webhook Configuration

BeePay provides a REST webhook endpoint for each provider:

WP-API URL: /wp-json/beepay/v1/webhook/{gateway}

• GET / POST /wp-json/beepay/v1/webhook/nagad
• GET / POST /wp-json/beepay/v1/webhook/bkash
• GET / POST /wp-json/beepay/v1/webhook/rocket
• GET / POST /wp-json/beepay/v1/webhook/sslcommerz

Each webhook requires:

1. Signature validation — Provider-specific HMAC/signature verification
2. Idempotency — Same webhook received multiple times is processed only once
3. Order lookup — Resolves order from invoice/transaction ID
4. Amount/currency validation — Matches order total and currency
5. Provider verification — Server-side payment status check
6. WC state transition — Updates order status via payment_complete()

Refund Behavior

• Full refunds — Supported via provider API where available
• Partial refunds — Supported where provider allows
• Manual refund required — Returned by providers without API refund support
• Never fake successful refunds — Refund results are verified from provider response

Reconciliation

Admin reconciliation system compares WooCommerce orders vs provider state:

• Date range filtering
• Gateway and provider filtering
• Transaction status and amount comparison
• CSV export
• Detection of:
  • WooCommerce paid / provider unpaid
  • Provider paid / WooCommerce unpaid
  • Amount mismatch
  • Duplicate transactions
  • Missing transactions

Development

Running Tests

composer install
./vendor/bin/phpunit

Code Quality

• composer phpcs — WordPress coding standards
• composer phpstan — Static analysis level 6

License

GPL-2.0-or-later — see LICENSE file.

Limitations

• Provider API behavior is based on documented interfaces; changes may require updates
• Refunds: Most providers return "manual refund required"; only Mock provider fully supports API refunds
• Test mode: Always use sandbox/test credentials in development never use real production credentials
• International phones: Not blindly rejected if the selected provider supports them