Documentation

Requirements

Installation

1. Save the payment-gateway-relay-X.X.X.zip we sent you on Telegram.
2. In WordPress admin: Plugins → Add New → Upload Plugin.
3. Choose the zip and click Install Now, then Activate.
4. If WC Stripe Gateway / WC Square isn't already active, install and activate it now. Dummy credentials are fine.

After activation you'll see a new menu: WooCommerce → Gateway Relay.

Configuration

Open WooCommerce → Gateway Relay. You'll see three sections:

General

• Enable Relay — leave OFF until credentials are saved and the connection test passes.
• Enable debug logging — turn on temporarily while troubleshooting. Log entries go to WooCommerce → Status → Logs under source payment-gateway-relay. Secrets are recursively redacted from log entries.
• Site 2 Domain — full URL of Site 2, the site Stripe / Square knows about (e.g. https://site2.example.com). Used for the statement descriptor and post-payment redirect.

Stripe Credentials (Site 2)

• Stripe Secret Key — Site 2's sk_live_… or sk_test_… (restricted keys rk_… also accepted).
• Stripe Publishable Key — Site 2's pk_live_… or pk_test_….

Find these in Site 2's Stripe Dashboard → Developers → API Keys.

Square Credentials (Site 2)

• Square Access Token — static access token from Site 2's Square Developer Dashboard.
• Square Location ID — a valid location ID on Site 2's Square account.
• Square Application ID — application ID matching that location.

Click Save Settings. Credentials are encrypted at rest with libsodium authenticated encryption the moment they're saved.

Testing credentials

Below the form is a Test connection panel:

• Test Stripe — calls /v1/balance with the stored secret key. Success = key works.
• Test Square — calls /v2/locations with the stored access token.

Test both before enabling the relay. If either fails:

• Re-check the key was pasted correctly (no leading/trailing whitespace).
• Confirm live/test mode matches what WC Stripe / WC Square is configured for on Site 1.
• Verify Site 2's processor account is in good standing.

Enabling the relay

1. Make sure both connection tests passed (or just the one you're using, if you only route a single gateway).
2. Tick Enable Relay, click Save Settings.
3. Place a test order on Site 1 using a real card or Stripe test card 4242 4242 4242 4242.
4. Check Site 2's Stripe / Square dashboard — the charge should appear there, not in any account configured directly on Site 1.

WooCommerce Blocks checkout

The plugin registers a Cart/Checkout Blocks integration automatically. If Site 1's checkout page uses the modern Blocks-based checkout:

• The Stripe publishable key is overridden at runtime so the Payment Element renders against Site 2's account.
• The Square application ID and location ID are overridden the same way.
• Express Checkout (Apple Pay / Google Pay) buttons work without any extra setup.

If Site 1 is on the classic shortcode checkout ([woocommerce_checkout]), the relay also works — the Blocks integration is additive, not a replacement for the classic flow.

What gets sent / what's stripped

Sent to Stripe / Square

• ✓ Amount and currency
• ✓ Generic order description (e.g. Order #1247)
• ✓ Statement descriptor (derived from Site 2's domain)
• ✓ Billing details (name, email, address) — required by processors for fraud scoring
• ✓ Order reference metadata (relay_order_id)

Stripped before sending

• ✗ Product names
• ✗ Product SKUs / UPCs / EANs
• ✗ Product descriptions
• ✗ Product categories
• ✗ Cart contents and line items
• ✗ Quantities and variants
• ✗ Custom product metadata

Whatever Site 1 sells doesn't go in the outbound request. From the processor's perspective, every transaction is a generic charge against Site 2's account.

Troubleshooting

Payment fails immediately

Almost always bad credentials or a live/test mode mismatch. Re-run the Test connection panel. Confirm Site 2's processor account is in good standing.

JavaScript console errors about the Stripe key

Clear every cache: WordPress object cache, page cache, CDN, browser. The publishable key is injected per page load — a stale cached HTML page on Site 1 can ship the old key.

"Stripe Account" header error

The plugin strips the Stripe-Account header automatically. If you still see it, deactivate other Stripe-related plugins on Site 1 one at a time to find the conflict.

Square: Location ID error

The Location ID must belong to the configured Square Application. Cross-check both values in Site 2's Square Developer Dashboard.

Credentials won't save

The admin user on Site 1 needs the manage_woocommerce capability. Confirm sodium and openssl PHP extensions are loaded (php -m | grep -i sodium).

WooCommerce Blocks not rendering

Make sure Site 1's checkout page contains the woocommerce/checkout block, not the legacy [woocommerce_checkout] shortcode. The relay still works on the shortcode flow — the Blocks integration is simply additive.

Uninstall

Deactivate the plugin in Plugins, then click Delete. The uninstall script automatically:

• Deletes the stored credentials option (pgr_credentials).
• Deletes the per-install encryption key (pgr_encryption_key).
• Reverts WC Stripe / WC Square to whatever credentials those plugins have configured directly.

Support

Questions, bug reports, feature requests:

@lucimornens on Telegram