> For the complete documentation index, see [llms.txt](https://developers.hyp.co.il/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.hyp.co.il/enterprise/changing-the-default-payment-page-appearance/adding-custom-input-fields.md).

# Adding Custom Input Fields

In some cases, you may want to collect or pass additional information that is not part of the standard request. Hyp Enterprise allows you to use up to ten custom user data elements (`userData1` to `userData10`) that can be useful in different ways:

* **System reconciliation**: You can pass internal identifiers from your CRM, ERP, or accounting software (such as a customer ID). Since these values are saved with the transaction, they make it easier to reconcile sales data between Hyp and your own systems later.
* **Order metadata**: You can attach specific details about the purchase that aren't captured by standard fields. Examples include a flight number for travel bookings or a policy number for insurance premiums.
* **Custom data collection**: If you don't already have certain information about a customer, you can use the payment page to collect it at the moment of purchase. This is useful for gathering details like a gift message or a preferred delivery time slot.

If your `doDeal` request defines custom user data elements inside the `customerData` element, you can then use the `userData` array inside `uiCustomData` to display text inputs on the payment page. This allows you to collect and validate custom information directly from the customer.

{% hint style="info" %}
Once submitted to Hyp via a payment page, custom user data elements are saved in Hyp's database. You can later retrieve them via the [inquireTransaction API](https://developers.hyp.co.il/enterprise/inquiring-transactions/overview.md). They are also included in the response XML and, if enabled in your Hyp Console, they will appear in your transaction reports.
{% endhint %}

To use custom user data, you first need to include the desired elements in your `doDeal` request.

For example, if you want to collect the customer's name on the payment page, you can:

1. Include a `userData1` element inside the `customerData` element of your `doDeal` request:

   ```xml
   <ashrait>
    <request>
      ...
      <doDeal>
      ...
        <customerData>
          <userData1/>
        </customerData>
      </doDeal>
    </request>
   </ashrait>
   ```
2. Include an object with `id=1` in the `userData` array inside `uiCustomData` to display a text field that collects the name on the payment page:

   ```json
   <paymentPageData>
       <ppsJSONConfig>
           {
            "uiCustomData": {
               "userData": [
                 {
                    "id": 1,
                    "label": "Your full name",
                    "required": true,
                    "readonly": false,
                    "size": 150,
                    "minLength": 5,
                    "maxLength": 125
                 }
               ]
             }
           }
       </ppsJSONConfig>
   </paymentPageData>
   ```

Your payment page would then look like this:

![Payment page with a custom field](https://3255314327-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQDmIAW4sQ20lCItJGzcS%2Fuploads%2Fgit-blob-f16530947746d3ee903a01e04f5cb43d480ae29c%2Fimage.png?alt=media)

If you define multiple custom user data elements (and you can define up to 10), you can add them all to the `userData` array:

```json
<paymentPageData>
    <ppsJSONConfig>
        {
          "uiCustomData": {
            "userData": [
              {
                "id": 1,
                "label": "Your full name",
                "required": false,
                "readonly": false,
                "size": 150,
                "minLength": 5,
                "maxLength": 125
              },
              {
                "id": 5,
                "label": "Your email address",
                "required": true,
                "readonly": false,
                "size": 100,
                "minLength": 5,
                "maxLength": 100
              }
            ]
          }
        }
    </ppsJSONConfig>
</paymentPageData>
```

If a `userData` element inside `customerData` contains a default value, and you choose to display the corresponding input field on the payment page, then the default value will appear in the input field. Otherwise, the input field will be initially empty.

For example, you may want to pass the customer name from your records but enable the customer to modify it, such as updating an informal name to a full legal name. In this case, the `userData` XML element inside `customerData` could look like this:

```xml
<ashrait>
    <request>
        ...
        <doDeal>
            ...
            <customerData>
                <userData1>Jenny Parkington</userData1>
            </customerData>
        </doDeal>
    </request>
</ashrait>
```

Inside `uiCustomData` in `ppsJsonConfig`, you could then define the `userData` array like this:

```json
<paymentPageData>
    <ppsJSONConfig>
        {
          "uiCustomData": {
            "userData": [
              {
                "id": 1,
                "label": "Your full legal name",
                "required": true,
                "readonly": false,
                "size": 150,
                "minLength": 5,
                "maxLength": 125
              }
            ]
          }
        }
    </ppsJSONConfig>
</paymentPageData>
```

Then your payment page will display the default value "Jenny Parkington" in the input field, allowing the customer to change it to "Jennifer L. Parkington":

![Default value in a custom input field](https://3255314327-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQDmIAW4sQ20lCItJGzcS%2Fuploads%2Fgit-blob-0c82127ff449e5d118783f1ce9e9aa993d3f163d%2Fimage.png?alt=media)

Sometimes, you may want to pass a piece of custom data to Hyp without displaying it on the payment page. One example is passing a unique transaction identifier. To do this, simply define the `userData` element inside `customerData` and do not include it in the `userData` array inside `uiCustomData`. This will make sure that the field is not displayed in the payment page, but its value will be passed to Hyp as a hidden field.

All properties that you can use for an object inside the `userData` array are listed in the table below:

| Property    | Type    | Description                                                                                                                                                                               | Mandatory? | Default value |
| ----------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------------- |
| `id`        | Number  | User data ID. The value should be between 1 and 10 and correspond to the number in the name of the `userData` element inside `customerData`.                                              | Yes        |               |
| `label`     | String  | The label for the input field on the payment page.                                                                                                                                        | Yes        |               |
| `required`  | Boolean | Indicates if the customer is required to fill in the field.                                                                                                                               |            | False         |
| `minLength` | Number  | Minimum length of the input field value that the customer enters on the payment page.                                                                                                     |            | 0             |
| `maxLength` | Number  | Maximum length of the input field value that the customer enters on the payment page. Hyp Enterprise does not support `maxLength` higher than 256.                                        |            | 256           |
| `readonly`  | Boolean | Indicates if the value in the input field should only be shown to the customer without allowing them to change it. Make sure to only set this to `true` if you provide the default value. |            | False         |
| `size`      | Number  | The width of the input field in units between 0 and 300. Every 50 units correspond to 2 columns in the payment page's responsive column layout.                                           |            | 100           |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.hyp.co.il/enterprise/changing-the-default-payment-page-appearance/adding-custom-input-fields.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
