Cards & Wallets · PaySuite payment page · Advanced features

Custom Fields

Send custom fields when you create a PaySuite Payment Page session to capture extra information from your customer, such as discount codes or terms acceptance.

For an overview of custom fields, including how they work when using the PaySuite Payment Page, see Custom fields.

Within the PaySuite Payment Page you can configure fields for customer input, examples include:

the type of field: text entry field, multiple radio button selection, multiple dropdown selection or simply additional text on page
the content of the field: default values, options available, masked values
text for the field label
the name of the field that we’ll send back to you in responses, call-backs and notifications if it needs to differ from the customer facing description
the position of the field on the hosted page: form top (before the payment capture fields) or form bottom (after the payment capture fields).

When you create a hosted payment session, add a customFields object to the request body. It contains an array called dataFieldOrTextFieldOrLabelField, where each element can be one of the following types:

Field type	Description
`dataField`	A plain name/value field.
`textField`	A text entry field shown on the hosted page.
`labelField`	Additional descriptive text shown on the hosted page.
`radioField`	A set of radio buttons with predefined options.
`passwordField`	A masked text entry field.
`selectField`	A dropdown list with predefined options.
`skinField`	A field passed to the skin for custom rendering.

Common properties for each field are:

Property	Type	Description
`name`	string	The field name returned to you in responses, callbacks and notifications.
`value`	string	The default or selected value of the field. For `skinField` this can be a JSON string.
`transient`	boolean	If `true`, the value is not stored as part of the transaction.
`locator`	string	Where the field appears on the page. Use `FORM_TOP` for before the payment fields, or `FORM_BOTTOM` for after them.
`options`	object	For `radioField` and `selectField`, the list of choices with `label` and `value` pairs.
`maxLength`	integer	For `passwordField`, the maximum number of characters.
`format`	string	For `skinField`, the content type of the value, for example `application/json`.

Create a hosted payment session with custom fields

The example below creates a payment session with several custom fields. The values your customer enters are returned to you on the transaction, in callbacks and in notifications.

Create a payment session with custom fields

EndpointDefinition

POST /hosted/rest/sessions/{instId}/payments

Request body

{
  "session": {
    "returnUrl": {
      "url": "https://www.example.com/return"
    }
  },
  "transaction": {
    "money": {
      "currency": "GBP",
      "amount": {
        "fixed": 10.00
      }
    },
    "merchantReference": "SESS-CF-0001"
  },
  "customFields": {
    "dataFieldOrTextFieldOrLabelField": [
      {
        "dataField": {
          "name": "customerAccountRef",
          "value": "CUST-1234",
          "transient": false
        }
      },
      {
        "labelField": {
          "name": "discountLabel",
          "value": "Have a discount code? Enter it below.",
          "transient": true,
          "locator": "FORM_TOP"
        }
      },
      {
        "textField": {
          "name": "discountCode",
          "value": "SUMMER2025",
          "transient": false,
          "locator": "FORM_TOP"
        }
      },
      {
        "selectField": {
          "name": "deliveryOption",
          "value": "standard",
          "transient": false,
          "locator": "FORM_BOTTOM",
          "options": {
            "option": [
              {
                "label": "Standard delivery",
                "value": "standard"
              },
              {
                "label": "Next day delivery",
                "value": "nextday"
              }
            ]
          }
        }
      },
      {
        "radioField": {
          "name": "termsAccepted",
          "value": "yes",
          "transient": false,
          "locator": "FORM_BOTTOM",
          "options": {
            "option": [
              {
                "label": "I accept the terms and conditions",
                "value": "yes"
              },
              {
                "label": "I do not accept",
                "value": "no"
              }
            ]
          }
        }
      },
      {
        "passwordField": {
          "name": "membershipNumber",
          "value": "",
          "transient": false,
          "locator": "FORM_TOP",
          "maxLength": 11
        }
      }
    ]
  }
}

cURL

curl -X POST "{targetEnvironmentPath}/hosted/rest/sessions/{instId}/payments" \
  -u "{apiUser}:{apiPassword}" \
  -H "Content-Type: application/json" \
  -d '{
  "session": {
    "returnUrl": {
      "url": "https://www.example.com/return"
    }
  },
  "transaction": {
    "money": {
      "currency": "GBP",
      "amount": {
        "fixed": 10.00
      }
    },
    "merchantReference": "SESS-CF-0001"
  },
  "customFields": {
    "dataFieldOrTextFieldOrLabelField": [
      {
        "dataField": {
          "name": "customerAccountRef",
          "value": "CUST-1234",
          "transient": false
        }
      },
      {
        "labelField": {
          "name": "discountLabel",
          "value": "Have a discount code? Enter it below.",
          "transient": true,
          "locator": "FORM_TOP"
        }
      },
      {
        "textField": {
          "name": "discountCode",
          "value": "SUMMER2025",
          "transient": false,
          "locator": "FORM_TOP"
        }
      },
      {
        "selectField": {
          "name": "deliveryOption",
          "value": "standard",
          "transient": false,
          "locator": "FORM_BOTTOM",
          "options": {
            "option": [
              {
                "label": "Standard delivery",
                "value": "standard"
              },
              {
                "label": "Next day delivery",
                "value": "nextday"
              }
            ]
          }
        }
      },
      {
        "radioField": {
          "name": "termsAccepted",
          "value": "yes",
          "transient": false,
          "locator": "FORM_BOTTOM",
          "options": {
            "option": [
              {
                "label": "I accept the terms and conditions",
                "value": "yes"
              },
              {
                "label": "I do not accept",
                "value": "no"
              }
            ]
          }
        }
      },
      {
        "passwordField": {
          "name": "membershipNumber",
          "value": "",
          "transient": false,
          "locator": "FORM_TOP",
          "maxLength": 11
        }
      }
    ]
  }
}'

Response

HTTP/1.1 201 Created

{
  "sessionId": "SMjrMTP1q7iRK4YIMxyfAbza5",
  "redirectUrl": "https://secure.mite.pay360.com/hosted/SMjrMTP1q7iRK4YIMxyfAbza5/begin/SMjrMTP1q7iRK4YIMxyfAbza5",
  "status": "SUCCESS"
}