# PayPal Reader (Zettle) Gateway

The PayPal Reader gateway lets you accept in-person card payments using a **PayPal Reader (Zettle)** card terminal directly from WCPOS. The browser streams the live payment status from the reader over a secure connection to Zettle's Reader Connect API, so the cashier sees each step of the payment as it happens.

## Features[​](#features "Direct link to Features")

#### In-person card payments

Take chip, contactless, and mobile-wallet payments on a PayPal Reader (Zettle) terminal

#### Live payment status

The POS shows real-time progress — connecting, payment in progress, completed, or cancelled

#### Amount verified server-side

The reported amount is always checked against the order total before the order is placed

#### Simple pairing

Link a reader from the gateway settings using a pairing code shown on the device

## Requirements[​](#requirements "Direct link to Requirements")

WCPOS

<!-- -->

: Pro version required for POS checkout

WordPress

<!-- -->

: WordPress 5.2+ with WooCommerce active

PHP

<!-- -->

: PHP 7.4 or higher

Zettle account

<!-- -->

: A Zettle developer merchant account, plus a Zettle Client ID and Assertion (JWT) from the Zettle Developer Portal

Compatible hardware

<!-- -->

: A PayPal Reader (Zettle) card terminal

Stable connection

<!-- -->

: Live payments stream status to the reader over the network and require an internet connection

Supported hardware and regions

PayPal Reader / Zettle availability, supported reader models, and supported countries are determined by your **Zettle merchant account**, not by WCPOS. Confirm your reader and region are supported with PayPal/Zettle before purchasing.

## Installation[​](#installation "Direct link to Installation")

1

#### Install PayPal Reader for WooCommerce

Install from `WP Admin > POS > Settings > Extensions`, or download the latest **plugin zip asset** (not the GitHub source-code zip or tarball) from the [GitHub releases page](https://github.com/wcpos/paypal-reader-for-woocommerce/releases) and upload it via `Plugins > Add New > Upload Plugin`. WooCommerce must be installed and active.

2

#### Configure the gateway

1. Navigate to `WP Admin > WooCommerce > Settings > Payments`
2. Find **PayPal Reader** in the payment methods list and open its settings
3. Leave **Enable Test mode** on while you verify the setup. Use the credentials from your Zettle developer merchant account in test mode; disable it later to take live payments
4. Enter your **Zettle Client ID** — your Zettle OAuth client ID from the Zettle Developer Portal
5. Enter your **Zettle Assertion** — your Zettle OAuth assertion (JWT). This is treated as a secret
6. Optionally set the **Title** and **Description** shown to customers
7. **Save** the settings

note

The **"Enable PayPal Reader for web checkout"** checkbox is for your online store's checkout only — it is **not required for the POS**. You enable the gateway for the POS in a later step.

3

#### Pair your reader

1. After saving, scroll to the **Paired readers** section at the bottom of the settings screen (it appears once your Client ID and Assertion are saved)
2. On the PayPal Reader device, open **Settings → Link with a developer** to display the pairing code
3. Under **Pair a new reader**, enter the **Pairing code** and optionally a **Reader name** (e.g. "Front counter")
4. Click **Pair reader**. The reader appears in the paired list and is ready to take payments

Important

A reader must be successfully paired before you can take payments. Use **Unpair** on the paired list to remove a reader.

4

#### Enable in WCPOS

1. Go to `WP Admin > POS > Settings > Checkout`
2. Find the **PayPal Reader** gateway in the list
3. Enable it for use in the POS
4. Save your settings

## Taking a payment[​](#taking-a-payment "Direct link to Taking a payment")

1. **Add items** to the cart in the POS and proceed to checkout
2. **Select PayPal Reader** as the payment method
3. **Choose a paired reader** and start the payment. (If none are paired, you'll be prompted to ask the store admin to pair one in `WooCommerce → Settings → Payments → PayPal Reader`.)
4. The POS shows live status as it connects: *"Connecting to reader…"*, *"Reader ready. Requesting payment…"*, *"Payment in progress…"*
5. The customer taps or inserts their card on the reader
6. On success, the amount is verified against the order total, the transaction reference is recorded, and the order is placed automatically
7. Use **Cancel payment** at any point to cancel the request on the reader

## Going live[​](#going-live "Direct link to Going live")

When you've verified everything in test mode:

1. Disable **Enable Test mode**
2. Replace your Zettle test credentials with your **production** Client ID and Assertion
3. Save — the endpoints and flow are identical; only the merchant account differs

## Requirements recap & limitations[​](#limitations "Direct link to Requirements recap & limitations")

* **The order is only completed after a confirmed reader result.** WCPOS will not place the order unless the payment reports as completed.
* **Amount-mismatch protection.** If the amount the reader reports doesn't match the order total, the payment is refused — so avoid editing the cart total mid-payment.
* **Connectivity.** Live payments depend on the browser maintaining a session to Zettle's Reader Connect API; a stable internet connection is required.

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

The Paired readers section isn't showing

Save your **Zettle Client ID** and **Assertion** first. The pairing panel only appears once both credentials are saved. You'll otherwise see *"Save your Zettle Client ID and Assertion above before pairing a reader."*

Reader won't pair

* On the reader, make sure you opened **Settings → Link with a developer** to get a fresh pairing code
* Enter the code exactly as shown, before it expires
* Confirm your Zettle Client ID and Assertion are correct and saved
* Ensure the reader and your network have a stable internet connection

Payment is refused with an amount mismatch

The plugin verifies the reader-reported amount against the order total and refuses any mismatch. Don't change the cart or order total while a payment is in progress — cancel the payment, adjust the cart, then start a new payment.

No real payments are processed / an admin warning about a 'mock reader' appears

A development/CI constant (`PRWC_USE_MOCK_READER`) is defined in `wp-config.php`. Remove that constant before taking live payments — while it's set, no real payments are processed.

### Getting help[​](#getting-help "Direct link to Getting help")

* Report gateway issues on the [GitHub repository](https://github.com/wcpos/paypal-reader-for-woocommerce)
* Contact PayPal/Zettle support for account, reader hardware, and regional availability questions