Set Up Entity Custom Fields

Create and access Entity Custom Fields through the Payrix Pro Portal to ensure seamless risk reviews and external data integration. The following sections describe how to create custom fields, assign them to merchants, and use field values to automate risk decisions.

Prerequisites

Before creating and assigning Entity Custom Fields, decide on the following values for each custom field:

Field: The name of the actual field. This can be between 1 and 500 characters. See the next section for best practices.
Label: The label the merchant sees for the field while signing up. This can be between 1 and 500 characters.
Required: A yes or no value on whether to make the custom field mandatory during signup.
Default: An optional default value to prefill the field.

Field Naming Best Practices

Entity Custom Fields use a key-value approach, similar to standard coding languages, to uniquely identify each field and its value. Follow these industry best practices to ensure all members of your team can easily find, identify, and duplicate the field as needed for each entity:

Use simplicity: Avoid unnecessary complexity and be descriptive with your name.
Set field formats: Choose one format: camel case (yourField), snake case (your_field), or kebab case (your-field). We recommend camel case.
Be consistent: Match field names to those used in your CRM or other system, where applicable, for easier visibility and integration.
Use full words: To avoid ambiguity among developers, use full words for names (for example, quantity instead of qty).
Use verbs for Booleans: For fields that accept a Boolean value (yes/1 or no/0), use verb prefixes (such as hasAccess or isVIP).

Create and Assign Entity Custom Fields

After deciding which Entity Custom Fields you want to add, assign them to individual merchants. Because the portal doesn’t offer dropdown menus, duplication function, autocomplete options, or predefined lists to select previously created Entity Custom Fields, you must adhere precisely to your field naming conventions. This precision is vital to prevent any complications concerning fee application, risk policies, or decisions configured around this new field.

Notes
You must manually set each custom field because we do not provide a dropdown menu of previously added custom fields or an autocomplete feature.
You must match your custom field exactly to ensure your risk policies, decisions, and fee rules will apply to that entity.

Send Custom Fields with Merchants During Signup

You can include Entity Custom Fields on your Merchant Signup Form. To add these fields for merchants to complete during signup:

Open an Implementation Services ticket.
Provide the Fields, Label, Required, and Default values for each custom field.

After the Implementations team adds your Entity Custom Fields, the signup form displays each field to merchants during onboarding.

Assign New Custom Fields to a Merchant

You can assign custom fields to store merchant‑specific values. You can then use those values to apply fee configurations, risk policies, and automated risk decisions.

Follow these steps in the portal to create and assign new Entity Custom Fields for an existing merchant:

Select Merchants under Management in the main side bar.
Select the merchant to go to their profile page.
Scroll down to the Custom Fields section on the Business tab.
Click Add Custom Field to open the Add Custom Field dialog.
Enter the field and the value that you want to assign.
Click Add to finish creating the custom field.

The merchant receives the new custom field for storing unique values. These values can be applied for fee configurations or risk policies and decisions.

Trigger Risk Policies with Entity Custom Fields

Use Entity Custom Fields with risk decisions or policies to enhance risk management automations. This integration provides entity-specific data insights and improves boarding rates by aligning compliance-related information with your risk practices.

Complete the following procedure to use an Entity Custom Field as the rule condition for a policy or decision. To simplify the setup, this procedure includes only the high-level action items. For more detailed setup steps and information on risk policies, see Use the Risk Management Page and Policies.

To configure a risk policy using a custom field as criteria to trigger the risk:

Select Risk then Policies under Admin in the main side bar.
Click Add Policy to create a new policy.
Define the Name, Stage, Target, and Status components.
Click Add Policy.
Select the new policy from the table to add decisions.
Click Add Decision.
Select the primary Decision from the list available, then click Next.
Select ENTITY_CUSTOM from the dropdown menu as your sub-decision.
Enter your custom field name and set your Value.
Set your Operator and Action, then click Next.
Add any Rules, Dependencies, and Failover Dependencies.
Click Create to complete the process.