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 Hosted deposit API integration.
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 field | Description |
|---|---|
| property key | Label property for and input properties id and name. |
| title | Label text in the hosted deposit 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:
{
"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 hosted deposit 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:
{
"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:
- Use the enumerator property.
- Use combined objects.
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 field | Description |
|---|---|
| property key | Label property for and input properties id and name. |
| title | Label text in the hosted deposit 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:
{
"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 hosted deposit form. |
| oneOf.title | Label text for the option. |
| oneOf.const | Valid 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 field | Description |
|---|---|
| property_key | Label property for and input properties id and name. |
| title | Label text in the hosted deposit 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:
{
"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"
}
]
}
}
}
}