Cascading Dropdowns

🚧

Cash Pickup

Support for cascading dropdowns is required to enable the Cash Pickup transfer method.

In some scenarios, the value selected in one field will impact the possible values of another field. For example, when entering an address, the list of possible states/provinces changes based on the selected country. To support this functionality within dynamic fields, the DROPDOWN field type supports Field Identifiers within the optionsSource property.

Below is an example of a response from GET /recipient-fields

{
  "fields": [
   {
      "fieldType": "DROPDOWN",
      "fieldId": "COUNTRY",
      "options": [
        {
          "id": "MEX",
          "name": "Mexico"
        },
        {
          "id": "IND",
          "name": "India"
        }
      ],
      "name": "Country",
      "isRequired": true
    },
    {
      "fieldType": "DROPDOWN",
      "fieldId": "STATE",
      "optionsSource": "https://sandbox-api.readyremit.com/v1/states-and-provinces?countryIso3Code={COUNTRY}",
      "name": "State",
      "isRequired": true
    }
  ]
}

In the example above, the STATE field is a DROPDOWN field type with an optionsSource property. The value of the optionsSource is a URL containing a reference to the field COUNTRY (note that field references are contained within braces { }).

The identifier in the optionsSource property is an indicator to the API consumer that this field is a dependency. Fields can have any number of dependencies, and should remain disabled until all the dependencies have been met.

In this example, the STATE field is dependent on the COUNTRY field so the STATE field would remain disabled or uneditable until the field with the fieldId equal to COUNTRY has a valid value. Once this dependency is met, the optionsSource URL can be built by replacing all the dependency identifiers. So if the user selected MEX from the COUNTRY field, the optionsSource of the STATE field would change from

https://sandbox-api.readyremit.com/v1/states-and-provinces?countryIso3Code={COUNTRY}

to

https://sandbox-api.readyremit.com/v1/states-and-provinces?countryIso3Code=MEX

Once the optionsSource URL is built it can be used to fetch the values for populating the dropdown.

🚧

The isRequired Property

In most scenarios, any field marked as isRequired: false can be hidden from a user but it's possible that a field is marked as isRequired: false but is also a dependency of another field. Any field that is a dependency is another field should always be shown to the user regardless of whether or not it is marked as isRequried