---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/en/notes/integrate/woocommerce/index.md
description: >-
  Complete guide for the PingPong Checkout WooCommerce payment plugin
  (woocommerce-pppay v2.3.6), covering runtime requirements, installation,
  sandbox integration, production launch, order number rules, secret key and TLS
  security, refunds & secondary transactions, uninstall behavior,
  troubleshooting, and a hooks appendix. Designed for Classic Checkout shortcode
  mode, supports physical and virtual goods, and requires PHP 7.3+ with bcmath
  and curl extensions.
---
# PingPong Checkout for WooCommerce Installation & Operations Guide

::: note **Plugin Version**
 `2.3.6`
:::

## 1. Overview

This guide is intended for **operators and integration engineers of WordPress + WooCommerce merchant storefronts**. It describes the installation, configuration, integration, launch, and operations of the PingPong Checkout payment plugin (`woocommerce-pppay`).

| Aspect | Description |
|---|---|
| Target audience | Merchants running their own WooCommerce stores, site builders / agencies |
| Not applicable | API Only custom integration (refer to the [API Only docs](./non-hosted-card.md) instead) |
| Supported checkout | **Classic Checkout only** (`[woocommerce_checkout]` shortcode) |
| Product types | Physical + virtual goods (`supports = ['refunds', 'products']`) |

::: warning Checkout compatibility
WooCommerce 8.3+ defaults to **Block-Based Checkout**. The current PingPong plugin supports **Classic Checkout shortcode mode only**; Block-Based Checkout is not supported.

- For new stores, confirm the checkout page uses the `[woocommerce_checkout]` shortcode under WooCommerce → Settings → Advanced
- Stores already migrated to Block Checkout must restore Classic Checkout before enabling this plugin
:::

---

## 2. Installation & Configuration

### 2.1 Software Versions

| Component | Minimum | Recommended | Notes |
|---|---|---|---|
| WordPress | 5.7 | Latest stable | Plugin header `Requires at least` |
| WooCommerce | 5.7 | 5.7+ tested | Version check on startup |
| PHP | **7.3** | 7.4 | Enforced on startup |

### 2.2 PHP Extensions

Missing required extensions will trigger `wp_die` and block activation.

| Extension | Required | Purpose |
|---|---|---|
| **bcmath** | ✅ Required | Amount math, avoids floating-point errors |
| **curl** | ✅ Required | Communication with PingPong gateway |
| **json** | ✅ | Response parsing (built into PHP 8) |
| **hash** | ✅ | `md5` / `sha256` signing (built-in) |
| **openssl** | Recommended | TLS dependency, usually bundled with curl |

::: tip Quick self-check
Run `php -m | grep -E 'bcmath|curl|json|hash|openssl'` on the server to list loaded extensions.
:::

### 2.3 System Permissions

| Scope | Requirement | Notes |
|---|---|---|
| WP role | `administrator` or `manage_woocommerce` | Activate plugin, configure gateway |
| Filesystem | Web process can read `wp-content/plugins/woocommerce-pppay/` | Satisfied by default after extraction |
| Log directory | `WP_TEMP_DIR` or `wp-content/uploads/` **writable** | Required for error logging |
| Database | Current WP DB user has `CREATE TABLE` privilege | Two business tables are created on activation |

### 2.4 Network Connectivity

| Direction | Target | Purpose |
|---|---|---|
| Outbound {rowspan=2} | `https://acquirer-payment.pingpongx.com` (production) | Order, query, refund, token requests {rowspan=2} |
|  | `https://sandbox-acquirer-payment.pingpongx.com` (sandbox) |  |
| Inbound {rowspan=3} | `/wc-api/notify` | PingPong async callbacks, **must be publicly reachable** {rowspan=3} |
|  | `/wc-api/refund` |  |
|  | `/wc-api/show` |  |

::: warning TLS certificate verification enforced
Starting with **WooCommerce plugin `v2.3.6`**, cURL enforces **`CURLOPT_SSL_VERIFYPEER=true`** and **`CURLOPT_SSL_VERIFYHOST=2`**.

Here, `v2.3.6` refers to the **plugin version**, not the TLS protocol version. The TLS protocol requirement remains aligned with the platform security baseline (currently documented as `TLS 1.2`).

Keep the server CA bundle (`/etc/ssl/certs/` or cURL bundled CA) up to date, otherwise order requests will fail certificate verification. **Do not disable verification as a workaround.**
:::

### 2.5 Performance Recommendations (avoid 504)

The PingPong acquiring endpoint has a 50-second timeout ceiling. Align your web layer timeouts accordingly:

- `php.ini`: `max_execution_time = 60`
- Nginx: `fastcgi_read_timeout 60s;`
- Apache: `Timeout 60`

### 2.6 Upload & Activation

**Option A: Backend upload (recommended)**

1. WP admin → `Plugins → Add New → Upload Plugin`
2. Choose `woocommerce-pppay.zip` → `Install Now`
3. Click `Activate` after installation

**Option B: FTP/SFTP extraction**

1. Extract the zip and upload the `woocommerce-pppay/` directory to `wp-content/plugins/`
2. WP admin → `Plugins` → activate `PingPong-Checkout`

On activation, WordPress fires `register_activation_hook` and creates the business tables automatically (see [2.7 Database Changes](#2-7-database-changes)).

### 2.7 Database Changes (automatic)

| Table | Purpose | Key fields |
|---|---|---|
| `ping_pong_payment_log` | First-time transactions | `transaction_id` (unique), `pp_status`, `query_response`, `notify_response` |
| `ping_pong_secondary_payment_log` | Secondary transactions (refunds, etc.) | `transaction_id`, `merchant_transaction_id` (both unique), `payment_type`, `amount` |

::: tip Data preserved on uninstall
These two tables are **not dropped on uninstall**; only the `woocommerce_pppay_settings` option is removed, to support compliance retention. Run `DROP TABLE` manually if a full cleanup is required.
:::

### 2.8 Log Directory Configuration

Edit `wp-config.php` via FTP and append the following after the `ABSPATH` definition:

```php:line-numbers title="wp-config.php"
/** Absolute path to the WordPress directory. */
if ( !defined('ABSPATH') ) {
    define('ABSPATH', dirname(__FILE__) . '/');
}

define('WP_TEMP_DIR', ABSPATH . 'wp-content/tmp');  // [!code highlight]
```

Make sure the directory exists and is writable:

```bash:line-numbers title="shell"
mkdir -p wp-content/tmp
chmod 755 wp-content/tmp
chown www-data:www-data wp-content/tmp  # adjust to your web user
```

![image-9](/wordpress/image-9.png)

### 2.9 Payment Gateway Configuration

1. WP admin → `WooCommerce → Settings → Payments`
2. Locate `Credit Card (PingPong Checkout)` → toggle it on → click `Manage`

![image-7](/wordpress/image-7.png)

3. Fill in the parameters and save:

![image-8](/wordpress/image-8.png)

| Field | Sandbox example | Notes |
|---|---|---|
| `gateway` | sandbox / production | Environment switch |
| `clientId` | `2018092714313010016` | Merchant backend → System Management → Key Management |
| `accId` | `2018092714313010016291` | Merchant backend → Group Management → Site Details |
| `salt` | `F78BC96A55548B2319EE68E0` | 1:1 with clientId, **never disclose** |
| `allowedCountries` | ANY / SPECIFIC | Whether to restrict by country |
| `specificCountries` | List of country codes | Only effective when the previous field is SPECIFIC |

---

## 3. Integration & Launch Workflow

### 3.1 Pre-install Checklist

- [ ] WordPress and WooCommerce are both activated
- [ ] PHP ≥ 7.3 with `bcmath` and `curl` extensions loaded
- [ ] Obtained **clientId / accId / salt** from the integration group or sales contact
- [ ] Confirmed order numbers will be monotonically increasing and unique under the accId (see [4.2 Order Number Rules](#4-2-order-number-rules))
- [ ] Server can reach PingPong gateway domains; CA bundle is current

### 3.2 Plugin Download

<a :href="$withBase('/wordpress/woocommerce-pppay.zip')" download="woocommerce-pppay.zip">woocommerce-pppay.zip</a>

> The package is approximately 213 KB with 237 files and bundles the `vendor/` directory — **no `composer install` is required**.

### 3.3 Sandbox Integration

1. Complete the installation per [Section 2](#2-installation-configuration) and configure the sandbox parameters.

```text:line-numbers title="Sandbox store parameters"
# [!code highlight] PingPong sandbox store parameters
clientId: 2018092714313010016
accId: 2018092714313010016291
salt: F78BC96A55548B2319EE68E0
```

2. Self-test with sandbox test cards:

```text:line-numbers title="Sandbox test cards"
# [!code highlight] Standard test card
Card number: 4200000000000000
Expiry: 12/22
cvv: 123  (cvv must be 3 digits)

# [!code highlight] 3DS test card
3DS card: 4711100000000000
```

```text:line-numbers title="PingPong environment URLs"
# [!code highlight] Sandbox URL
Sandbox    https://sandbox-acquirer-payment.pingpongx.com

# [!code highlight] Production URL
Production https://acquirer-payment.pingpongx.com
```

3. **Capture screenshots**:
   - [ ] Card number input page
   - [ ] Final redirect page after payment completion
4. Send the screenshots to the integration group and notify technical support.

::: danger Sandbox discipline
The sandbox does not actually charge cards, but **never ship goods during testing**: shipping causes real losses; not shipping invites cardholder complaints. Once integration testing passes, immediately disable the payment channel and only re-enable it after the production launch.
:::

### 3.4 Production Launch Workflow

```mermaid
flowchart TD
    A[🚀 Sandbox passed] --> B[📋 Business / compliance review]
    B --> C[🔑 Production credentials issued]
    C --> D[⚙️ Switch to production params]
    D --> E[💰 Merchant self-test with small order]
    E --> F[📤 Send screenshots & link to integration group]
    F --> G[🎯 Tech support triggers real transaction]
    G --> H[🔄 Merchant initiates refund to verify flow]
    H --> I[✅ Payment channel live]

    style A fill:#2196F3,stroke:#1976D2,color:#fff,stroke-width:2px
    style B fill:#FF7043,stroke:#E64A19,color:#fff,stroke-width:2px
    style C fill:#2196F3,stroke:#1976D2,color:#fff,stroke-width:2px
    style D fill:#2196F3,stroke:#1976D2,color:#fff,stroke-width:2px
    style E fill:#2196F3,stroke:#1976D2,color:#fff,stroke-width:2px
    style F fill:#2196F3,stroke:#1976D2,color:#fff,stroke-width:2px
    style G fill:#FF7043,stroke:#E64A19,color:#fff,stroke-width:2px
    style H fill:#2196F3,stroke:#1976D2,color:#fff,stroke-width:2px
    style I fill:#4CAF50,stroke:#388E3C,color:#fff,stroke-width:2px
```

**Detailed steps**:

1. After sandbox integration passes, the PingPong business / compliance review begins (site profile + account qualification).
2. Once approved, production clientId / accId / salt are issued.
3. The merchant replaces parameters with production values in the WP admin.
4. The merchant self-tests with one small order (a `$1` product link is recommended) and captures screenshots.
5. Send the screenshots and product link to the integration group — technical support will initiate a real transaction against that link.
6. After a successful real transaction, the merchant initiates a refund to verify the refund flow.
7. Once the above is complete, the payment channel goes live.

### 3.5 Obtain accId & Secret Key from the Merchant Backend

After receiving the approval notice from the integration group or business/customer contact, log in to the [Merchant Backend](https://checkout.pingpongx.com/aq/websiteList).

::: steps
1. Open the website list

   From the menu, choose [Website Management] → [Group Management] → [View Details] → [Website List]

   ![image-4](/wordpress/image-4.png)

   Group management supports the following operations:

   - **Create group**: Click "Create Group" to add a new group; a default group is provided out of the box
   - **Website membership**: Websites are attached to groups; every website must belong to a group
   - **Detail management**: Click "View Details" to rename the group, view/copy the group ID, and list its websites

2. Select the website

   Pick the website matching the domain you are integrating from the list

   ![image-5](/wordpress/image-5.png)

3. Obtain the accId for the matched domain

   ![image-6](/wordpress/image-6.png)

4. Obtain the secret key

   From the menu, choose [System Management] → [Key Management] → click "Key Details" to view the specific key fields.

   Key status reference:

   - **Normal**: Usable
   - **Abnormal**: Not usable — contact your business representative to resolve

   ![image](/wordpress/image-9475334.png)
:::

---

## 4. Funds Safety & Risk

### 4.1 Status Verification & Reconciliation

::: danger Status-first principle
In live production operations, **always treat the payment status shown in the [acquiring merchant backend](https://checkout.pingpongx.com/) as the source of truth**. Before shipping, log in to the merchant backend and verify the order status.

This plugin **does not provide reconciliation**. Merchants must download statements from the merchant backend and reconcile them against site orders on a regular basis to ensure order status, amounts, and refund records are consistent.
:::

### 4.2 Order Number Rules

Order numbers are provided by WooCommerce. They may originate from:

- The default database auto-increment order number
- A "custom order number" plugin installed by the merchant (e.g., Sequential Order Number, Custom Order Numbers, etc.)

Regardless of the source, **the merchant must ensure order numbers under the same accId are unique and monotonically increasing**.

::: danger Funds safety red line
The PingPong backend enforces the following rules — merchants are responsible for complying:

1. **Order numbers under the same accId must be unique and monotonically increasing**, otherwise order status issues will occur.
2. **Orders from different databases cannot share the same accId** (multiple sites cannot share one accId).
3. **If the accId already has historical transactions**, set the starting order number to a value greater than the maximum existing order number before activating the plugin.
4. **When resetting the database, migrating the store, or moving the accId to another store**, first check the maximum order number under that accId.

Violating these rules causes order status mismatch and callback mis-routing, **directly impacting reconciliation**.
:::

If a "custom order number" plugin is used, verify that the generated order numbers remain unique and monotonically increasing across restarts, migrations, and concurrent requests. Database-sequence-based or strongly-validated solutions are recommended.

### 4.3 Secret Key Security

The `salt` is the signing key. **Anyone who obtains it can forge legitimate refund requests.** Please strictly follow:

- ❌ Never embed `salt` in client-side JS / templates
- ❌ Never share `salt` in console output, logs, screenshots, or chat tools in plain text
- ❌ Never export `wp-options` containing `salt` to third parties
- ✅ Only transmit `salt` via the WP admin config field and trusted channels (integration group)

### 4.4 Network & TLS

- Since WooCommerce plugin v2.3.6, cURL enforces `SSL_VERIFYPEER` + `SSL_VERIFYHOST=2`
- The server must maintain a valid CA bundle
- If the order API returns an SSL error, **first check whether the CA bundle is expired — do not disable verification**
- The inbound callback path `/wc-api/notify` must be publicly reachable; in WAF / Nginx, restrict ingress to PingPong egress IP ranges only

### 4.5 Refunds & Secondary Transactions

- The plugin's `process_refund` only validates that the amount is positive — **it does not block over-refunds**. Verify the amount before issuing a refund.
- Partial refunds are recorded in `ping_pong_secondary_payment_log`. When the status enters `PROCESSING`, the order status is frozen until the PingPong backend writes back the final result.
- Both the refund reference `merchant_transaction_id` and the original `transaction_id` have unique constraints — duplicate submissions are rejected by the database.

### 4.6 Uninstall Behavior

- `Uninstall` only deletes the `woocommerce_pppay_settings` option
- The two business tables are **preserved** for compliance traceability; run `DROP TABLE` manually if a full cleanup is required

---

## 5. Troubleshooting

| Symptom | What to check |
|---|---|
| White screen after activation | PHP < 7.3 or missing `bcmath` / `curl`; check the admin notice |
| Order API returns SSL error | Check server CA bundle expiration; **do not disable verification** |
| Order API returns 504 | See [2.5 Performance](#2-5-performance-recommendations-avoid-504); align PHP / Nginx / Apache timeouts |
| Payment succeeded but order status not updated | Verify `/wc-api/notify` is publicly reachable and not blocked by WAF |
| Refund fails with "duplicate" | `merchant_transaction_id` already exists; generate a new refund reference |
| Historical order conflict under the same accId | See [4.2 Order Number Rules](#4-2-order-number-rules); adjust the starting order number via the merchant backend or database |

---

## 6. Appendix

### 6.1 Key Registered Hooks

| Hook | Type | Purpose |
|---|---|---|
| `plugins_loaded` (0) | action | Load entrypoint, environment check, register gateway |
| `woocommerce_payment_gateways` | filter | Register `WC_Pppay` |
| `woocommerce_api_{notify/refund/show}` | action | Async callback endpoints |
| `woocommerce_thankyou_pppay` | action | Payment completion page |
| `wc_ajax_ppc_token_request` | action | Frontend token exchange |
| `wc_ajax_ppc_polling_order_status` | action | Order status polling |
| `wc_ajax_ppc_get_order_detail` | action | Fetch order detail |
| `add_meta_boxes` | action | Admin order MetaBox |
| `register_activation_hook` | hook | Create tables |
| `register_uninstall_hook` | hook | Clean up config |

### 6.2 Version Information

| Item | Value |
|---|---|
| Current plugin version | `2.3.6` |
| Package | `woocommerce-pppay.zip` (~213 KB, 237 files) |
| Dependencies | `vendor/` is bundled; no `composer install` required |