=== BankOpenAPI for WooCommerce ===
Contributors: bankopenapi
Tags: woocommerce, vietqr, bank transfer, payment gateway, vietnam
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 0.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Accept Vietnamese bank transfers with VietQR. Every order gets its own QR code and is confirmed automatically as soon as the money arrives.

== Description ==

BankOpenAPI for WooCommerce adds a "Bank transfer (VietQR)" payment method to your store.

* After placing the order, the customer sees a QR code, the bank account and the transfer content on your order page. They scan it with any Vietnamese banking app.
* When the money arrives in your bank account, BankOpenAPI matches the transfer to the order and the order moves to Processing. No screenshots, no checking the bank app by hand.
* Partial transfers put the order on hold and ask the customer for the rest. Overpayments are noted on the order.
* Money goes straight to your own bank account. BankOpenAPI never holds your money.

= Fits your theme =

* The payment box is part of your page, not an iframe: it uses your theme's fonts, text color and buttons.
* Change the layout, accent color, countdown and success message in the settings, no code needed.
* Developers can fine-tune it with CSS variables (`--boa-accent`, `--boa-radius`, `--boa-qr-size`…), override the template (`yourtheme/bankopenapi/payment-box.php`), or use the filters and JavaScript events listed below.
* Prefer not to touch your theme? Choose "BankOpenAPI payment page": customers pay on a hosted page and come back to your order page.

= Works with =

* Classic checkout and the Checkout block.
* High-Performance Order Storage (HPOS).
* Custom thank-you pages built with page builders: add the `[bankopenapi_payment]` shortcode.

= Sandbox =

Test the whole flow without real money: enable Sandbox, paste a `boa_test_` key, place an order and press "Simulate payment" on the order page.

= Security =

* Use an API key with the "Checkout" permission: it can only create and read payment requests, so it cannot read your transactions even if your site is compromised.
* Keys can be defined in wp-config.php and are never printed in the page source, sent to the browser or written to logs.
* Webhooks are verified with HMAC-SHA256 signatures (Standard Webhooks). The plugin never trusts webhook data: it fetches the payment request from the API before updating the order.
* If webhooks cannot reach your site (firewall, security plugin), orders are still confirmed: the plugin checks payment status by itself.

= For developers =

Filters:

* `bankopenapi_payment_request_args` — change the description or expiry sent to BankOpenAPI.
* `bankopenapi_payment_box_args` — change the variables passed to the payment box template.
* `bankopenapi_payment_box_strings` — change any text of the payment box.

Actions:

* `bankopenapi_payment_box_before`, `bankopenapi_payment_box_after` — add content around the payment box.
* `bankopenapi_order_paid` — runs after an order is confirmed as paid.

JavaScript events on `document`: `bankopenapi:paid` and `bankopenapi:changed` (detail: `orderId`, `status`).

== External services ==

This plugin connects to the BankOpenAPI API (https://app.bankopenapi.com/api/v1), operated by BankOpenAPI, to create payment requests and check their status.

* When a customer places an order with this payment method, the plugin sends the order amount, the order number, a short description ("Order #… at <site name>"), the payment window and the order page URL. No customer name, email, phone number or address is sent.
* When the order page is open, and every 5 minutes for pending orders, the plugin asks the API for the payment status and the QR code image.
* When you save the settings or press "Test connection", the plugin checks your API key and registers a webhook URL on your site so BankOpenAPI can notify it when money arrives.
* If you choose the BankOpenAPI payment page, the customer's browser opens https://app.bankopenapi.com/thanh-toan/… to pay.

Terms of service: https://bankopenapi.com/dieu-khoan-su-dung
Privacy policy: https://bankopenapi.com/chinh-sach-bao-ve-du-lieu-ca-nhan

== Installation ==

1. Install and activate the plugin. WooCommerce must be active and the store currency must be Vietnamese đồng (VND).
2. Sign up at https://app.bankopenapi.com, link your bank account, then create an API key with the "Checkout" permission.
3. Go to WooCommerce → Settings → Payments → BankOpenAPI, paste the key and save. The plugin checks the key and registers the webhook automatically.
4. Enable the payment method.

== Frequently Asked Questions ==

= Does BankOpenAPI hold my money? =

No. Customers transfer straight to your own bank account. BankOpenAPI only reads incoming transfers to confirm orders.

= My checkout builder replaces the thank-you page and the QR code is missing =

Add the `[bankopenapi_payment]` shortcode to your custom thank-you page, or choose "BankOpenAPI payment page" in the settings.

= The payment box looks different from my theme =

Add a few lines to Appearance → Customize → Additional CSS, for example `.boa-pay { --boa-accent: #f5b700; --boa-radius: 12px; }`. For full control, copy `templates/payment-box.php` to `yourtheme/bankopenapi/payment-box.php`.

= What happens if the customer transfers after the order was cancelled? =

The order is put on hold instead of being completed, and you get an email to check stock and decide.

== Screenshots ==

1. The payment box on the order page: VietQR code, bank details with copy buttons and the time left to pay. It uses your theme's fonts and buttons.
2. The bank transfer method at checkout (Checkout block and classic checkout).
3. Connect your BankOpenAPI account with one click, separately for Live and Sandbox.
4. Appearance settings with a live preview rendered with your own theme.
5. The payment box updates by itself once the money has arrived.

== Changelog ==

= 0.1.0 =
* First release.
