---
title: Troubleshooting
description: "Common issues with WooCommerce Custom Payment Gateway Pro and how to fix them. --- Table of Contents [Toggle](#) - [Gateway does not appear at checkout](#Gateway_does_not_appear_at_checkout) - [Likely causes](#Likely_causes) - [Steps to fix](#Steps_to_fix) - [Gateway only appears for administrators](#Gateway_only_appears_for_administrators) - [Likely…"
url: "https://wpruby.com/knowledgebase/troubleshooting/"
updated: "2026-07-07"
category: WooCommerce Custom Payment Gateway Pro
---

# Troubleshooting

Common issues with WooCommerce Custom Payment Gateway Pro and how to fix them.

---

Table of Contents

 [Toggle](#)

- [Gateway does not appear at checkout](#Gateway_does_not_appear_at_checkout)
  - [Likely causes](#Likely_causes)
  - [Steps to fix](#Steps_to_fix)
- [Gateway only appears for administrators](#Gateway_only_appears_for_administrators)
  - [Likely cause](#Likely_cause)
  - [Steps to fix](#Steps_to_fix-2)
- [Conditional rules are preventing the gateway from showing](#Conditional_rules_are_preventing_the_gateway_from_showing)
  - [Likely causes](#Likely_causes-2)
  - [Steps to fix](#Steps_to_fix-3)
- [Required custom field is blocking checkout](#Required_custom_field_is_blocking_checkout)
  - [Likely causes](#Likely_causes-3)
  - [Steps to fix](#Steps_to_fix-4)
- [API request is not sent](#API_request_is_not_sent)
  - [Likely causes](#Likely_causes-4)
  - [Steps to fix](#Steps_to_fix-5)
- [API request fails](#API_request_fails)
  - [Likely causes](#Likely_causes-5)
  - [Steps to fix](#Steps_to_fix-6)
- [API logs are empty](#API_logs_are_empty)
  - [Likely causes](#Likely_causes-6)
  - [Steps to fix](#Steps_to_fix-7)
- [Customer was not redirected to API URL](#Customer_was_not_redirected_to_API_URL)
  - [Likely causes](#Likely_causes-7)
  - [Steps to fix](#Steps_to_fix-8)
- [Uploaded file does not appear where expected](#Uploaded_file_does_not_appear_where_expected)
  - [Likely causes](#Likely_causes-8)
  - [Steps to fix](#Steps_to_fix-9)
- [Debug mode confusion](#Debug_mode_confusion)
  - [Common misunderstandings](#Common_misunderstandings)
  - [Steps to go live](#Steps_to_go_live)
- [Deprecated Credit Card field warnings](#Deprecated_Credit_Card_field_warnings)

## Gateway does not appear at checkout

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#gateway-does-not-appear-at-checkout](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#gateway-does-not-appear-at-checkout)

### Likely causes

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#likely-causes](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#likely-causes)

- The gateway is disabled.
- **Enable Debug Mode** is on and you are not logged in as an administrator.
- Conditional display rules are hiding the gateway.
- WooCommerce checkout cache or a conflicting plugin.

### Steps to fix

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#steps-to-fix](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#steps-to-fix)

1. Go to **WooCommerce → Settings → Payments → Manage** on the gateway.
2. Confirm **Enable Custom Payment** is checked.
3. If testing, log in as an **Administrator** or turn off **Enable Debug Mode**.
4. Check **Conditional Display Rules** — disable rules temporarily to test.
5. Clear any caching plugins and test in a private browser window.
6. Confirm WooCommerce is available in your customer's country and currency.

---

## Gateway only appears for administrators

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#gateway-only-appears-for-administrators](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#gateway-only-appears-for-administrators)

### Likely cause

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#likely-cause](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#likely-cause)

**Enable Debug Mode** is turned on.

### Steps to fix

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#steps-to-fix-1](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#steps-to-fix-1)

1. Open gateway settings.
2. Uncheck **Enable Debug Mode**.
3. Save changes.

Debug mode limits the gateway to users with the Administrator role so you can test safely.

---

## Conditional rules are preventing the gateway from showing

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#conditional-rules-are-preventing-the-gateway-from-showing](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#conditional-rules-are-preventing-the-gateway-from-showing)

### Likely causes

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#likely-causes-1](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#likely-causes-1)

- Rules are enabled but the cart or customer does not match.
- Country, cart total, or role conditions are too strict.
- Shipping method not yet selected when rules are evaluated.

### Steps to fix

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#steps-to-fix-2](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#steps-to-fix-2)

1. Open **Conditional Display Rules** on the gateway.
2. Temporarily uncheck **Enable conditional display rules** and save.
3. Test checkout — if the gateway appears, a rule is the cause.
4. Review each condition:
   - Is the customer's country correct?
   - Is the cart total above/below your threshold?
   - Is the user logged in with the expected role?
5. Re-enable rules one at a time to find the problem condition.

> Only **All conditions match** is available in the current release. Every condition must pass.

---

## Required custom field is blocking checkout

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#required-custom-field-is-blocking-checkout](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#required-custom-field-is-blocking-checkout)

### Likely causes

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#likely-causes-2](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#likely-causes-2)

- A required field is empty.
- File upload failed or was not completed.
- Email or number field has invalid format.

### Steps to fix

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#steps-to-fix-3](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#steps-to-fix-3)

1. Check the error message at the top of checkout.
2. Open the gateway **Custom Form** builder and review fields marked **Required: Yes**.
3. Test each field type:
   - **File Upload** — confirm file type and size are within limits
   - **Email** — use a valid email format
   - **Customer Signature** — confirm the signature pad is filled
4. Make seldom-used fields optional if they block legitimate orders.

---

## API request is not sent

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#api-request-is-not-sent](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#api-request-is-not-sent)

### Likely causes

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#likely-causes-3](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#likely-causes-3)

- **API requests** is not enabled.
- **API URL** is empty.
- Order was placed before API settings were saved.

### Steps to fix

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#steps-to-fix-4](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#steps-to-fix-4)

1. Open gateway settings → **Advanced options**.
2. Check **Enable the gateway to request an API URL after the checkout process**.
3. Enter a valid **API URL** and save.
4. Place a new test order (API runs on order placement, not on settings save).
5. Check **API Logs** for entries.

---

## API request fails

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#api-request-fails](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#api-request-fails)

### Likely causes

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#likely-causes-4](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#likely-causes-4)

- Wrong URL, method, or authentication.
- Remote server rejected the request.
- Firewall or SSL issues.
- Invalid JSON or missing required fields on the receiving end.

### Steps to fix

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#steps-to-fix-5](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#steps-to-fix-5)

1. Click **Send Test Request** in **API Request Tools**.
2. Open the failed entry in **API Logs** and read the error and response body.
3. Verify **HTTP Headers** (Authorization, API keys).
4. Confirm **POST requests data type** matches what your endpoint expects (FORM DATA vs JSON).
5. Check **Payload Preview** key names against your API documentation.
6. Retry from the log if the issue was temporary.

---

## API logs are empty

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#api-logs-are-empty](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#api-logs-are-empty)

### Likely causes

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#likely-causes-5](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#likely-causes-5)

- No orders have used this gateway since API was enabled.
- API requests are disabled.
- You are viewing the wrong gateway's settings page.

### Steps to fix

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#steps-to-fix-6](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#steps-to-fix-6)

1. Confirm **API requests** is enabled and **API URL** is set.
2. Place a test order with the gateway.
3. Use **Send Test Request** — this should create a log entry.
4. Refresh the API Logs table.
5. Clear status/date filters if applied.

---

## Customer was not redirected to API URL

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#customer-was-not-redirected-to-api-url](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#customer-was-not-redirected-to-api-url)

### Likely causes

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#likely-causes-6](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#likely-causes-6)

- **Redirect the Customer to the API URL** is not checked.
- **POST** redirect uses an intermediate receipt page — customer may briefly see a loading step.
- API request failed before redirect.

### Steps to fix

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#steps-to-fix-7](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#steps-to-fix-7)

1. Confirm **Redirect the Customer to the API URL** is checked.
2. For **GET** requests, confirm the API URL accepts query parameters.
3. For **POST** redirects, the customer is sent to a receipt page that auto-submits a form — ensure the API URL accepts form POST data.
4. Note: **JSON** POST body mode does not work with redirect enabled.
5. Check **API Logs** for errors on the request.

---

## Uploaded file does not appear where expected

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#uploaded-file-does-not-appear-where-expected](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#uploaded-file-does-not-appear-where-expected)

### Likely causes

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#likely-causes-7](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#likely-causes-7)

- **Show in admin order details** or **Show in emails** is set to No.
- **Store with order** is disabled.
- **Store Payment Information in the Database** is disabled in global settings.
- Upload did not complete at checkout.

### Steps to fix

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#steps-to-fix-8](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#steps-to-fix-8)

1. In the **File Upload** field settings, confirm:
   - **Show in admin order details:** Yes
   - **Show in emails:** Yes (if needed)
   - **Store with order:** Yes
2. Go to **WooCommerce → Settings → Custom Payment Gateways** and confirm **Store Payment Information in the Database** is enabled.
3. On the order screen, check the **Payment Information** meta box.
4. Files are stored in the WordPress **media library** (uploads folder). Look for the attachment linked on the order.
5. Confirm the customer uploaded an allowed file type within the size limit.

---

## Debug mode confusion

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#debug-mode-confusion](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#debug-mode-confusion)

### Common misunderstandings

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#common-misunderstandings](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#common-misunderstandings)

| Situation | Explanation |
| --- | --- |
| Gateway visible to you but not customers | Debug mode is on — only administrators see it |
| Conditional rules "not working" in debug | Gateway may be hidden by rules; check logs and disable rules to test |
| Ready to go live but customers cannot pay | Turn off debug mode and ensure gateway is enabled |

### Steps to go live

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#steps-to-go-live](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#steps-to-go-live)

1. Turn off **Enable Debug Mode**.
2. Confirm **Enable Custom Payment** is checked.
3. Test once as a non-admin customer (or in a logged-out session).
4. Save settings.

---

## Deprecated Credit Card field warnings

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#deprecated-credit-card-field-warnings](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/troubleshooting.md#deprecated-credit-card-field-warnings)

If you see warnings about the deprecated Credit Card field:

1. Open the affected gateway from **Custom Payment Gateways**.
2. Remove the legacy Credit Card field from **Custom Form**.
3. Use a PCI-compliant gateway (Stripe, PayPal, WooPayments, and so on) for card payments.

See [Security and Sensitive Payment Data](https://wpruby.com/knowledgebase/security-and-sensitive-payment-data/).