PayPal Reader (Zettle) Gateway
The till sends the order total to a PayPal Reader, the customer taps or inserts their card on the reader, and the sale finishes on its own when the reader reports the payment complete. This page is in two parts: taking a payment at the till, and setting it up in WP Admin.
The PayPal Reader extension needs WCPOS Pro, both to install it from the extension directory and to use it at the till.
Take a payment
- The till and your store are online. The payment runs on your store's own payment page, inside the POS.
- Someone with WP Admin access has set the gateway up and paired a reader.
- The register is open, if your store uses Open and close the register. The till won't record a payment while it's closed. See Registers.
-
Build the cart and press Checkout.
-
Open the Legacy tab. Your store's payment page opens inside the POS. See The Legacy Tab.
-
Choose PayPal Reader. Your store may have given it another name. The panel says Loading readers…, then Mode: test. Ready to start payment. (or Mode: live. once the store has gone live).
-
Pick the reader. Every paired reader is a button with its name, such as Front counter (ready), and the first one is already chosen. Tap another to use it instead.
avvisoTEST MODE at the top of the panel is only a label. The reader can still charge real money. See Test mode and going live.
-
Press Start reader payment. The panel says Connecting to reader…, then Reader ready. Requesting payment…, and the full order total goes to that reader.
-
The customer taps or inserts their card on the reader. The panel says Payment in progress…, with the reader's current step in brackets, while the reader works.
-
When the reader reports the payment complete, the panel says Payment complete. Submitting order… and the POS moves on to the receipt.
You don't need Process Payment at the foot of the Legacy tab: the sale finishes on its own. Press it before the reader finishes and the POS says Complete the PayPal Reader payment before placing the order.
The dark box under the buttons keeps a timed line for every step. Read it when a payment stops partway.
The reader is always charged the whole order, so it can't share a sale with another method. Once a payment has been taken on the order, the Legacy tab reads Whole bill only and can't be used; cancel that payment first.
Stop a payment
Press Cancel payment while the payment runs. It asks the reader to cancel and stops the till listening to it, and the panel says Payment canceled.
After Cancel payment, or if the payment page is closed or reloaded while the reader is working, the till no longer hears from the reader. If the reader shows the payment approved anyway, the customer has paid: don't charge them again. Record it with the Card tile on the Payments tab, and check the payment in your Zettle account.
Once you're sure the customer wasn't charged, press Start reader payment to try again, or close the tab and take another method.
After the sale
The order is marked paid, and its transaction ID is Zettle's ID for the card payment, so you can find the same payment in your Zettle account. Order notes record when the payment started and on which reader (by its Link ID), and when it completed, was refused for an amount mismatch, or was cancelled with Cancel payment.
Refunds
The extension can't refund through Zettle, so Refund to PayPal Reader isn't available.
Don't hand the customer any cash. The card refund is made in Zettle, and Refund via cash only records it in WCPOS. If the register is open, it also lowers the cash the register expects in the drawer by the same amount. See Cash refunds and the drawer.
- Refund the card in your Zettle account.
- Record the refund on the order with Refund via cash. See Refund Destination.
If something goes wrong
No readers paired yet. Ask the store admin to pair one… The Zettle account has no reader paired, so Start reader payment stays greyed out. Someone with WP Admin access has to pair one: see Pair a reader under Set it up.
The panel stays on Connecting to reader… The reader isn't ready for a payment: it may be asleep, off, offline or busy with something else. Wake it and check it is on its home screen and online. Press Cancel payment, check the reader shows no payment taken, as in Stop a payment, then press Start reader payment again.
Payment canceled. The payment was cancelled on the reader or with Cancel payment. If you pressed Cancel payment, check the reader first, as in Stop a payment. Then start it again, or take another method.
Payment failed. Was the card charged?
What comes after Payment failed. tells you whether the customer has paid, and so whether you may charge again. Find the message, then follow its case:
- Payment amount mismatch.: charged, refund first.
- A reason in brackets: not charged, try again.
- Request failed., Invalid server response., Invalid request. or Invalid order access.: charged, record the payment.
- Nothing after it, or a message not listed here: check before you try again.
Payment amount mismatch: charged, refund first
Card charged: yes. The panel says Payment failed. Payment amount mismatch. The reader took the money, but the order's total changed after the payment started, so the order is refused and stays unpaid. Refund that payment in your Zettle account, then start a new payment for the right total. To avoid it, don't change the cart while a reader payment runs: press Cancel payment, change the cart, then start a new payment.
A reason in brackets: not charged, try again
Card charged: no. The panel says Payment failed. with a reason in brackets. The reader or Zettle didn't take the payment, for example the card was declined. Press Start reader payment, or take another method.
Only Payment failed. or an unlisted message: check before you try again
Card charged: can't tell. The panel says only Payment failed. The till lost its connection to Zettle and can't tell whether the card was charged. Treat a message this page doesn't list the same way. Check the reader and the payment list in your Zettle account. If the payment is there, record it as in Stop a payment. Start again only once you're sure it wasn't taken; if you can't tell, ask whoever manages your Zettle account before you charge again.
Request failed. or another message listed here: charged, record the payment
This case covers only these messages after Payment failed.: Request failed., Invalid server response., Invalid request. and Invalid order access. For any other message, follow Only Payment failed. instead.
Card charged: yes. The panel only shows these messages after the reader has reported the payment complete: the reader took the payment, but the store couldn't record it, so the order stays unpaid. Find the payment in your Zettle account and record it as in Stop a payment. If it isn't in your Zettle account, follow Only Payment failed. and don't charge again until you're sure.
Other messages
Zettle credentials are not configured. The Zettle Client ID or Zettle Assertion is empty. Ask whoever set up the gateway to fill them in: see Fill in the gateway settings under Set it up.
A message starting Zettle OAuth exchange returned HTTP … Zettle refused the credentials. Ask whoever set up the gateway to check the Zettle Client ID and Zettle Assertion.
The panel shows its buttons but never says Loading readers… The payment page's scripts aren't loading. See A Gateway's Payment Page Looks Wrong.
Messages while setting up
Save your Zettle Client ID and Assertion above before pairing a reader. The Paired readers section waits for both credentials. Enter them and save.
Enter the pairing code first. The Pairing code box is empty. Read the code off the reader and type it in.
Could not load paired readers: followed by Zettle's answer. The settings page couldn't reach Zettle, or Zettle refused the credentials. Check them and save again.
Pair reader shows a message starting Zettle API returned HTTP … Zettle refused the pairing code. On the reader, open Settings → Link with a developer for a fresh code, type it exactly as shown, and check the reader is online. If it still fails, check the Zettle Client ID and Zettle Assertion are saved.
PayPal Reader: mock reader is active. A developer setting, PRWC_USE_MOCK_READER, is defined in wp-config.php. No real payments are taken while it is set. Ask your developer or host to remove it.
Set it up
This part is for whoever runs the store's WP Admin: five steps, from installing the extension to switching it on for the POS.
Install, enter credentials, pair a reader and enable it for the POS
Install the extension
Open WP Admin > POS > Settings > Extensions, find PayPal Reader for WooCommerce, click Install, then Activate. See Installing an Extension.
Without the directory, download the plugin zip (not the source-code zip) from the GitHub releases page and upload it with Plugins > Add Plugin, then Upload Plugin. WooCommerce must be active.
Get your Zettle credentials
In the Zettle Developer Portal, get a Client ID and an Assertion (a JWT) for your Zettle account. To try the gateway without taking real money, use a Zettle developer (test) merchant account first.
Which PayPal Reader models and countries you can use is up to your Zettle account, not WCPOS. Check with PayPal before buying a reader.
Fill in the gateway settings
- Go to
WP Admin > WooCommerce > Settings > Paymentsand open PayPal Reader. - Leave Enable Test mode ticked, the default, while you try it with your test account.
- Enter the Zettle Client ID and the Zettle Assertion.
- Optional: change the Title cashiers choose on the payment page, and its Description.
- Save.
Pair a reader
- Scroll to Paired readers at the foot of the same settings page. It appears once both credentials are saved.
- On the PayPal Reader, open Settings → Link with a developer. The reader shows a pairing code.
- Under Pair a new reader, enter the Pairing code, and a Reader name such as
Front counter. Without a name, it is calledWCPOS PayPal Reader. - Click Pair reader. The page says Reader paired. and the reader joins the list.
Every till sees every reader paired to the Zettle account, and the cashier picks one at checkout. To remove one, click Unpair beside it and confirm.
Turn it on for the POS
Go to WP Admin > POS > Settings > Checkout, find PayPal Reader and switch Enabled on. See Enabling a Gateway.
Leave Enable PayPal Reader for web checkout (not necessary for WCPOS) unticked. It only lists the gateway on the online store; the POS uses it once it is enabled here.
Test mode and going live
Test mode doesn't switch the reader to a sandbox. Zettle has one set of addresses for test and real payments, and the account behind your credentials decides whether real money moves. Test mode only changes labels on the payment panel: the TEST MODE badge, and Mode: test. in the status line.
To go live:
- Replace the Zettle Client ID and Zettle Assertion with the ones for your real Zettle account.
- Untick Enable Test mode, and save.
- Check Paired readers. The list comes from the Zettle account, so readers paired to the test account aren't there: pair them again, as in Pair a reader under Set it up.
- Take a small real payment and refund it in Zettle.
Settings reference
On WP Admin > WooCommerce > Settings > Payments > PayPal Reader. The steps above cover the ones you need; open the list for every setting and its default.
All 6 settings, and the pairing panel
| Setting | What it does |
|---|---|
| Enable/Disable | Enable PayPal Reader for web checkout (not necessary for WCPOS). Lists the gateway on the online store. Leave it off: online, it only works on an existing order's payment page. Off by default. The POS has its own switch, under POS > Settings > Checkout |
| Title | The name cashiers choose on the payment page. Defaults to PayPal Reader |
| Description | The line shown under the title. Defaults to Pay in person using PayPal Reader. |
| Test mode | Enable Test mode. Shows the TEST MODE badge on the payment panel. On by default. It doesn't change where payments go |
| Zettle Client ID | Your Zettle OAuth client ID, from the Zettle Developer Portal |
| Zettle Assertion | Your Zettle OAuth assertion (a JWT). Kept hidden like a password |
Paired readers, below the settings, lists each reader by name and Link ID, with Unpair. Pair a new reader takes a Pairing code and a Reader name.
Logs
Order notes are the first place to look: a payment's start, its completion or amount refusal, and a Cancel payment pressed at the till are noted on its order. A decline, a cancel on the reader or a lost connection isn't noted: read the log box on the payment page.
When Zettle's reader service refuses a request or can't be reached, the extension also writes it to WP Admin > WooCommerce > Status > Logs, under the source paypal-reader-for-woocommerce. Send that log and the order number when you ask for help.
Requirements
What it doesn't do
- Refunds through Zettle, from WooCommerce or the POS.
- Tips on the reader.
- Part-payments: the reader is always charged the whole order.
- Picking up a payment after the payment page closes or reloads.
- The online store's normal checkout. Online, it only works on an existing order's payment page.
How it works, for developers
The store signs in to Zettle with the JWT-bearer OAuth grant (oauth.zettle.com) and caches the access token until 30 seconds before it expires. Pairing, the reader list and payment sessions use Zettle's Reader Connect API (reader-connect.zettle.com/v1/integrator): pairing claims a link offer with the reader's code, and each reader is a link.
Start reader payment asks the store to open a session for the chosen link. The payment page then opens a WebSocket to Zettle, asks for the reader's state, and sends the payment request for the order total, with no tipping, once the reader is ready. Progress comes back over the same socket. Cancel payment sends a cancel request on it.
When the reader reports COMPLETED, the page sends the result to the store, which accepts it only if the amount matches the order total. It saves Zettle's card payment ID as the transaction ID and places the order. The order can't be placed until that check has passed.
For automated tests, PRWC_USE_MOCK_READER (or the paypal_reader_for_woocommerce_use_mock_reader filter), with PRWC_MOCK_CANCEL_BEHAVIOR, swaps Zettle for a mock reader. It is never shown in the settings, and WP Admin warns while it is on.
Related Documentation
- The Legacy Tab
- Checkout
- Checkout Settings
- Extensions
- Report an issue on GitHub. For your Zettle account, readers and countries, contact PayPal.