# Set Up Zuora Payment Forms

Limio now supports **Zuora Payment Forms (ZPFs)** as a secure, PCI-compliant way for customers to enter payment details directly within your Limio checkout. This functionality builds on Zuora’s [Payment Forms and Payment Links](https://knowledgecenter.zuora.com/Zuora_Payments/Process_payments/Payment_Forms_and_Payment_Links) and allows you to configure country and currency–specific forms that map to the correct Zuora gateway.

{% hint style="info" %}
This feature was introduced in [Release 109](https://docs.limio.com/release-notes/limio-commerce-release-notes/readme/limio-release-notes-release-109)
{% endhint %}

### Pre-requisites

* You have a Zuora tenant with Payment Forms enabled.
* You have a Zuora **Payment Gateway** configured.
* You have admin access in Limio (to manage settings).
* *(Optional but recommended)* [reCAPTCHA enabled](https://docs.limio.com/product/settings/browser/security/recaptcha-bot-protection) to prevent bot abuse.

### 1. Set up in Zuora

1. In Zuora, go to **Payments → Setup Payment Forms and Payment Links → Payment Forms**.
2. Create a new **Payment Form** or copy the default one.
3. Configure regions, fields, and styling (button, layout, colours) as needed.
4. Copy the **Publishable Key** and **Payment Form Number (PF-xxxxx)**.
5. Make sure you have a **default Payment Gateway** (or specify one later when creating the session).

For more information please refer to the [Zuora Documentation](https://knowledgecenter.zuora.com/Zuora_Payments/Process_payments/Payment_Forms_and_Payment_Links).

### 2. Set up in Limio

Here’s how to configure Limio so the Payment Forms are used correctly.

#### Basic Configuration

<figure><img src="https://3950144701-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKxTpA9AeeNYx1ml6UpHj%2Fuploads%2FxG4AX2PZnIVtvujaZfn6%2Fimage.png?alt=media&#x26;token=42949e37-10c1-4ba7-a73e-a9c633917385" alt=""><figcaption></figcaption></figure>

1. In Limio dashboard, go to **Settings → Zuora → Payment Form Pages**
2. Add a new form configuration. Fill out:

   | Field                             | What to set / example                                                                         |
   | --------------------------------- | --------------------------------------------------------------------------------------------- |
   | Page URL                          | The Zuora Payment Form URL (e.g. `https://apisandbox.zuora.com/apps/PublicHostedPageLite.do`) |
   | Zuora Page Height                 | e.g. `400px`, `500px` — height for the iframe on checkout                                     |
   | Country Codes                     | Which countries this payment form applies to                                                  |
   | Currency Codes                    | Which currencies this payment form applies to                                                 |
   | Form Number / Payment Form Number | The identifier you got from Zuora                                                             |
   | Publishable Key                   | From Zuora                                                                                    |
   | Payment Gateway ID                | From Zuora                                                                                    |
   | Payment Gateway Name              | Friendly name used in UI / reporting                                                          |
3. Save.
4. In your *Offer* definitions in Limio, ensure **Payment Type** includes “Zuora Payment Form” so customers see this option.

### 3. Customer checkout flow

#### Acquisition

Zuora Payment Form are supported in Limio's [https://docs.limio.com/product/checkout/overview-how-to-customise-the-limio-modular-checkout](https://docs.limio.com/product/checkout/overview-how-to-customise-the-limio-modular-checkout "mention").

<figure><img src="https://3950144701-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKxTpA9AeeNYx1ml6UpHj%2Fuploads%2F2RvNQbJEXuSivjNMPlbU%2Fimage.png?alt=media&#x26;token=19657202-2a14-4154-9397-07b394b8a216" alt=""><figcaption></figcaption></figure>

Once set up:

* Upon checkout, Limio will fetch the appropriate Form configuration based on the user’s basket (country & currency).
* Limio will request a **payment session token** from Zuora via an API (secure).
* The Zuora Form is rendered as configured in Zuora to collect payment details.
* On submission, the payment method is stored in Zuora.
* The order is processed according to your defined payment settings.

#### Self-service

Zuora Payment Form is supported in [https://docs.limio.com/components/component-library/self-service-components/component-self-service-form](https://docs.limio.com/components/component-library/self-service-components/component-self-service-form "mention").

{% hint style="warning" %}
Zuora Payment Form is not supported in legacy Self-Service components such as [https://docs.limio.com/components/component-library/legacy-configuration-components/component-payments-table](https://docs.limio.com/components/component-library/legacy-configuration-components/component-payments-table "mention"). You can still use [Zuora Hosted Payment Methods Pages](https://docs.limio.com/integrations/zuora-integration/configuring-payment-gateways/how-to-set-up-zuora-hosted-payment-methods-for-limio) .
{% endhint %}

### 4. Common issues & troubleshooting

| Symptom                                 | Possible cause                                          | What to check                                                                                          |
| --------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| No form shows up for certain customers  | No matching country & currency configuration            | Verify your Limio configuration includes the country/currency of the user’s basket                     |
| Payment session generation fails        | Misconfigured API credentials or gateway in Zuora       | Check your Zuora credentials, gateway ID, that form is active                                          |
| Styling / layout looks off in checkout  | CSS in Zuora Form height misset                         | Adjust height or use CSS overrides in Zuora or Limio (or ensure correct page height in Limio settings) |
| Required fields missing or not enforced | Form misconfigured in Zuora; fields not marked required | In Zuora Payment Form settings, ensure field visibility/requirement correctly set                      |