=== BitLuso Pay ===
Contributors: bitluso
Tags: bitcoin, lightning, payment-gateway, cryptocurrency, woocommerce
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.3.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Accept Bitcoin and Lightning payments in WooCommerce. BitLuso never holds your funds: payments go directly to your wallet.

== Description ==

BitLuso Pay adds Bitcoin and Lightning as a payment method at your WooCommerce checkout.

The customer chooses BitLuso, is sent to a payment page hosted by BitLuso, pays there, and comes
back to your order confirmation. Your shop never handles an address, an invoice or a private key,
and no card or wallet details are entered on your site.

= How an order is settled =

The customer's return to your shop does not mark the order paid — they may close the tab or lose
signal. BitLuso calls your shop back over a signed HTTPS request instead, and the order moves only
on that:

* **Payment detected** — the order goes on hold while the transaction confirms.
* **Payment settled** — the order is completed, stock is reduced and your usual WooCommerce emails go out.
* **Payment late or partial** — the order goes on hold with a note explaining what happened, so money a customer really sent is never quietly discarded.
* **Payment reverted** — the order goes back to pending, because a transaction that was detected can still be replaced before it confirms.
* **Payment expired or cancelled** — the order is cancelled.

The plugin checks the amount and the currency against the order before completing it, and refuses a
payment that does not match.

= Setup =

Two fields. Paste the API key and API secret from your BitLuso dashboard into
**WooCommerce → Settings → Payments → BitLuso Pay** and save. Saving verifies the credentials and
registers your shop's callback URL with BitLuso for you — there is no URL or secret to copy in the
other direction.

= Refunds =

Refunds are issued from your BitLuso dashboard, not from WooCommerce. A crypto refund needs a
destination address that your shop does not have, so the plugin reports an error rather than
recording a refund that never happened.

= External service =

This plugin is a client for **BitLuso**, a payment service operated by BitLuso
(<https://bitluso.pt>). The plugin is not useful without a BitLuso merchant account: the payment
page and the settlement run on that service. The funds do not — payments go directly to your
wallet.

Your site contacts `https://portal.bitluso.pt` in exactly three situations, and at no other time:

1. **When you save the settings screen** with the gateway enabled. Your API key is sent so the
   credentials can be verified, together with your shop's callback URL so BitLuso knows where to
   report payments. Nothing is sent while the gateway is disabled, and nothing is sent on
   activation.
2. **When a customer places an order** and chooses BitLuso at checkout. To open the payment session
   the plugin sends the order total and currency, the order number and order key, the line items
   (name, SKU, quantity, price), the customer's billing name, email address and country, your
   shop's return and cancel URLs, the site language, and your site's address (`home_url()`). This
   is personal data belonging to your customer, sent because it is what the payment requires.
3. **When BitLuso reports a payment**, BitLuso calls your site back. This is an inbound request,
   signed with a shared secret and rejected if the signature, the timestamp or the order key does
   not match.

No analytics, telemetry or usage data is collected, and the plugin does not contact any other
service.

Your customers also reach BitLuso directly: the payment page is hosted on `portal.bitluso.pt`, so
BitLuso receives their IP address and browser details when they arrive there, as any site does.

Using this plugin means all of that is handled under BitLuso's terms of use and privacy policy
(both in Portuguese):

* Terms of use: <https://bitluso.pt/termos/>
* Privacy policy: <https://bitluso.pt/privacidade/>

If your shop serves customers in the EU, list BitLuso as a recipient of personal data in your own
privacy policy.

== Installation ==

1. Install and activate the plugin. WooCommerce 8.0 or newer must be active.
2. Create an API key in your BitLuso dashboard, under **Integrações → WooCommerce**. The secret is
   shown only once.
3. Go to **WooCommerce → Settings → Payments → BitLuso Pay**, paste the API key and API secret, tick
   **Enable BitLuso Pay** and save.
4. Saving verifies the credentials and registers the callback URL. A confirmation notice tells you
   whether you are connected in live or test mode.

Your shop must be reachable over HTTPS from the public internet, or BitLuso cannot report payments
back to it. A shop on localhost will take payments but never complete the orders.

== Frequently Asked Questions ==

= Do I need a BitLuso account? =

Yes. The plugin is a client for the BitLuso payment service; it does nothing on its own. See the
External service section above.

= Which coins can my customers pay with? =

Whatever your BitLuso store has enabled — on-chain Bitcoin, Lightning, or both.
The choice is made on the BitLuso payment page, so you never have to configure it here.

= Does it work with the block checkout? =

Yes, and with the classic checkout. The plugin also declares compatibility with High-Performance
Order Storage.

= Why is my order on hold instead of completed? =

An order goes on hold when the payment was detected but is not yet confirmed, when it arrived after
the deadline, when only part of it arrived, or when the amount or currency did not match the order.
The order notes say which, and the payment is waiting for you in your BitLuso dashboard.

= Can I refund from WooCommerce? =

No. Refund the payment from your BitLuso dashboard — a crypto refund needs the customer's address,
which your shop never sees.

= Can I point the plugin at a staging portal? =

Yes. Define the URL in `wp-config.php` before WordPress loads plugins:

`define( 'BITLUSO_PAY_URL', 'https://qa.portal.bitluso.pt' );`

A `bitluso_pay_base_url` filter is available for a multisite install whose shops belong to different
portals.

= Where are the logs? =

Tick **Debug log** on the settings screen, then read **WooCommerce → Status → Logs**, source
`bitluso_pay`.

== Screenshots ==

1. The BitLuso payment method at the block checkout.
2. The settings screen: an API key, an API secret, and nothing else to get wrong.
3. A completed order, settled by a verified callback from BitLuso.

== Changelog ==

= 1.3.0 =
* First release on WordPress.org.
* Updates now come from WordPress.org; the plugin no longer checks the BitLuso portal for new versions.
* Uninstalling the plugin now deletes its settings, including the stored API credentials.
* Hardened the callback listener: request headers and the values BitLuso reports are sanitized before use.

= 1.2.0 =
* Removed the Title, Description and portal URL settings. The checkout shows the BitLuso button, and the portal URL is now a constant that `wp-config.php` can override.
* The callback signing secret is issued by BitLuso when the shop registers its callback URL, instead of being pasted in by hand.

= 1.1.0 =
* Cart and Checkout blocks support, and High-Performance Order Storage compatibility.

= 1.0.0 =
* Initial release: hosted Bitcoin and Lightning checkout for WooCommerce.

== Upgrade Notice ==

= 1.3.0 =
Updates now arrive from WordPress.org. Uninstalling the plugin now deletes its stored API credentials — deactivating does not.
