> For the complete documentation index, see [llms.txt](https://docs.norrnext.com/unzer-hpp-for-phoca-cart/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.norrnext.com/unzer-hpp-for-phoca-cart/faq.md).

# FAQ

Frequently asked questions and troubleshooting guide for Unzer HPP for Phoca Cart.

### 1. Where can I find test card details to test the plugin in Sandbox mode?

To test the payment workflow without transferring real money:

1. Enter your test API keys in the payment method settings (Private Key starting with `s-priv-` and Public Key starting with `s-pub-`).
2. Use the official test card credentials provided in the [Unzer Test Cards Documentation](https://docs.unzer.com/reference/test-cards/).

Unzer provides test credit card numbers for various scenarios, including successful payments, 3D Secure challenges, and declined transactions.

***

### 2. Payment is completed in Unzer, but the order remains "Pending" in Phoca Cart

If an order status is not updated to **Payment Completed** after a successful transaction, check the following common causes:

* **2.1. Asynchronous Payment Methods**\
  Certain payment methods (e.g., SEPA Direct Debit, bank transfers) take additional time to clear. Unzer sends the `payment.completed` webhook only once the funds are fully settled.
* **2.2. Public API Key Mismatch**\
  The plugin validates incoming webhook requests by matching the incoming `publicKey` property against the **Public API Key** configured in your payment method settings. If the public key is missing or does not match the private key pair, the webhook payload is rejected. Ensure your configured Public and Private keys belong to the exact same Unzer project.
* **2.3. Security Extensions Blocking Webhook Requests**\
  Security extensions (such as **RSFirewall!**, **Admin Tools**, or external Web Application Firewalls like Cloudflare) may intercept and block incoming POST requests sent from Unzer to the Phoca Cart webhook endpoint (`index.php?option=com_phocacart&view=response&task=response.paymentwebhook...`).
  * Solution: Whitelist the Phoca Cart webhook URL in your security extension or firewall settings.
* **2.4. Verify with Debug Logging**\
  Enable **Debug** mode in the payment method settings and inspect recent entries in **Phoca Cart > Logs**. The log will record whether webhook calls were received, whether payloads were valid, and any error details.

***

### 3. How do I enable additional payment methods (Credit Cards, PayPal, Klarna, SEPA, etc.)?

Available payment methods are managed on Unzer's platform:

1. Check the available payment options on the [Unzer Payment Methods](https://docs.unzer.com/payment-methods/) page.
2. Contact your Unzer account manager or the Unzer support team to activate the desired payment methods for your merchant account.
3. Once activated by Unzer, the new payment methods will automatically appear on the Hosted Payment Page during checkout. No changes inside Phoca Cart are required.

***

### 4. "Total amount does not match! Please contact our shop support" — What does it mean and how to fix it?

This message appears when **Send Order Items** is enabled and a calculation discrepancy is detected between the total order gross amount and the aggregated sum of all individual basket line items (products, options/variants, taxes, shipping costs, payment fees, or discounts).

To resolve:

1. Enable **Debug** in the Unzer payment method options.
2. Perform a test checkout to trigger the issue and inspect the logged amounts under **Phoca Cart > Logs** (look for `Payment - Unzer HPP - ERROR: Total amount mismatch`).
3. Verify your Phoca Cart tax calculation rules, discount coupon setups, and shipping calculations.
4. If the discrepancy persists due to a complex tax or rounding scenario, please contact [NorrNext Support](https://norrnext.com/support/helpdesk) with the debug log details.

***

### 5. "Phone number must be at least 7 digits" error

When **Create Customer** is enabled, Unzer requires a valid phone number in international or standard numeric format (between 7 and 23 digits, compliant with E.164 conventions).

If a customer submits an invalid phone number or a number with fewer than 7 digits, the plugin prevents the API call and prompts the customer to verify their contact details before redirecting.

***

### 6. "Payment plugin configuration error. Please contact site administrator"

This error indicates that the **Private API Key** has not been configured in the payment method settings in Phoca Cart. Go to **Phoca Cart > Payment Methods > \[Your Unzer Payment Method] > Payment Method Options** and enter your Private API Key.

***

### 7. Does Unzer HPP support 3D Secure (3DS2) and SCA?

Yes. The Unzer Hosted Payment Page fully supports **3D Secure 2 (3DS2)** and **Strong Customer Authentication (SCA)** under the European Revised Payment Services Directive (PSD2).

When a card payment requires customer authentication, Unzer automatically initiates the 3DS challenge dialog directly within the hosted payment interface without requiring any extra setup on your Joomla site.

***

### 8. Is the plugin PCI DSS compliant?

Yes. Because this plugin uses the **Unzer Hosted Payment Page (HPP)**, all sensitive credit and debit card information is entered directly on Unzer's PCI DSS Level 1 certified servers.

Your Joomla server never captures, processes, or stores credit card numbers, CVVs, or cardholder data. This dramatically reduces your PCI DSS compliance scope (typically to SAQ A), providing security and peace of mind for both you and your shoppers.