Melalweb Pay with Bale for WooCommerce

Melalweb Pay with Bale adds Bale wallet checkout to WooCommerce using the official Bale Bot payment methods (sendInvoice, answerPreCheckoutQuery, and inquireTransaction).

Bale no longer supports bot card-to-card money requests. Wallet payment is the supported way for bots to receive money. This plugin can still offer an optional store-managed card-to-card method (destination card + receipt upload) that does not use Bale’s removed bot card-to-card API.

This plugin is an independent Melalweb integration. It is not affiliated with, endorsed by, or officially connected to Bale, WooCommerce, or Automattic. Bale and WooCommerce are trademarks of their respective owners.

Features

• Bale wallet invoices via sendInvoice with automatic webhook confirmation
• Pre-checkout validation within Bale’s 10-second window (answerPreCheckoutQuery)
• Transaction inquiry via inquireTransaction when a shopper checks payment status
• Optional createInvoiceLink API helper for mini-app style flows
• Test wallet token support: WALLET-TEST-1111111111111111 (same flow, no real transfer)
• Optional store card-to-card with secure receipt upload and manager review
• Admin dashboard for transactions, linked users, events, and CSV export
• Optional percentage discounts per payment method
• Automatic expiry of unpaid payment requests
• Bundled Persian (fa_IR) translations for WordPress sites set to فارسی

How Bale wallet pay works

1. The customer signs in and links their account to the Bale bot with a 15-minute one-time code.
2. At checkout the plugin creates a payment payload and calls Bale sendInvoice with the wallet provider_token from @botfather.
3. Bale sends pre_checkout_query. The plugin re-checks the linked account, amount (IRR), order status, and expiry, then answers with answerPreCheckoutQuery.
4. After payment, successful_payment is received. The charge ID is stored uniquely and the order is completed. Status checks can also call inquireTransaction.

Requirements

• WordPress 6.5 or later
• WooCommerce 7.0 or later
• Store currency set to Iranian Rial (IRR) or Toman (IRT / TOMAN)
• A Bale bot token and wallet payment token (provider_token) from @botfather

Localization

Source strings are English (WordPress.org standard). When the site language is Persian (fa_IR), the bundled translation in /languages is loaded automatically via load_plugin_textdomain and Domain Path: /languages.

External services

This plugin connects to Bale (an Iranian messenger and payments platform) so a store can send wallet invoices, confirm payments, inquire transactions, register a webhook, and optionally send status messages in Bale.

Bale Bot API

• What it is used for: creating wallet invoices (sendInvoice), answering checkout queries (answerPreCheckoutQuery), inquiring transactions (inquireTransaction), optionally creating invoice links (createInvoiceLink), registering the store webhook, testing the bot connection, sending optional order-status messages, and receiving payment updates.
• When data is sent: only after a store manager saves a bot token and wallet payment token, and only when a shopper pays with Bale, links their account, checks payment status, or a manager tests/registers the connection. Store card-to-card checkout does not call this API unless a Bale notification template is used.
• Data sent to Bale: bot token and provider token in API request URLs (stored on this WordPress site, not sent to Melalweb); invoice title, description, amount in IRR, a random payment identifier, and the customer’s Bale chat ID; transaction ID for inquiry; webhook URL of this site; optional notification text about an order.
• Service: Bale, API host https://tapi.bale.ai
• Terms of service: https://bale.ai/terms
• Privacy policy: Bale publishes its privacy terms in the same document (sections on user privacy / حریم خصوصی): https://bale.ai/terms
• Bot API documentation: https://docs.bale.ai/

Bale deep links

• What it is used for: opening the merchant’s Bale bot so a signed-in customer can link their store account with a one-time code.
• When data is sent: when a signed-in customer views checkout or the account linking page and a bot username is configured.
• Data sent: the bot username and a short-lived one-time linking code in a https://ble.ir/{bot}?start={code} URL opened by the customer.
• Service: Bale deep links on https://ble.ir
• Terms of service: https://bale.ai/terms
• Privacy policy: https://bale.ai/terms

This plugin does not send store, customer, or payment data to Melalweb.

فارسی

درگاه Melalweb Pay with Bale پرداخت کیف‌پول الکترونیکی بله را با متدهای رسمی بازو (sendInvoice، answerPreCheckoutQuery و inquireTransaction) به ووکامرس اضافه می‌کند.

درخواست پول کارت‌به‌کارت از طریق بازوها دیگر توسط بله پشتیبانی نمی‌شود؛ روش پایدار دریافت پول در بازو، کیف‌پول است. این افزونه همچنان می‌تواند یک روش اختیاری کارت به کارت فروشگاهی (نمایش کارت مقصد + بارگذاری رسید) ارائه دهد که از API حذف‌شده کارت‌به‌کارت بازو استفاده نمی‌کند.

اگر زبان سایت وردپرس روی «فارسی» باشد، ترجمه‌های همراه افزونه در پوشه languages به‌صورت خودکار بارگذاری می‌شوند.

سازوکار پرداخت کیف‌پول بله

1. مشتری وارد حساب می‌شود و با کد یک‌بارمصرف ۱۵ دقیقه‌ای به ربات بله متصل می‌شود.
2. هنگام تسویه، افزونه متد sendInvoice را با provider_token کیف‌پول فراخوانی می‌کند.
3. بله رویداد pre_checkout_query را می‌فرستد؛ افزونه ظرف حداکثر ۱۰ ثانیه با answerPreCheckoutQuery پاسخ می‌دهد.
4. پس از پرداخت موفق، successful_payment می‌رسد و سفارش تکمیل می‌شود. دکمه «بررسی وضعیت» می‌تواند از inquireTransaction هم استفاده کند.

تست بدون انتقال پول واقعی

توکن آزمایشی WALLET-TEST-1111111111111111 را به‌عنوان provider_token وارد کنید.