In Public Pay v2, the Payment Description field lets WHMCS administrators specify the exact text shown on PayPal and Coinbase payment screens. This field accepts four variables that are replaced at runtime: %COMPANY_NAME%, %CLIENT_ID%, %CLIENT_DISPLAY_NAME%, and %CLIENT_HASH_ID%. The system pulls live values from your WHMCS company settings and client records, producing a description that is both branded and client-specific before the gateway page loads.

Dynamic descriptions reduce client confusion, reinforce branding, and simplify transaction reconciliation on your side. A static label such as "Payment Due" becomes actionable context like "Acme Hosting Services - John Doe (Account 123)". This is especially relevant for Public Pay links that allow invoice settlement without requiring a full client login, where the hash identifier ties the transaction back to the correct record securely.

#Understanding the Payment Description Field

Before v2, payment descriptions passed to gateways were often hardcoded or minimally configurable, leading to generic entries in client statements and your merchant accounts. The new field solves this by letting administrators build templates that incorporate real data at the moment of checkout. Because Public Pay supports hash-based access, the %CLIENT_HASH_ID% variable becomes particularly useful for cross-referencing payments that originate from emailed links or portal-generated URLs. All substitutions occur server-side, so sensitive account details never appear in plain text within the WHMCS interface itself.

#Available Variables

  • %COMPANY_NAME% - The name of your company (The company name specified in WHMCS's settings)
  • %CLIENT_ID% - The unique id of the client's WHMCS account
  • %CLIENT_DISPLAY_NAME% - The display name as configured by the client's public pay settings
  • %CLIENT_HASH_ID% - The client's unique public pay hash id

The above variables will be replaced with the correct values at runtime. Replacement is deterministic and occurs before the client browser is redirected, guaranteeing that the final string matches the intended invoice and client context. Using these placeholders removes the need to edit descriptions manually for every transaction.

#Configuring and Testing Payment Descriptions

Navigate to the Public Pay settings area in the WHMCS admin panel and locate the dedicated Payment Description input. Enter a template that mixes literal text with any combination of the supported variables. Keep the total length reasonable so the rendered string fits within gateway display constraints. After saving, create a test invoice, generate its Public Pay link, and walk through the full checkout flow on both PayPal and Coinbase. Verify that each variable resolves correctly and that the resulting description is readable on the hosted payment pages. Adjust spacing, punctuation, and variable order based on the test results.

ini 
payment_description = "Payment to %COMPANY_NAME% for %CLIENT_DISPLAY_NAME% (ID: %CLIENT_ID%, Ref: %CLIENT_HASH_ID%)"

#Runtime Processing and Best Practices

At the point a client opens a Public Pay URL, the WHMCS module evaluates the description template, queries the necessary client and company records, and performs the string substitutions. The processed text is then forwarded to the chosen gateway. To avoid truncation on PayPal or Coinbase, target a final length under 150 characters. Always confirm that client display names are set appropriately in their Public Pay profile to prevent unintended information from appearing. Log several test transactions to confirm the descriptions appear consistently in both the gateway dashboards and your WHMCS transaction history.

  • Combine variables with static text that clearly indicates the purpose of the payment
  • Avoid overusing variables if the resulting string becomes excessively long
  • Test descriptions across multiple clients with different display names and hash values

Start with a simple template that includes your company name and the client's display name. Expand to include the ID or hash only when internal tracking demands it. This approach delivers immediate clarity for clients while maintaining clean records on the payment processors. For further integration steps with invoicing or automated reminders, review the WHMCS Public Pay module configuration reference.