Configure custom hosted cashier properties

This topic describes how to use and configure custom cashier properties. For information on how to use hosted cashiers, see Cashier.

Use custom cashier properties to obtain more information from the customer when using a hosted cashier. Rebilly accepts custom fields that are provided in a JSON file with structures that are compliant with the JSON schema draft 4, 6, and 7.

Hosted cashiers render custom properties as form inputs that follow JSONForms rules. For more information, see the JSONForms documentation.

The following are examples of how to use custom fields:

Required fields

Use the property required to make some properties mandatory.

Example:

Copy
Copied
{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "title": "Email",
      "maxLength": 64,
      "format": "email"
    }
      ...
  },
    "required": ["email"]
}

String input

Use the string JSON-schema type to render input types text, textarea, or date with the following basic rules:

JSON field Description
property key Label property for and input properties id and name.
title Label text in the cashier request form.
maxLength Determines input type. The default type is text. For values greater or equal to 255, the HTML element is <textarea>.
format Sets the input as a specific format. Accepted values are date, date-time and email.

Example JSON schema:

Copy
Copied
{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "title": "Email",
      "maxLength": 64,
      "format": "email"
    },
    "donation_message": {
      "type": "string",
      "title": "Do you want to leave a message?",
      "maxLength": 255
    },
    "dob": {
      "type": "string",
      "title": "Date of birth",
      "format": "date"
    }
  }
}

Numeric input

To render the HTML input type number, use the number or integer JSON-schema types with the following rules:

JSON field Description
property key Label property for and input properties id and name.
title Label text in the cashier request form.
type Restricts the type of numbers. If type is integer, the engine sets HTML step to 1. For type number no step size is set.
minimum Sets the minimum valid value.
maximum Sets the maximum valid value.
exclusiveMinimum Sets the minimum value, the value is excluded. When used, the minimum keyword has no effect.
exclusiveMaximum Sets the maximum value, the value is excluded. When used, the maximum keyword has no effect.

Example JSON schema:

Copy
Copied
{
  "type": "object",
  "properties": {
    "age": {
      "type": "integer",
      "title": "What is your age?",
      "exclusiveMinimum": 21
    },
    "rate": {
      "type": "number",
      "title": "In a scale from 0 to 10, How would you rate this service?",
      "minimum": 0,
      "maximum": 10
    }
  }
}

Single selection dropdown input

To limit the dropdown input to a single option, use a primitive type for the property. Two strategies can be used to render a dropdown menu. Depending on your needs, select of one of the following:

Enumerator property

Use the enum property to render a dropdown selection.

warning

The enum property does not enable you to customize the label for each individual option. The engine renders the option value as both the label and the value. If you must customize labels, see Combined objects.

The JSON properties rules are:

JSON field Description
property key Label property for and input properties id and name.
title Label text in the cashier request form.
type Type of the enum items. For example string
enum List of valid values for the property. Only this values are valid.

Example JSON schema:

Copy
Copied
{
    "type": "object",
    "properties": {
        "single-selector-string": {
            "title": "the label for the input form",
            "type": "string",
            "enum": [
                "foo",
                "bar",
                "joe"
            ]
        },
        "single-selector-numeric": {
            "title": "the label for the input form",
            "type": "integer",
            "enum": [
                1,
                2,
                3
            ]
        }
    }
}

Combined objects

Use the schema composition operator oneOf to combine a set of items to render a single dropdown selection. Use JSON schema constants to set the options. For more information on constants, see JSON schema constant values.

The JSON properties rules are:

JSON field Description
property_key Label property for and input properties id and name.
title Label text in the cashier request form.
oneOf.title Label text for the option.
oneOf.const Valid value of the option to store.

Example JSON schema:

Copy
Copied
{
    "type": "object",
    "properties": {
        "single-selector-string": {
            "title": "the label for the input form",
            "type": "string",
            "oneOf": [
                {
                    "const": "foo",
                    "title": "The Foo option"
                },
                {
                    "const": "bar",
                    "title": "The Bar option"
                }
            ]
        },
        "single-selector-numeric": {
            "title": "the label for the input form",
            "type": "integer",
            "oneOf": [
                {
                    "const": 1,
                    "title": "The 1 option"
                },
                {
                    "const": 2,
                    "title": "The 2 option"
                }
            ]
        }
    }
}

Multiple selection dropdown input

To render HTML input as a multiselect dropdown, use the JSON schema type array in combination with the oneOf composition operator. Each of the options is a JSON schema constant. For more information on constants, see JSON schema constant values.

The JSON properties rules are:

JSON field Description
property_key Label property for and input properties id and name.
title Label text in the cashier request form.
uniqueItems Boolean property used to denote that each item is unique.
items List of the object schemas for each of the available options.
item.title Label text for the option.
item.const Valid value of the option to store.

Example JSON schema:

Copy
Copied
{
  "type": "object",
  "properties": {
    "multiple-selector": {
      "title": "the label for the input form",
      "type": "array",
      "uniqueItems": true,
      "items": {
        "oneOf": [
          {
            "const": "foo",
            "title": "The Foo option"
          },
          {
            "const": "bar",
            "title": "The Bar option"
          }
        ]
      }
    }
  }
}