Skip to content
Documentation for: TrustOrder
HUuptools.io
Markdown

Troubleshooting

TrustOrder fails open. If the service is slow or unavailable, nothing is hidden and every order goes through. The checkout waits at most 1.5 seconds for the answer.

Any error (timeout, network, unexpected answer, no API key) means nothing is hidden and the order goes through. The order gets the Not checked badge, so you can look at it yourself.

The Overview page shows the connection test on the Connection card and the most recent problem under Last error, in plain words, with the time it was logged. If there was none, it says “No error so far.”

Message What to do
The API key was not accepted. Check that you copied the whole key. Paste the full key again.
The account or shop behind this key is suspended or disabled. Contact upTools. Contact upTools.
Too many requests in a short time. TrustOrder retries by itself. Nothing; it retries.
The daily check quota is used up. Until tomorrow every payment method stays available. Wait until tomorrow.
The service did not answer in time. The order went through with every payment method. Nothing; the order went through.
The service could not be reached from this server (network or DNS error). Ask your host to check the server’s network and DNS.
Temporary error on the service side. Nothing; try again later.
The service refused a request as invalid. Update the plugin if this repeats. Update the plugin.
No API key is saved. Add a key: Install and connect.
A risky buyer would have had no payment method left, so nothing was hidden. Set a fallback payment method. Pick a fallback method: Settings.
A local check limit was reached (per session or per visitor network); those buyers were not checked. See check limits.

If the account shows Awaiting approval, checks already work; upTools approves the account soon.

The Status list on the Overview page shows whether Accented characters (PHP intl) is Available or Missing.

When the PHP intl or mbstring extension is missing, values with non-ASCII characters (accented addresses, international e-mail domains) are not hashed, and an order whose e-mail contains such characters is not checked. The admin shows a notice. Ask your host to enable intl and mbstring.

TrustOrder limits checks per visitor network, so it needs the real visitor address.

  • The visitor network comes from REMOTE_ADDR.
  • X-Forwarded-For is never trusted.
  • If your shop is behind a proxy or load balancer, return the real visitor address from the trustorder_client_ip filter.
  • When the visitor address is private, carrier-grade NAT (100.64.0.0/10), loopback, link-local or IPv6 ULA, which usually means a proxy sits in front of the shop, the network limits are skipped until you set trustorder_client_ip. The per-session limits still apply.
  • IPv4-mapped IPv6 addresses (::ffff:a.b.c.d) count as IPv4, and IPv6 addresses are grouped per /64.

To protect your API quota, TrustOrder limits the number of checks:

  • While the buyer types, at most 5 checks run per checkout session.
  • Placing an order has its own limit: at most 3 checks per session.
  • Per visitor network: at most 20 browsing checks and 10 place-order checks per 30 minutes.
  • Shop-wide: at most 300 browsing checks per hour.

The filters trustorder_ip_check_limit, trustorder_submit_ip_check_limit and trustorder_hourly_check_limit change these limits.

What happens when a limit is reached:

  • When the place-order limit is reached for a buyer who has not been checked yet, the risky payment methods stay hidden. The last remaining payment method is never hidden.
  • A place-order check that fails because the service is unreachable or returns a server error does not use up the limit, at most 3 times per session and 6 times per visitor network in 30 minutes (filter: trustorder_network_refund_limit).
  • The Overview page shows Hourly check limit and Place-order limit per network as Reached if they were reached in the last hour, and the admin shows a dismissible warning.

Without a persistent object cache, the counters are approximate when many requests arrive at the same moment. With one, every count is atomic and a denied check uses up nothing. If the object cache errors, the counters fall back to transients for that request, so the limits still apply.

Reports are sent in the background. When the service is busy or unreachable, the plugin retries after 1, 5, 30 and 120 minutes, then marks the report as failed. To check or resend one order, use wp trustorder signal status and wp trustorder signal send (WP-CLI).

Deactivating the plugin cancels its pending background jobs. After reactivating, start the backfill.

A to_test_... key puts the shop in test mode: the Overview and Settings pages show a Test mode badge, and the data goes into a separate test database. Use a to_live_... key for the live shop.

  • Test and live keys keep separate reports. After a key switch, an order is sent again to the new environment.
  • Switching keys does not withdraw reports already sent with the other key.
  • The backfill keeps its progress per environment and runs only for the environment of the saved key.

The TrustOrder API is documented here: TrustOrder API.