Developers / WooCommerce
Take payments on WooCommerce, without touching a card number.
Your customer presses Pay, goes to a Payments.lk page, pays by card, and comes back. No card number ever reaches your server, so your own compliance burden stays as small as it can be.
Where this plugin is up to
It is built and its tests pass, and you can install it from the zip above today. It is not on the WordPress plugin directory yet, so there is no automatic update, and it has not been through a large number of real stores. If you run it, we would like to hear what breaks. Write to [email protected].
Five steps
- 1
Install the plugin
Download the zip below, then in WordPress go to Plugins, Add New Plugin, Upload Plugin, choose the file and activate it. It needs WordPress 6.6 or newer, WooCommerce 8.0 or newer and PHP 7.4 or newer.
- 2
Put in your sandbox key
Go to WooCommerce, Settings, Payments, and open Payments.lk. Leave the mode on Sandbox and paste your sandbox secret key, which starts with sk_test_. Sandbox keys are issued the day you apply, so you can do all of this while underwriting runs.
- 3
Add the webhook, which is the part that matters
The settings screen shows the address your store listens on. Copy it, add a webhook endpoint for Sandbox events at that address in the Payments.lk dashboard under Developers, tick all five events the plugin uses (payment.succeeded, payment.failed, checkout.expired, refund.succeeded and refund.failed), and paste its signing secret into the plugin's sandbox webhook signing secret. Until you do this, the gateway stays hidden at checkout and no order is ever marked paid, on purpose.
https://yourshop.lk/?wc-api=payments_lk
- 4
Place a test order
Buy something on your own store and pay with a sandbox test card. The order should move to processing by itself a moment after you are sent back, because the webhook did it rather than your browser.
View test cards
Use one of these on Payable's sandbox page, with any name and any three digit CVV. The expiry date decides the answer.
- 5123 4500 0000 0008
- Mastercard
- 2223 0000 0000 0007
- Mastercard
- 4508 7500 1574 1019
- Visa
- 3718 812455 60002
- American Express, CVV 1000
- 3600 0000 0000 0123
- Diners Club
- 6445 6445 6445 6460
- Discover
- 01/39
- Approved
- 05/39
- Declined
- 04/27
- Expired card
- 5
Go live
When your application is approved and activated, switch the mode to Live and paste your live secret key. Then add a second webhook endpoint at the same address for Live events, with the same five events, and paste its own signing secret into the plugin's live webhook signing secret. The sandbox secret does not verify live events, so the gateway stays hidden in live mode until both are in. Sandbox and live are separate accounts with separate keys, so nothing carries over.
The one rule to understand
The order is marked paid by the signed notification we send your store, never by the customer arriving back on your thank you page.
Anyone can type a thank you URL without paying, and a customer whose phone died on the way back has still paid. Only the notification is proof, and it is signed with your endpoint’s secret so nobody else can forge one. That is why the plugin refuses to mark anything paid until you have added the signing secret for the mode you are in.
What it does today
- Card payments on the hosted checkout.
- Refunds from the order screen, full or partial.
- The classic checkout and the Cart and Checkout blocks, which are the default on new stores.
- High Performance Order Storage, the default for new stores.
- A sandbox mode with test cards, so you can try all of it before you are live.
Not yet: saved cards and subscriptions, which need Payable’s Advanced plan, and any currency other than Sri Lankan rupees.
When something is wrong
- The gateway does not appear at checkout
- Four things hide it, and all four are deliberate. The store currency is not Sri Lankan rupees, because we settle in rupees and nothing else. The secret key for the current mode is empty. The webhook signing secret for the current mode is empty, because without it a customer could pay and the order would never be marked paid. Or the gateway is not enabled. The settings screen tells you which.
- Orders stay pending after a successful payment
- This is almost always the webhook. Check that you added an endpoint in the dashboard for the mode you are using, that it points at the address on the settings screen, that it has the five events ticked, and that its signing secret is pasted into the field for that mode. Sandbox and live endpoints each have their own secret. The plugin refuses every unsigned or wrongly signed notification, and one signed with one mode's secret that says it is from the other mode, and says so in the log.
- An order went on hold instead of processing
- The amount paid did not match the order total, which usually means the order was edited after the customer paid. The plugin holds it for a person rather than treating a smaller payment as settlement. The order note says both figures.
- Where do I see what happened
- Turn on the debug log in the plugin settings, then look under WooCommerce, Status, Logs, at the payments-lk source. Keys, signatures and customer details are never written there.
- Can I refund from WooCommerce
- Yes, from the order screen, in full or in part, the same as any other gateway. A refund, sandbox or live, is recorded at once, sent to Payable within about a minute, and settles when Payable confirms it; the plugin adds an order note at each step. Payable refunds a card payment only once it has settled, which is the next bank working day, so a refund made sooner can fail. The order note then says so, and you correct the order and refund again the next working day.
Check what you downloaded
Compare the file’s SHA-256 with the one here before you upload it to your store. The plugin is built from the Payments.lk repository with its checks passing, and the zip holds the source, so you can read every line you are about to run.
c52fc89423c796beb776c5a657dcd06e5fd677aa971cc42e69bd17b6322a12ca
shasum -a 256 payments-lk-for-woocommerce-0.1.2.zip
Not on WooCommerce? The developer guide covers a checkout on any website, in a mobile app, and cards on file. There are also runnable samples in Node.js and PHP.