=== Payments.lk for WooCommerce ===
Contributors: paymentslk
Tags: woocommerce, payment gateway, sri lanka, lkr, credit card
Requires at least: 6.6
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 0.2.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Take card payments on your WooCommerce store through Payments.lk, the Sri Lankan gateway.

== Description ==

Payments.lk is a Sri Lankan payment gateway, the startup brand of Payable, which has run payments infrastructure in Sri Lanka since 2016.

Your customer presses Pay, goes to a Payments.lk hosted page, pays by card, and comes back to your store. No card number ever touches your server, which keeps your own compliance burden as small as it can be.

The order is marked paid by a signed notification sent from Payments.lk to your store, not by the customer's browser returning. That is what keeps your order records right even when a customer closes the tab at the wrong moment.

= What it does =

* Card payments on the hosted checkout
* Refunds from the WooCommerce order screen, full or partial
* Works with both the classic checkout and the Cart and Checkout blocks
* Compatible with High Performance Order Storage
* A sandbox mode with test cards, so you can try everything before you are live

= What you need =

WooCommerce 8.0 or newer. WordPress asks you to install and activate it first.

A Payments.lk account, which you can [apply for at payments.lk](https://payments.lk/signup). Sandbox keys are issued the day you apply, so you can build and test while underwriting runs. Live keys arrive when your application is approved and activated. Payments.lk charges a fee on each payment, set out on its [pricing page](https://payments.lk/pricing); the plugin itself is free.

The store currency must be one Payments.lk takes: Sri Lankan rupees (LKR) always, and US dollars (USD), pounds (GBP) or euros (EUR) once Payable has set that currency up for your account. The gateway hides itself on any other store currency rather than failing at the last step.

== External services ==

This plugin connects your store to Payments.lk, the card payment gateway that Payable (Pvt) Ltd runs in Sri Lanka. It cannot take a payment without it, so you need a Payments.lk account and its secret keys.

The plugin sends requests to one place, the Payments.lk API at https://api.payments.lk, and only at two moments:

* **At checkout,** when a customer places an order and chooses to pay by card, it asks the API to start a hosted checkout. It sends the order amount in the order's currency (Sri Lankan rupees, or US dollars, pounds or euros where your account takes them); the order's ID as its reference and a description naming the order number and your store; the customer's billing name and email address, and their phone number only when it is a valid Sri Lankan number; and the addresses on your store the customer returns to after paying or cancelling. The customer then pays on the Payments.lk checkout at payments.lk, typing the card on the payment page of Payable, which processes it. Card details never pass through your store.
* **At refunds,** when you refund an order from the order screen, it sends the amount, the Payments.lk payment it applies to and the reason you typed, if any.

Each request carries the secret key of the mode you chose, Sandbox or Live, and names the plugin and WordPress versions. The plugin makes no other requests: none on activation, no tracking and no update checks.

Payments.lk sends webhooks back to your store's callback address: signed notifications when a payment succeeds or fails, a checkout expires, or a refund succeeds or fails. The plugin checks each signature against your webhook signing secret before it changes an order.

This data is covered by the Payments.lk [terms of use](https://payments.lk/terms) and [privacy policy](https://payments.lk/privacy).

== Installation ==

1. Install and activate the plugin.
2. Go to WooCommerce, Settings, Payments, and open Payments.lk.
3. Choose Sandbox, and paste your sandbox secret key from the Payments.lk dashboard under Developers.
4. In the Payments.lk dashboard under Developers, add a webhook endpoint for Sandbox events pointing at the callback address shown on the settings screen, and tick all five events the plugin uses: payment.succeeded, payment.failed, checkout.expired, refund.succeeded and refund.failed. A new endpoint has only the first two ticked. Then paste its signing secret into Sandbox webhook signing secret. The gateway stays hidden at checkout until it is in.
5. Place a test order and pay with a test card.
6. When you are approved, switch the mode to Live and paste your live secret key. Add a second endpoint at the same address for Live events, tick the same five events, and paste its own signing secret into Live webhook signing secret. The sandbox secret does not verify live events, so the gateway stays hidden in live mode until both are in.

== Frequently Asked Questions ==

= Do card details reach my server? =

No. The customer pays on a page hosted by Payments.lk. Your store only ever sees an amount, an order reference and the result.

= Why is nothing marked paid? =

Almost always the webhook. Check that you added an endpoint in the Payments.lk dashboard for the mode you are using, that it points at the callback address on the settings screen, that it has all five events ticked (payment.succeeded, payment.failed, checkout.expired, refund.succeeded and refund.failed), and that its signing secret is pasted into the field for that mode. Without refund.succeeded a refund is never noted on the order. Sandbox and live endpoints each have their own secret. The plugin refuses every notification it cannot verify, and one signed with one mode's secret that says it is from the other mode, on purpose. The log under WooCommerce, Status, Logs says which.

= Can I take payments in another currency? =

In US dollars, pounds or euros, yes, once Payable has set that currency up for your account (usually with a foreign currency account at your bank; ask us at hello@payments.lk). The plugin sends each order in the store currency. Until your account takes it, the settings screen says so, and a customer who tries to pay is told the store cannot take card payments in that currency right now. Sandbox mode takes a currency only where Payable's sandbox holds it for your account. Any other store currency hides the gateway.

= Does it support subscriptions? =

Not in this version. Keeping a card on file to charge later needs Payable's Advanced plan, and it will come once that path is routine.

= Where do I get help? =

Ask in this plugin's support forum, or write to hello@payments.lk about your Payments.lk account.

== Screenshots ==

1. The settings: the mode, a secret key and a webhook signing secret for Sandbox and for Live, and the callback address and five events to give each mode's webhook endpoint in the Payments.lk dashboard.
2. The Checkout block, with Pay by card as the payment method.
3. An order marked paid by the signed Payments.lk webhook, with the payment noted on the order.
4. A partial refund on the order screen, about to be sent to Payments.lk.
5. The same refund once Payments.lk has confirmed it, with its notes.

== Changelog ==

= 0.2.1 =
* Ready for the WordPress.org plugin directory. The plugin declares that it needs WooCommerce, so WordPress asks for WooCommerce first.
* The readme names the external service, what is sent and when, with the Payments.lk terms of use and privacy policy, and gains screenshots.
* Tested up to WordPress 7.1 and WooCommerce 11.1.
* The webhook's signature header is unslashed and sanitised before it is read. What it verifies is unchanged.
* The Plugin URI is the plugin's own page. The Domain Path header, naming a folder never shipped, is gone; translations come from translate.wordpress.org.
* The settings screen, its warnings and the installation steps say to tick all five events the plugin uses on each webhook endpoint. A new endpoint in the dashboard ticks only payment.succeeded and payment.failed, and without refund.succeeded a refund is never noted.
* A refund the API reports as already through is noted that way, not as waiting for the processor. Nothing else about payments, refunds or webhooks changed.

= 0.2.0 =
* Payments in the store currency. Each checkout is sent in the order's currency: LKR as before, or USD, GBP or EUR, which Payments.lk takes once Payable has set that currency up for your account. The gateway is offered on a store in any of the four, and stays hidden on any other.
* When your account does not take the store currency yet, the settings screen says so for the mode you are in, and a customer who tries to pay is told the store cannot take card payments in that currency right now, with Payments.lk's own explanation in the order note.
* The limits follow the currency: Rs. 10 to Rs. 1,000,000, or 2.00 to 10,000.00 in USD, GBP and EUR.
* An order is marked paid only by a payment of its amount in its own currency; anything else is held for you to check. Order notes show amounts in the payment's currency.

= 0.1.2 =
* A webhook signing secret for each mode, Sandbox and Live, as the dashboard gives each endpoint its own. On updating, the secret you had moves into the field for the mode the store is in; paste the other mode's secret from its own endpoint.
* Orders are matched only through checkouts and payments this store created, the customer is sent only to payments.lk, and a phone number the API cannot read is left out instead of stopping the checkout.
* The default title is Pay by card.

= Earlier versions =

Every change in every version, back to 0.1.0, is in changelog.txt in the plugin's folder.
