Adding Custom Input Fields

If your doDeal request defines custom user data elements (UserData1...UserData10) inside the customerData element, then you can use the userData array inside uiCustomData to display text inputs on the payment page in order to collect and validate information for these custom user data elements.

Once submitted to Hyp via a payment page, custom user data elements are saved in Hyp's database and can be later retrieved by the merchant via the inquireTransaction API. They are also included in the response XML and, if this is enabled in Hyp console, appear in transaction reports.

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:

   <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:

   <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

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

<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:

<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:

<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

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 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