View Categories

Troubleshooting

Waseem
Updated on July 7, 2026

4 min read

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

Gateway does not appear at checkout

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

  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

Likely cause

Enable Debug Mode is turned on.

Steps to fix

  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

Likely causes

  • 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

  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

Likely causes

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

Steps to fix

  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

Likely causes

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

Steps to fix

  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

Likely causes

  • 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

  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

Likely causes

  • 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

  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

Likely causes

  • 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

  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

Likely causes

  • 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

  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

Common misunderstandings

SituationExplanation
Gateway visible to you but not customersDebug mode is on — only administrators see it
Conditional rules “not working” in debugGateway may be hidden by rules; check logs and disable rules to test
Ready to go live but customers cannot payTurn off debug mode and ensure gateway is enabled

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

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.