Melalweb Pay with Bale for WooCommerce

Description

Melalweb Pay with Bale adds two checkout methods to WooCommerce:

• Direct pay with Bale — send an in-chat invoice through the Bale bot API and confirm the order from a webhook.
• Card to card — show destination bank cards, collect a receipt, and let a store manager approve or reject it.

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

• Direct Bale invoices with automatic webhook confirmation
• Multiple destination cards with display order and enable/disable controls
• Secure receipt upload for JPG, PNG, WebP, and PDF files
• Manager approval or rejection that updates the WooCommerce order status
• Admin dashboard for transactions, linked users, events, and CSV export
• Optional percentage discounts per payment method
• Automatic expiry of unpaid payment requests
• Guest checkout for card-to-card; pay with Bale requires a linked account

How pay with Bale works

1. The customer signs in to the store and links their account to the Bale bot with a 15-minute one-time code.
2. At checkout the plugin creates a random payment identifier and calls the Bale sendInvoice method.
3. Bale sends pre_checkout_query to the webhook. The plugin re-checks the linked account, amount, currency, order status, and expiry.
4. After payment, successful_payment is received. The Bale charge ID is stored uniquely and the order is completed.

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 merchant provider_token from your Bale merchant agreement

External services

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

Bale Bot API

• What it is used for: creating Bale Pay invoices (sendInvoice), answering checkout queries, 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 provider token, and only when a shopper pays with Bale, links their account, or a manager tests/registers the connection. 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, currency, a random payment identifier, and the customer’s Bale chat ID; 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 با بله دو روش پرداخت به ووکامرس اضافه می‌کند:

• پرداخت با بله — ارسال فاکتور درون‌چتی از طریق API ربات بله و تأیید سفارش با وبهوک
• کارت به کارت — نمایش کارت‌های مقصد، دریافت رسید و تأیید یا رد آن توسط مدیر فروشگاه

این افزونه یک اتصال مستقل Melalweb است و وابسته، تأییدشده یا مرتبط رسمی با بله، ووکامرس یا Automattic نیست. بله و ووکامرس علائم تجاری مالکان مربوطه هستند.

قابلیت‌ها

• فاکتور مستقیم بله با تأیید خودکار وبهوک
• چند کارت مقصد با ترتیب نمایش و امکان فعال یا غیرفعال‌سازی
• آپلود امن رسید JPG، PNG، WebP و PDF
• تأیید یا رد رسید توسط مدیر و به‌روزرسانی وضعیت سفارش ووکامرس
• داشبورد مدیریتی برای تراکنش‌ها، کاربران متصل، رویدادها و خروجی CSV
• تخفیف درصدی جداگانه برای هر روش پرداخت
• انقضای خودکار درخواست‌های پرداخت پرداخت‌نشده
• پرداخت مهمان برای کارت به کارت؛ پرداخت با بله نیاز به اتصال حساب دارد

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

1. مشتری وارد حساب فروشگاه می‌شود و با یک کد یک‌بارمصرف ۱۵ دقیقه‌ای حساب خود را به ربات بله متصل می‌کند.
2. هنگام ثبت سفارش، افزونه یک شناسه پرداخت تصادفی می‌سازد و متد sendInvoice بله را فراخوانی می‌کند.
3. بله رویداد pre_checkout_query را به وبهوک می‌فرستد. افزونه حساب متصل، مبلغ، ارز، وضعیت سفارش و انقضا را دوباره بررسی می‌کند.
4. پس از پرداخت، رویداد successful_payment می‌رسد. شناسه تراکنش بله به‌صورت یکتا ذخیره و سفارش تکمیل می‌شود.

نیازمندی‌ها

• وردپرس ۶.۵ یا جدیدتر
• ووکامرس ۷.۰ یا جدیدتر
• واحد پول فروشگاه روی ریال (IRR) یا تومان (IRT / TOMAN)
• توکن ربات بله و provider_token پذیرنده طبق قرارداد پذیرندگی بله

نصب

1. افزونه ووکامرس را نصب و فعال کنید.
2. فایل ZIP را از «افزونه‌ها ← افزودن» نصب کنید، یا پوشه melalweb-pay-with-bale-for-woocommerce را در wp-content/plugins/ کپی کنید.
3. افزونه Melalweb Pay with Bale را فعال کنید.
4. از منوی مدیریت وردپرس وارد Melalweb Pay with Bale شوید.
5. نام کاربری ربات، توکن ربات و توکن پذیرنده را وارد و ذخیره کنید.
6. روی «ثبت وبهوک در بله» بزنید.
7. اگر کارت به کارت می‌خواهید، کارت‌های مقصد را اضافه کنید.
8. واحد پول ووکامرس را روی ریال یا تومان قرار دهید.

پرسش‌های رایج

آیا این افزونه رسمی بله یا ووکامرس است؟
خیر. این یک افزونه مستقل Melalweb است که به API عمومی ربات بله متصل می‌شود.

آیا پرداخت با بله برای مهمان کار می‌کند؟
خیر. پرداخت با بله به کاربر واردشده و متصل به چت بله نیاز دارد. کارت به کارت از مهمان پشتیبانی می‌کند.

رسیدها کجا ذخیره می‌شوند؟
رسیدها به‌صورت خصوصی در uploads/melalweb-balepay-receipts/ ذخیره می‌شوند و فقط با دسترسی مدیر یا کلید سفارش قابل مشاهده‌اند.

بعد از حذف افزونه، اطلاعات پرداخت می‌ماند؟
بله. جدول‌ها و تنظیمات حفظ می‌شوند مگر اینکه گزینه حذف داده را در زبانه ظاهر فعال کرده باشید.

خدمات خارجی

این افزونه برای ارسال فاکتور کیف پول، تأیید پرداخت و ثبت وبهوک به سرویس بله (https://tapi.bale.ai و پیوندهای https://ble.ir) متصل می‌شود. توکن ربات و توکن پذیرنده روی همین سایت ذخیره می‌شوند و به Melalweb ارسال نمی‌شوند. شرایط استفاده و حریم خصوصی بله: https://bale.ai/terms