Developer docs
/
Deposits
/
Configure custom hosted deposit properties
Last updated

These docs are intended for a developer audience.

Configure custom hosted deposit properties

This topic describes how to use and configure custom deposit properties. For information on how to use hosted deposit forms, see Deposits.

Use custom deposit properties to obtain more information from the customer when using a hosted deposit. 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 deposits 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:

{
  "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 fieldDescription
property keyLabel property for and input properties id and name.
titleLabel text in the hosted deposit form.
maxLengthDetermines input type. The default type is text. For values greater or equal to 255, the HTML element is <textarea>.
formatSets the input as a specific format. Accepted values are date, date-time and email.

Example JSON schema:

{
  "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 fieldDescription
property keyLabel property for and input properties id and name.
titleLabel text in the hosted deposit form.
typeRestricts the type of numbers. If type is integer, the engine sets HTML step to 1. For type number no step size is set.
minimumSets the minimum valid value.
maximumSets the maximum valid value.
exclusiveMinimumSets the minimum value, the value is excluded. When used, the minimum keyword has no effect.
exclusiveMaximumSets the maximum value, the value is excluded. When used, the maximum keyword has no effect.

Example JSON schema:

{
  "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.

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 fieldDescription
property keyLabel property for and input properties id and name.
titleLabel text in the hosted deposit form.
typeType of the enum items. For example string
enumList of valid values for the property. Only this values are valid.

Example JSON schema:

{
  "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 fieldDescription
property_keyLabel property for and input properties id and name.
titleLabel text in the hosted deposit form.
oneOf.titleLabel text for the option.
oneOf.constValid value of the option to store.

Example JSON schema:

{
  "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 fieldDescription
property_keyLabel property for and input properties id and name.
titleLabel text in the hosted deposit form.
uniqueItemsBoolean property used to denote that each item is unique.
itemsList of the object schemas for each of the available options.
item.titleLabel text for the option.
item.constValid value of the option to store.

Example JSON schema:

{
  "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"
          }
        ]
      }
    }
  }
}