# PayArc Terminal Gateway

The PayArc Terminal gateway lets you take in-person payments on a PayArc PAX terminal from WCPOS through PayArc Connect. A payment is started from WooCommerce and completed on the terminal, and the order is marked paid only after PayArc confirms it.

## Features[​](#features "直接链接到 Features")

### PAX Terminal Integration

Send payments to your PayArc PAX terminal through PayArc Connect in the cloud, with no local pairing

### Verified Completion

The amount and currency must match the order before completion; card brand, entry mode and last 4 are saved on the order

### Clear Decline Reasons

Decline reasons are shown to the cashier and added as an order note

### Terminal Receipts

Print a merchant receipt, a customer receipt or both on the terminal

### Built-in Diagnostics

Check your connection with the **Validate Settings** button and a diagnostics table with masked identifiers

## How It Works[​](#how-it-works "直接链接到 How It Works")

WordPress calls **PayArc Connect**, and PayArc reaches the PAX terminal. The POS only talks to your site. Each payment charges the **full order total**.

The payment page checks the result every **1.5 seconds** and stops after **5 minutes**. PayArc callbacks to the **Webhook URL** speed up the result; payments still complete by polling without callbacks. Keep the payment page open while the customer pays on the terminal.

## Setup[​](#setup "直接链接到 Setup")

1

### Install PayArc Terminal for WooCommerce

Install from `WP Admin > POS > Settings > Extensions`, or download the **payarc-terminal-for-woocommerce.zip** asset from the [GitHub releases page](https://github.com/wcpos/payarc-terminal-for-woocommerce/releases) and upload it via `Plugins > Add New > Upload Plugin`. Activate the plugin.

2

### Enter your PayArc credentials

1. Go to `WP Admin > WooCommerce > Settings > Payments` and open **PayArc Terminal**
2. Choose **Mode**: `Live` is the default. Use `Test` only with PayArc test dashboard credentials and the PayArc Connect Test app. Never mix environments
3. Enter **PayArc login email**, the email used to sign in to your PayArc merchant dashboard
4. Enter **PayArc MID** from the PayArc Merchant Profile, not the terminal ID
5. Enter **PayArc ClientSecret** from the dashboard API section and **PayArc SecretKey / API bearer token** from the PayArc dashboard
6. Leave **Callback bearer token** blank unless PayArc support issued one; it is optional

3

### Connect

Click **Connect using these credentials**. On success, the screen asks you to enter or confirm the terminal serial number and save settings. If it says the credentials look like the other environment, switch **Mode** and connect again.

注意

After any change to mode or credentials, click **Connect using these credentials** again and save. Payments are blocked until the mode and credentials match the saved connection. If upgrading from before 0.1.14, press Connect once.

4

### Add your terminal

1. Enter the PAX **Terminal serial number** from the **S/N** label on the back of the device, as configured by PayArc for your account
2. Choose **Tender type** and **Print receipt**
3. Check that the **Webhook URL** is HTTPS. Give it to PayArc only if they ask
4. Click **Save changes**

Live mode needs an HTTPS site.

5

### Enable in WCPOS

1. Go to `WP Admin > POS > Settings > Checkout`
2. Find the **PayArc Terminal** gateway and enable it for the POS
3. Save your settings

注意

The **Enable/Disable** checkbox on the WooCommerce settings screen controls the *online store* checkout only. WCPOS uses this gateway once it is configured, whether or not that box is ticked.

Most stores leave this unchecked.

## Settings reference[​](#settings "直接链接到 Settings reference")

| Setting                                 | What it does                                                                                                                      |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Enable/Disable**                      | Enables PayArc Terminal for online store checkout. Off by default; POS enablement is controlled under `POS > Settings > Checkout` |
| **Title**                               | The checkout label; defaults to `PayArc Terminal`                                                                                 |
| **Description**                         | The checkout description; defaults to `Pay in person at a PayArc PAX terminal.`                                                   |
| **Mode**                                | `Live` (default) or `Test`. Test requires PayArc test dashboard credentials and the PayArc Connect Test app                       |
| **PayArc login email**                  | Your PayArc merchant dashboard login email; required before connecting                                                            |
| **PayArc MID**                          | The merchant MID from your PayArc Merchant Profile, not the terminal ID                                                           |
| **PayArc ClientSecret**                 | The secret from the dashboard API section; stored on your server only                                                             |
| **PayArc SecretKey / API bearer token** | The token from the PayArc dashboard, used to log in and retrieve the terminal registry                                            |
| **Callback bearer token**               | Optional. Fill it in only if PayArc support issued one                                                                            |
| **PayArc connection**                   | **Connect using these credentials**, **Refresh Terminals** and **Disconnect** buttons                                             |
| **Terminal serial number**              | The PAX S/N assigned to your account, required for payments. Filled from the registry if found; enter or confirm it before saving |
| **Tender type**                         | `CREDIT` (default) or `DEBIT`                                                                                                     |
| **Print receipt**                       | `0` — none (default), `1` — merchant, `2` — customer, `3` — both                                                                  |
| **Webhook URL**                         | Read-only callback address. Check that it is HTTPS; give it to PayArc only if they ask                                            |
| **PayArc diagnostics**                  | Connection information and a **Validate Settings** button; secrets are never displayed                                            |

Saved secret fields show only the last 4 characters. Leave a secret field blank to keep the saved value.

The **PayArc diagnostics** table shows mode, endpoints, masked MID / tenant ID / serial number, whether the Connect access token is configured, the Webhook URL, the last callback and the last PayArc error. Use **Validate Settings** to check your settings.

## Usage[​](#usage "直接链接到 Usage")

### Processing Payments[​](#processing-payments "直接链接到 Processing Payments")

1. **Select Gateway**: Choose **PayArc Terminal** as the payment method in the POS
2. **Start Payment**: Click **Start Payment** to send the order total to the terminal
3. **Customer Payment**: Keep the page open while the customer completes payment on the PAX terminal. Follow the status messages: `Starting terminal payment...` → `Payment sent to terminal.` → `Waiting for the terminal result...` → `Payment approved. Completing the order...`
4. **Automatic Completion**: When PayArc confirms payment, the order completes automatically

### Payment Controls[​](#payment-controls "直接链接到 Payment Controls")

* **Cancel Payment** appears once a payment starts. If PayArc has not returned a trace id yet, wait a moment before cancelling
* After a decline, cancel or timeout, you can try again. Check the terminal before retrying a timed-out payment
* The payment activity log is collapsed by default. Use **Show activity** to view it and **Clear** to clear the displayed activity

### Receipts[​](#receipts "直接链接到 Receipts")

The **Print receipt** setting controls printing on the terminal: none, merchant, customer or both.

## Refunds[​](#refunds "直接链接到 Refunds")

Refunds are not supported through the plugin. Refund through PayArc, then record the refund in WooCommerce manually.

## Logs[​](#logs "直接链接到 Logs")

Find logs in `WooCommerce > Status > Logs`, under source `payarc-terminal-for-woocommerce`. Logs include connection attempts, sales started or failed, cancellations, and callbacks accepted or rejected. Identifiers are masked and secrets are redacted.

There is no support-bundle download. When asking for help, send the order number and the relevant log lines. Do not share full MIDs, terminal IDs, tokens or card data.

## Requirements[​](#requirements "直接链接到 Requirements")

PayArc Account

<!-- -->

: A merchant account with PayArc Connect access

Compatible Hardware

<!-- -->

: A PayArc-supported PAX terminal assigned to your account

WCPOS

<!-- -->

: Pro version required for POS checkout

Server

<!-- -->

: WooCommerce 7.0+, PHP 7.4+, and HTTPS for Live mode

Currency

<!-- -->

: USD, CAD, GBP, EUR or JPY

Stable Connection

<!-- -->

: Reliable internet connection for payment communication

## Scope & Limitations[​](#scope-and-limitations "直接链接到 Scope & Limitations")

* Refunds are not supported through the plugin
* Payments charge the **full order total**; partial or split payments are not supported
* Tips are not supported
* One terminal per store: a single serial-number setting, with no cashier picker
* Currencies are limited to **USD, CAD, GBP, EUR and JPY**
* Payments are blocked until mode and credentials match the saved connection

## Troubleshooting[​](#troubleshooting "直接链接到 Troubleshooting")

### Common Issues[​](#common-issues "直接链接到 Common Issues")

The credentials look like the other environment

* The selected mode and credentials come from different environments
* Switch **Mode** to match the credentials, or replace the credentials with those for the selected mode
* Click **Connect using these credentials** again and save

Unable to connect PayArc

* PayArc refused the login credentials. Check the entered credentials and try again
* Check `WooCommerce > Status > Logs`, source `payarc-terminal-for-woocommerce`, for details

Unable to process payment request. (HTTP 500)

* This cashier message is generic. Find **PayArc payment action failed** in the WooCommerce log for the real cause
* After a mode or credential change, click **Connect using these credentials** again and save
* Check that **Terminal serial number** is filled in
* If the log says PayArc rejected both the Connect access token and SecretKey, ask PayArc support to confirm **PayArc Connect V3** is enabled for your merchant account
* Check that the store currency is **USD, CAD, GBP, EUR or JPY**

Access denied. (HTTP 403) on Start Payment

* Update to **0.1.12 or later**, which fixes this error for POS sessions

Terminal Registry is empty

* An empty registry, or a terminal shown without a POS identifier, is normal
* Registry data is only reporting information. Payments use the **Terminal serial number**

A payment waits too long

* Check the terminal screen and keep the payment page open
* Check the order notes and the PayArc dashboard before retrying
* The page checks every **1.5 seconds** and stops after **5 minutes**

### Getting Help[​](#getting-help "直接链接到 Getting Help")

* Include the **order number** and relevant **log lines** with your support request
* Visit the [GitHub repository](https://github.com/wcpos/payarc-terminal-for-woocommerce) to report issues
* Contact PayArc support for account, PayArc Connect and terminal setup