# PaidTerms for WooCommerce — merchant installation guide (1.5.2)

For the store owner or their web developer. About 10 minutes. No code changes, theme edits, database access or
inbound firewall rules are needed.

## Before you start

You need:

- **An approved PaidTerms merchant account** that PaidTerms has activated for instalment offers, with a payout bank
  account on file. PaidTerms tells you when it is ready.
- **From your PaidTerms dashboard → WooCommerce** (sign in at app.paidterms.co.nz):
  - the plugin ZIP `paidterms-woocommerce-1.5.2.zip` — download it there;
  - a **connection key** (`ptwc_live_…`) for your store's exact web address, for example `https://shop.example.co.nz`.
    Enter the address exactly as customers see it (`www.` and no-`www` are different addresses) and click **Create
    connection key**; it is shown once, so copy it straight away. A staging copy of your site has a different address,
    so it needs its own key. (PaidTerms can also issue a key for you.)
- **A supported store** (see "Supported versions"): store currency **NZD**.
- **Outbound HTTPS** from your web server to `app.paidterms.co.nz`. PaidTerms never calls your site.

## Install

1. **Plugins → Add Plugin → Upload Plugin** (older WordPress says "Add New" or "Add New Plugin"), choose the ZIP,
   **Install Now**, then **Activate Plugin**.
2. Go to **WooCommerce → Settings → Payments**, find **PaidTerms** and click **Manage** (older WooCommerce: click
   **PaidTerms**). Don't use the list's own **Enable** button yet: enable PaidTerms in step 5, after a clean test.
3. Paste the token, tick **Test connection**, and **Save**. Leave "Enable PaidTerms at checkout" unticked for now.
4. Read the result. It always names the business: *"Orders will be financed for <business name> (token issued for
   <address>)"*. If that is not your business or your store's address, stop and contact PaidTerms.
   - **Green "PaidTerms connection successful"**: everything is ready.
   - **Red "PaidTerms connection works … Before you enable PaidTerms:"** followed by more red lines: the connection
     is fine but customers cannot use PaidTerms yet (for example, your account is not activated, setup is
     unfinished, or PaidTerms is not accepting new applications yet). Wait for PaidTerms to confirm, then test again.
   - **Failure** says what to check (see "Troubleshooting"). If PaidTerms was enabled, a failed token or address
     check switches it off at checkout until a test passes.
5. When the test is clean, tick **Enable PaidTerms at checkout** and **Save**.
6. Check: add a product to the cart so the total (including GST and shipping) is between NZ$20 and NZ$20,000. "Pay in
   instalments with PaidTerms" appears at checkout.

Product-page messaging defaults to **Off** on new and upgraded stores. To opt
in, return to the PaidTerms gateway settings and choose Automatic (the standard
WooCommerce Add to Cart hook) or Manual placement (use
`[paidterms_financing_message]`). This setting does not change checkout. Custom
product templates may omit the standard hook; in that case Automatic displays
nothing and leaves the layout alone.

Optional: put the token in `wp-config.php` instead, as `define( 'PAIDTERMS_TOKEN', 'ptwc_live_…' );`. This overrides
the settings field.

## What happens to orders

| WooCommerce status | Meaning | What you do |
|---|---|---|
| Pending payment | The customer is still completing the PaidTerms application | Nothing. It is not cancelled automatically, even if your hold-stock time passes |
| **On hold** — note "Awaiting PaidTerms approval" | Payment is set up, possibly the first instalment collected. PaidTerms has **not** approved fulfilment | **Do not ship** |
| **On hold** — note "financing was NOT approved" | PaidTerms declined the financing. No further instalments are collected | **Do not ship.** Contact the customer about another payment method, or cancel the order |
| **On hold** — note "PaidTerms needs to review this order manually" | For example a refund, dispute or failed payment. The note says which | **Do not ship.** PaidTerms will contact you |
| Processing | PaidTerms approved the order for fulfilment | Fulfil as normal |
| Cancelled / Refunded | You cancelled or refunded it; PaidTerms was told automatically | See below |

- **Only Processing means ship.** PaidTerms approves an order after the customer's first card instalment has been
  collected (usually about an hour after they finish) and a PaidTerms review.
- The plugin checks automatically: often in the first day, then every 6 hours for 14 days. **Order actions → Check
  PaidTerms status** checks at any time.
- **Cancel or refund:** PaidTerms is told automatically. If financing has not started, the PaidTerms link is switched
  off. If it has started, or the refund is partial, PaidTerms records it for manual review and contacts you. Nothing
  is cancelled automatically.
- **Your payment:** PaidTerms pays you by bank transfer. This is separate from the order moving to Processing.

## Troubleshooting

| Symptom | Check |
|---|---|
| Test: `unauthorized` | The token is incomplete, has spaces, or was rotated or revoked. Ask PaidTerms for the current token |
| Test: `store_url_mismatch` | The token was issued for a different address than your checkout uses (www vs no-www, http vs https, a staging copy). Ask PaidTerms for a token for the address shown, or fix WordPress → Settings → General (Site Address) |
| Test: `network_error` | Your host or firewall blocks outbound HTTPS to `app.paidterms.co.nz` |
| Test: `rate_limited` | Wait a few minutes and test again |
| "Connection works … Before you enable PaidTerms" then the account is not activated or setup is unfinished | Complete onboarding with PaidTerms; test again when PaidTerms confirms |
| PaidTerms not shown at checkout | Enabled? Token saved and test passing? Currency NZD? Cart total NZ$20–20,000 (incl. GST and shipping)? |
| "Temporarily unavailable" at checkout | PaidTerms is not accepting new applications right now, your account is not activated, or the plugin is older than 1.3.0. Run Test connection: it says which |
| Order stuck On hold | Read the latest order note, then **Check PaidTerms status** |
| No status changes at all | **WooCommerce → Status → Scheduled Actions**, group `paidterms`: are actions running? A low-traffic site needs WP-Cron to fire, or a real cron hitting `wp-cron.php` |

The plugin writes nothing to logs and stores the token only in the settings field. Error codes appear in order notes
and on the settings screen. When contacting PaidTerms, quote the order number, the code, and the first 18 characters
of the token shown on the settings screen (never the whole token).

## Upgrade, token rotation, deactivation

- **Upgrade:** Plugins → Add Plugin → Upload Plugin, choose the new ZIP, then **Replace current with uploaded**. Settings
  and token are kept, and every open PaidTerms order is re-checked. Then run **Test connection** once.
- **New token** (PaidTerms rotated it): the old token stops working immediately. Paste the new one and Save with
  Test connection ticked. Orders already placed keep working. Until you paste it, checks fail quietly and retry; no
  order changes.
- **Moved to a new address** (for example adding `www.`): ask PaidTerms for a token for the new address first.
- **Deactivate:** no order changes and nothing is cancelled. Customers cannot choose PaidTerms, and checks pause until
  you re-activate, when every open order is re-checked.
- **Delete:** removes the plugin's settings, including the token. Orders and their notes are kept.

## Supported versions

| | Supported | Tested by PaidTerms |
|---|---|---|
| WordPress | 6.4 or later | 7.1 |
| WooCommerce | 8.0 or later | 11.2 |
| PHP | 7.4 or later | 8.3 (syntax-checked on 7.4, 8.1, 8.3, 8.4) |
| Checkout | Classic checkout (shortcode) and the Checkout Block | Both |
| Order storage | HPOS and legacy (posts) storage | Both |
| Currency | NZD only | |

## Known limitations

- NZD stores only; order totals NZ$20–NZ$20,000 including GST and shipping.
- One token per store address. Each staging or second store needs its own token.
- Business customers apply on the PaidTerms site; the plugin never collects card or bank details.
- Heavily customised checkouts (custom payment-step plugins, one-page checkout builders, headless storefronts) are not
  guaranteed. Ordinary themes using WooCommerce's own checkout are supported.
- Status updates arrive by the plugin checking PaidTerms, not instantly.