# WooCommerce Plugin
The **AuxCORE Payment Gateway** plugin connects a WooCommerce store to the AuxCORE platform. Shoppers pay in a secure drawer that slides open on the checkout page, and the order is settled through the merchant's own AuxCORE account and gateway.
> **Plugin version:** 6.2.2 · **Requires:** WordPress 6.0+, WooCommerce 7.0+, PHP 7.2+
> **Audience:** merchants (AuxCORE dashboard owners) and store admins (WooCommerce operators)
Fastest path: **Step 1 Merchant setup → Step 2 Install → Step 3 Configure → Go-live checklist**
---
## Overview
The plugin registers four payment methods with WooCommerce, but **only Secure Online Payment runs on the AuxCORE 2.0 platform**. The other three still call the legacy AuxCORE v1.0 API and will fail at checkout.
| Method | What the shopper sees | Gateway ID | Status |
|--------|-----------------------|------------|--------|
| **Secure Online Payment** | A secure checkout panel slides open on the same page — no redirect away from the store | `wc_auxpay_hosted` | ✅ Supported |
| Credit Card | Card fields inline on the checkout page | `wc_auxpay_card` | ⚠️ Legacy — not operational |
| ACH | Bank account + routing fields inline on the checkout page | `wc_auxpay_ach` | ⚠️ Legacy — not operational |
| Text to Pay | A secure payment link sent to the shopper's mobile | `wc_auxpay_texttopay` | ⚠️ Legacy — not operational |
> **Leave the three legacy methods disabled.** To accept card *and* bank payments today, enable **Secure Online Payment** only — its drawer offers Card and/or ACH according to the merchant's **Accepted Payment Types** (step 1.2).
Both the **classic WooCommerce checkout** and the **WooCommerce Blocks checkout** are supported.
### How the pieces fit together
```
Shopper
│ pays at checkout
▼
WooCommerce store ──► AuxCORE plugin ──► AuxCORE Public API ──► Payment gateway
▲ │
└────────── signed webhook (result) ◄────────┘
```
- The plugin calls the **Public API** with the merchant's API key in an `x-api-key` header — never a JWT.
- AuxCORE routes the payment to the merchant's configured gateway and processes it.
- AuxCORE calls the store back over an **HMAC-SHA256 signed webhook** with the authoritative result, and the order status updates automatically.
> **PCI scope:** card and bank-account details are captured by AuxCORE inside the drawer. The plugin never sees or stores a PAN, CVV, or ACH account number in the WordPress database.
---
## Prerequisites
- WordPress 6.0+, WooCommerce 7.0+, PHP 7.2+
- **HTTPS with a valid certificate** — required for live payments, and required for the webhook to reach the store
- An active AuxCORE merchant account with at least one payment gateway configured
- The **Public API base URL** for your environment and an **API key** (created in Step 1)
| Environment | API base URL |
|-------------|--------------|
| Sandbox | `https://uat.auxcore.net/api/v1/public` |
| Production | `https://app.auxcore.net/api/v1/public` |
---
## Step 1 — Merchant setup (AuxCORE dashboard)
Complete this in the AuxCORE dashboard **before** configuring WordPress.
### 1.1 Enable the WooCommerce integration
1. Sign in to the AuxCORE dashboard.
2. Go to **Settings → Developer & Integrations → WooCommerce**.
3. Turn the integration **on**.
4. Enter the **store URL** exactly as shoppers reach it, for example `https://mystore.com`.
> **Match the store URL exactly.** The Secure Online Payment drawer is an iframe that the platform only allows to load on the registered origin. `https://www.mystore.com` vs `https://mystore.com`, or `http` vs `https`, is a mismatch — and a mismatched origin renders the drawer blank.
### 1.2 Choose the accepted payment types
This decides what appears **inside the Secure Online Payment drawer** — it is read from the merchant record when the drawer loads, not from the WordPress plugin settings.
1. Open **Settings → Payments → Payment Channels** (administrators: pick the merchant first).
2. In **Accepted Payment Types by Channel**, on the **Web / WooCommerce** row, enable **Card** (credit/debit) and/or **ACH** (bank transfer).
3. Click **Save Payment Channels**.
> Card is on by default and **ACH is off**. If the store should take bank payments in the drawer, turn ACH on here.
### 1.3 Create an API key
1. Go to **Settings → Developer & Integrations → API Keys** and click **New Key**.
2. Choose **WooCommerce plugin** as what you are connecting, and give the key a recognisable name, for example "WooCommerce Store".
3. **Copy it immediately** — the key is shown only once.
Use a standard **Secret** key (`api-…`), created on the Sandbox host for testing and on the Production host for go-live — keys are per environment, not distinguished by prefix. Do not use an SDK embed key (`lpk_live_…`) here.
> **Hand-off to the store admin:** the API base URL and the API key. That is everything the plugin needs.
---
## Step 2 — Install the plugin
### 2.1 Pick the build
Since 6.1.0 the plugin ships as **two distributions built from one codebase**. They are identical at payment time — same gateways, same fees, same webhooks, same refunds — and differ only in whose brand the shopper sees and in their default settings.
| | HR (white-label) | LR (AuxPAY-branded) |
|---|---|---|
| How you get it | Download below, or direct from AuxCORE | WordPress / WooCommerce plugin store, or download below |
| Slug / folder | `auxpay-payment-gateway` | `auxpay-payment-gateway-lr` |
| Name in wp-admin | AuxCORE Payment Gateway/HR | AuxPAY Payment Gateway |
| Who the shopper pays | The merchant's own name and logo from AuxCORE | AuxPAY name, logo and website, fixed |
| "Powered by AuxPAY" at checkout | A setting, **off** by default | Always on, shown read-only |
| Upgrading from 6.0.x | Upgrades in place, keeps settings and auto-update | A fresh install; nothing migrates onto it |
**A store may run only one build at a time.** Both register the same gateway IDs and read the same `wc_auxpay_*` options. Activating one deactivates the other and wp-admin says which was switched off — the API key, fee configuration and method wording carry over in both directions. Confirm the settings page still reads **Connected** after a switch.
The one exception is selecting both in the Plugins list and using the bulk *Activate* action: WordPress performs that silently, so both end up active. Nothing breaks — HR keeps serving payments and LR stands down with a notice — so an accident can never put AuxPAY branding on a white-label checkout. Deactivate whichever build you do not want.
### Download
Latest: 6.2.2 · published Oct 7, 2026
Supports Velocity Rules: a payment held for review keeps the order On hold until the merchant approves or denies it. The webhook re-registers itself after the update.
Previous versions (2)
Install an older version only to match a store you are troubleshooting; new stores should use the latest.
Install one, not both. The two builds register the same gateway IDs — see the note above on
what happens when both are activated.
### 2.2 Install and activate
1. **Plugins → Add New → Upload Plugin** and upload the `.zip` downloaded above, or copy the folder into `wp-content/plugins/`.
2. Go to **Plugins** and click **Activate**.
3. A **Settings** shortcut appears under the plugin name, linking straight to the gateway settings.
---
## Step 3 — Configure the plugin
Everything lives on one page: **WooCommerce → Settings → AuxCORE Gateway**.
### 3.1 General settings
| Setting | Purpose | Default |
|---------|---------|---------|
| **Test mode** | On = Sandbox, off = Production. Keep it on until the store has been tested. | On |
| **Frontend Visibility** | "Enable for admin only" — AuxCORE methods show at checkout only to logged-in administrators. Turn **off** for go-live. | Off |
| **API URL** | The Public API base URL from the table above. **No trailing slash.** | — |
| **API Key** | The key from step 1.3, sent as the `x-api-key` header. | — |
| **Debug log** | Writes to **WooCommerce → Status → Logs → `auxpay-payment-gateway`**. | Off |
| **Payment branding** | Shows a "Powered by AuxPAY" line under each payment method at checkout. Fixed on and greyed out on the LR build. | Off (HR) / On (LR) |
| **Services Fee** | Enables an optional service/technology fee on the legacy Card and ACH methods. | Off |
| **Services Fee Title** | The label shown for that fee on the cart and checkout. | "Technology Fee" |
Click **Save changes**.
> **What saving does:** the plugin resolves the merchant from the API key and **registers the payment webhook automatically**. There is no webhook URL to paste anywhere.
### 3.2 Connect and verify
With the API URL and key saved:
1. Click **Test API Connection** — validates the key and resolves the merchant and tenant. The **Merchant Details** panel should flip to **Connected**.
2. Click **Fetch Configuration** — pulls the merchant profile (company name, logo, address, accepted card brands, fee settings) and the WooCommerce integration status.
The Merchant Details panel then reports:
| Field | What it tells you |
|-------|-------------------|
| **API Connection** | Connected / Not Connected |
| **Payment Mode** | Sandbox or Production, reflecting **Test mode** |
| **Merchant** | The resolved merchant / company name |
| **WooCommerce Integration** | Enabled / Disabled — if disabled, turn it on in the dashboard (step 1.1) |
| **Registered Store URL** | The URL registered in AuxCORE; it must match the real site |
**Card Fee Details** and **ACH Fee Details** tables below it show any fee configured for the merchant — active flag, value, type, and minimum.
> After changing the API URL or key, save again and re-run **Test API Connection** and **Fetch Configuration** so the stored merchant details and the registered webhook stay in sync.
### 3.3 Accepted card brands
The card icons at checkout come from the merchant's **AuxCORE gateway** — the same setting that decides whether a card is approved or declined — so the logos can no longer advertise a brand the processor would refuse.
To change them, an administrator opens the merchant in the AuxCORE portal, goes to **Gateway Config**, opens the gateway and edits **Card Brand Configuration**. Then run **Fetch Configuration** in the plugin to pull the change. Switching a brand off both hides its logo and declines that card, so leave it on unless the processor genuinely has not boarded the brand.
A fetch that cannot resolve the brands leaves the stored icons untouched rather than clearing them, so a transient API problem cannot blank a working checkout. If no icons appear at all, the store has either never fetched successfully or the merchant has no active card gateway.
### 3.4 Payment method wording
Each method has its own **Title** and **Description** shown at checkout:
| Method | Default title | Default description |
|--------|---------------|---------------------|
| Secure Online Payment | "Secure Online Payment" | "Complete your payment securely through AuxCORE checkout." |
| Credit Card | "Credit Card" | "Pay using your credit card." |
| ACH | "ACH Payment" | "Pay directly from your bank account." |
| Text to Pay | "Text to Pay" | "Pay using a link sent to your mobile." |
### 3.5 Payment branding
**Payment branding** decides whether shoppers see a "Powered by AuxPAY" line — the AuxPAY logo, linking to auxpay.net — under each payment method, on both the classic and Blocks checkout. On the white-label build it is off by default, so upgrading changes nothing until you switch it on.
It does **not** change, on either build:
- **Who the shopper is asked to pay.** The merchant's own business name and logo, fetched from AuxCORE, still head the drawer and the secure payment page. The platform line sits beneath them as a credit.
- **The plugin's name in wp-admin** — the Plugins list, the settings tab and the WooCommerce → Payments rows are unaffected.
- **Your method titles and descriptions** from 3.4.
On the LR build the setting is greyed out and stays on. For an unbranded checkout, install the HR build instead — the settings carry over.
---
## Webhooks
The webhook is how AuxCORE reports the **authoritative** result of each payment, so orders settle correctly even if the shopper closes the browser.
- **Registered automatically when settings are saved** — no manual step. From 6.2.2, after an update that adds events the plugin also re-registers it once by itself, the next time an admin page loads.
- The reference URL is shown read-only on the settings page as `https://your-store.com/?wc-api=wc_auxpay_hosted_webhook`.
- Notifications are signed with **HMAC-SHA256** and verified by the plugin, with replay protection.
- Subscribed events: `transaction.approved`, `transaction.pending`, `transaction.declined`, `transaction.voided`, `transaction.refunded`, `transaction.refund_failed`, `transaction.returned`, `transaction.in_review` (6.2.2), `session.expired`, `session.cancelled`.
- Registering an already-registered store URL **rotates** the signing secret — the previous secret stops verifying immediately, and the plugin stores the new one.
If no webhook arrives, the plugin falls back to a direct AuxCORE lookup a few seconds later and settles the order from the authoritative record. The lookup runs under the same per-order lock as the webhook, so the two can never both complete an order.
> **Orders stuck on pending?** Confirm the store is reachable over HTTPS from the public internet — the webhook cannot reach `localhost` or a site behind basic auth — then re-save settings to re-register it, and enable **Debug log** to inspect incoming calls.
See [Webhooks →](./webhooks.md) for the signature scheme and [Webhook Events →](../reference/webhook-events.md) for payload shapes.
---
## Fees
If the merchant account charges a convenience fee, turn on **Services Fee** and set a **Services Fee Title**. The amount and type — percentage or fixed, with an optional minimum — come from the merchant configuration; run **Fetch Configuration** to load the current values and confirm them in the Card/ACH Fee Details tables.
> This plugin-side cart fee is added only for the standalone **Credit Card** and **ACH** methods, which are the legacy methods you should be leaving disabled. For **Secure Online Payment**, the convenience fee is applied by the AuxCORE platform inside the drawer from the merchant's fee configuration, and the webhook reports the amount actually charged — order total plus fee. The order note records the fee, which WooCommerce's own totals never see.
---
## Orders and refunds
- **Orders update automatically.** On webhook confirmation the WooCommerce order moves to the matching status — completed on approval, failed on decline.
- **Payments held for Transaction Rules review stay On hold** (6.2.2). When one of the merchant's Transaction Rules (dashboard **Settings → Fraud & Risk → Transaction Rules**) flags a payment, the processor approves it but AuxCORE holds it until the merchant reviews it in **Transactions**. The order is set to **On hold** with a note, and the shopper is told the payment was received and is being reviewed. Approving it moves the order to Processing; denying it voids the payment and cancels the order. Do not ship an On hold order with a Velocity Rules note before it is approved.
- **Transaction details** appear on the standard **WooCommerce → Orders → [order]** screen as AuxCORE reference notes.
- **Refunds** are issued from the WooCommerce order screen as usual, full or partial; the plugin forwards them to AuxCORE for Secure Online Payment orders.
- **A declined payment keeps the checkout session.** The shopper gets a "Try again" button and pays again against the same WooCommerce order rather than placing a second one.
---
## Go-live checklist
- [ ] **Test mode = On** (Sandbox) while testing
- [ ] **Test API Connection** succeeds — Merchant Details shows **Connected**
- [ ] **Fetch Configuration** succeeds — merchant name, fees and card brands load
- [ ] Card icons at checkout match the brands you actually accept (step 3.3)
- [ ] **WooCommerce Integration = Enabled** in Merchant Details
- [ ] **Registered Store URL** matches the real site, scheme and host
- [ ] **Only Secure Online Payment is enabled** — Credit Card, ACH and Text to Pay left disabled
- [ ] The merchant's **Accepted Payment Types** (Card / ACH) are set as intended for the drawer
- [ ] A **sandbox test order** goes through Secure Online Payment, by card and — if enabled — ACH
- [ ] The test order **auto-completes via webhook**, not just on the redirect back
- [ ] A **refund** works on a test order
- [ ] The site is served over **HTTPS** with a valid certificate
- [ ] Switch to a **Production API key** and the Production API URL, **Test mode = Off**, **Frontend Visibility = Off**
- [ ] Re-save settings and re-run **Test API Connection** so the live webhook is registered
---
## Troubleshooting
| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| Merchant Details shows **Not Connected** | Wrong API URL or key, a trailing slash on the URL, or settings not saved | Re-check the URL (no trailing slash) and key, **Save**, then **Test API Connection** |
| **WooCommerce Integration: Disabled** | The integration is not turned on for the merchant | Dashboard → **Settings → Developer & Integrations → WooCommerce**, enable it, then **Fetch Configuration** again |
| AuxCORE methods missing at checkout | **Frontend Visibility** is on (admin-only), or the method is not enabled | Turn Frontend Visibility off for live; confirm Secure Online Payment is enabled |
| Credit Card / ACH / Text to Pay fails at checkout | These legacy methods still call the AuxCORE v1.0 API | Disable them and use Secure Online Payment |
| Secure Online Payment drawer is blank | The registered store URL does not match the real site origin | Set the exact store URL — scheme and host — in the dashboard |
| Card or ACH missing inside the drawer | That payment type is not enabled for the merchant | Dashboard → **Settings → Payments → Payment Channels**, the **Web / WooCommerce** row; ACH is off by default |
| Order stays pending after payment | The webhook is not reaching the store | Make the site publicly reachable over HTTPS, re-save settings to re-register, check the debug log |
| Order On hold with a "Velocity Rules review" note | A merchant Velocity Rule flagged the payment | Approve or deny it in the AuxCORE dashboard under **Transactions**; the order follows automatically |
| Live payments rejected / insecure warning | No SSL | Install a valid certificate; HTTPS is required for live payments |
| No card icons at checkout | Never fetched successfully, or no active card gateway | Run **Fetch Configuration**; check the merchant has an active card gateway |
> Enable **Debug log** and read **WooCommerce → Status → Logs → `auxpay-payment-gateway`** when diagnosing connection or webhook problems.
---
## Reference
### API endpoints the plugin calls
All requests carry the **`x-api-key`** header. Paths are appended to the configured API URL.
| Endpoint | Method | When | Purpose |
|----------|--------|------|---------|
| `/testConnection` | POST | "Test API Connection" button | Validate the key; resolve `merchantId` / `tenantId` |
| `/key-info` | GET | On save | Resolve `merchantId`, `tenantId`, `pciServerUrl` |
| `/merchants` | GET | "Fetch Configuration" button | Load company name, logo, address, fees, card brands |
| `/woocommerce-status` | GET | "Fetch Configuration" button | Read the integration `enabled` flag and registered `website` |
| `/register-webhook` | POST | On save | Register the store's payment webhook (`url`, `events`); returns the signing secret in `data.secret` |
| `/checkout-session` | POST | Shopper places an order | Create the hosted checkout session the drawer loads |
| `/refund` | POST | Refund from the order screen | Full or partial refund (`transactionId`, optional `amount`) |
| `/transaction-list`, `/transaction/:id` | GET | No webhook after a few seconds | Fallback lookup of the authoritative transaction status (an approved row with `velocityReviewStatus: "in_review"` puts the order On hold) |
`POST /checkout-session` and the shopper-side `/checkout-sessions/:sessionId/*` calls share a limit of **30 requests per 15 minutes per IP**. The store's server creates every session, so a busy store can reach it from its own IP.
Plugin builds newer than 6.1.1 also call `GET /payment-purposes`, which lists the payment purposes the merchant has an active card gateway for: `{ "success": true, "data": { "purposes": [{ "purpose", "gatewayName" }], "generalConfigured": true } }`.
### Settings stored by the plugin
| Setting | Option key |
|---------|------------|
| Test mode | `wc_auxpay_test_enabled` |
| Frontend Visibility | `wc_auxpay_admin_enabled` |
| API URL | `wc_auxpay_api_url` |
| API Key | `wc_auxpay_api_key` |
| Debug log | `wc_auxpay_logs_enabled` |
| Payment branding | `wc_auxpay_show_platform_branding` |
| Services Fee | `wc_auxpay_fee_enabled` |
| Services Fee Title | `wc_auxpay_fee_title` |
| Secure Online Payment title / description | `wc_auxpay_hosted_title` / `wc_auxpay_hosted_description` |
| Credit Card title / description | `wc_auxpay_cc_title` / `wc_auxpay_cc_description` |
| ACH title / description | `wc_auxpay_ach_title` / `wc_auxpay_ach_description` |
| Text to Pay title / description | `wc_auxpay_texttopay_title` / `wc_auxpay_texttopay_description` |
---
## Next steps
- [Authentication →](./authentication.md) — API key types and headers
- [Webhooks →](./webhooks.md) — signature verification and retries
- [Testing →](./testing.md) — sandbox cards and the full QA checklist
- [Go-Live Checklist →](../guides/go-live-checklist.md) — platform-wide readiness
---
**Need help?** Contact support@auxcore.net with your merchant name and, where relevant, the `auxpay-payment-gateway` debug log.