Entity Custom Fields

In this guide, you will learn about the new "Entity Custom Fields" feature, designed to empower partners to send identifiers and Risk-requested items using unlimited custom fields. By leveraging this feature, partners can ensure that their software works seamlessly, leading to increased Boarding Rates. Additionally, partners can avoid waiting for Risk to request information manually, streamlining their operations.

Enhance software functionality with the ability to send multiple identifiers and Risk-requested items.
Increase boarding rates by ensuring smooth operations and efficient data handling.
Eliminating manual information requests from Risk leads to faster processes and reduced wait times.

How It Works

These custom fields can be created on the following types of entities and their individual users via their respective Profile pages in the Portal or through an API call:

Merchant
Referrer
Facilitator

This custom field will now be associated with the entity or individual user when their Profile page is reviewed in the Portal, or when retrieving details about a user or entity using the API, such as using GET /merchants or GET /logins (Users) where the new custom field can even be used in a query to more quickly retrieve a specific user or entity.

Warning: Each custom field must be manually set as we do not provide a drop-down of previously added custom fields or an auto-complete feature.

Ensure you match your custom field exactly to ensure your risk policies, decisions, and fee rules will apply to that entity or user.

Keys and Values

Each set of entity custom fields utilizes a key: value pair similar to most coding languages to help identify each unique field and each field's unique value.

Each Key (Field) can be between 1 and 500 characters.
Each Value can be between 1 and 500 characters.

As Entity Custom Fields is the process of creating your own API parameter and value set, (also reflected in the the Portal), you’ll want to follow these industry-leading best practices to ensure all members of your team can easily find, identify, and duplicate the field as needed for each new user or entity.

Best Practices: Naming Your Keys

Simplicity: Avoid unnecessary complexity and be descriptive with your name.
Naming Convention: Choose one format - camelCase (yourField), snake_case (your_field), or kebab-case (your-field). We recommend camelCase.
1. Use the same naming convention from your CRM or other system for your Keys where applicable for easy visibility.
Use Full Words: To avoid ambiguity among developers, use full words for names (e.g. qty should be quantity).
Action-Based: For Keys that accept a Boolean value (yes|1/no|0), use action prefixes (e.g. hasAccess, isVIP, etc.)

Entity Custom Fields Setup

Now that you understand the basics and best practices for setting up a custom entity field, let’s get started.

As mentioned above, Entity Custom Fields must be set individually for each user or entity. Since no dropdown menus, duplication function, auto-complete options, or predefined lists are available to select previously-created Entity Custom Fields, it is crucial to adhere precisely to your Key naming conventions. This precision is vital to prevent any complications concerning fee application, Risk Policies, or Risk Decisions configured around this new field.

Setup for Existing Entities

Portal Setup - Existing Entities

In the expandable content below, we’ll provide the step-by-step setup process for new Entity Custom Fields in the Portal:

Step 1: Select the desired User or Entity from its Management page to access its Profile page.
- Users: Users → User Profile
- Merchants: Merchants → Merchant Profile
- Referrers: Referrers → Referrer Profile
Step 2: Under Account Overview, scroll down to the Custom Fields section.
Step 3: Click the Add Custom Field button to open the “Add Custom Field” modal.
Step 4: Set the Field name (the “Key”), and the Value you want to assign for that field.
Step 5: Click the Add button to finish creating the new Entity Custom Field.

Result: The Entity Custom Field has been added to the profile for the user or entity of your choice and can now be applied for Fee configurations or Risk Policies and Decisions.

API Reference and Setup - Existing Entities

In the expandable content below, we’ve included the API reference for the /entityCustomFields endpoint, the endpoint used to create new Entity Custom Fields overall.

We include the reference here as the request and response bodies are the steps for existing entity setup. For the API reference by itself, visit our API Documentation.

It’s important to note that this endpoint can only be used to create new entity custom fields for existing Merchants because an existing Entity ID (e.g. t1_ent_123abc4d567890efg1h2i34) is a mandatory request body parameter when sending a POST /entityCustomFields request independently.

Entity Custom Fields Headers

/entityCustomFields HTTP/1.1
Content-Type: application/json
Accept: application/json
APIKEY:{{apiKey or txnSessionKey}}
Host: api-test.payrix.com

Available HTTP Methods

Available HTTP Methods
Create	`POST /entityCustomFields`
Retrieve All	`GET /entityCustomFields`
Retrieve by ID	`GET /entityCustomFields/{id}`
Update	`PUT /entityCustomFields/{id}`
Delete	`DELETE /entityCustomFields/{id}`

ID Format

t1_ecf_123abc4d567890efg1h2i34

Request Body

{
  "entity": "t1_ent_123abc4d567890efg1h2i34",
  "key": "{New_Custom_FieldKey_Name}",
  "value": "{Your_Custom_Value_or_ID}"
}

Parameter	Type	Required	Description	Notes

Parameter

Type

Required

Description

Notes

entity

ID

Required

The ID of the Entity associated with the Custom Field.

This field is stored as a text string.

Example Format:

t1_ent_123abc4d567890efg1h2i34

key

string

Required

The Key identifier of the Entity Custom Field.

This field is stored as a text string and must contain at least 1 character.

Note: As a best practice, do not include spaces in your key title.

value

string

Required

The Value Identifier of the Entity Custom Field.

This field is stored as a text string and must contain at least 1 character and up to 500 characters.

Response Body

{
  "id": "t1_ecf_123abc4d567890efg1h2i34",
  "created": "2024-05-29T21:26:55.016Z",
  "modified": "2024-05-29T21:35:22.016Z",
  "creator": "t1_log_123abc4d567890efg1h2i34",
  "modifier": "t1_log_123abc4d567890efg1h2i34",
  "entity": "t1_ent_123abc4d567890efg1h2i34",
  "key": "{New_Custom_Field_Name}",
  "value": "{Your_Custom_Value_or_ID}",
  "deleted": null
}

Parameter	Type	Description	Notes

Parameter	Type	Description	Notes
`id`	ID	The ID of the custom field record that was just created.	This field is stored as a text string. This ID will be used to locate this custom field for modification or deletion in the future. Example Format: `t1_ecf_123abc4d567890efg1h2i34`
`entity`	ID	The ID of the Entity associated with the Custom Field.	This field is stored as a text string. Example Format: `t1_ent_123abc4d567890efg1h2i34`
`key`	string	The Key identifier of the Entity Custom Field.	This field is stored as a text string and must contain at least 1 character.
`value`	string	The Value Identifier of the Entity Custom Field.	This field is stored as a text string and must contain at least 1 character and up to 1,000 characters.
`deleted`	date-time	The date the custom field was deleted, if applicable.	Format: YYYY-MM-DD HH:MM:SS (UTC) Example: `2024-03-29T21:26:55.016Z` Will be `null` if the field has not yet been deleted.
`created`	date-time	The date the custom field was first created.	Format: YYYY-MM-DD HH:MM:SS (UTC) Example: `2024-03-29T21:26:55.016Z`
`modified`	date-time	The date the custom field was last modified, if applicable.	Format: YYYY-MM-DD HH:MM:SS (UTC) Example: `2024-03-29T21:26:55.016Z`
`creator`	ID	The User (Login) ID for the user that created the entity custom field.	This field is stored as a text string. Example Format: `t1_log_123abc4d567890efg1h2i34`
`modifier`	ID	The User (Login) ID for the user that last modified the entity custom field.	This field is stored as a text string. Example Format: `t1_log_123abc4d567890efg1h2i34`

Setup For New Entities

Sending Custom Fields with New Entities During Signup

When creating a new entity on the platform, whether during Merchant Signup or Referrer Boarding, you can optionally add the following JSON object array to the signup form at the entity data level like so:

Pre-Populated Signup Form - HTTP Query String

As mentioned above, you can send multiple entity custom fields at once within the Entity creation HTTP query by simply duplicating the section above as needed and giving each new duplicate section new, unique key names.

Applying Entity Custom Fields with Risk Policies

By utilizing Entity Custom Fields in conjunction with Risk Decisions or Policies, you can significantly enhance your risk management processes. Risk Assessment is made more effective through personalization for specific entities using Entity Custom Fields. Integration with Risk Decisions or Policies enhances decision-making through entity-specific data insights allowing improved entity compliance and higher boarding rates by organizing your customized compliance-related information to better align to your individual risk practices. Efficient Risk Monitoring in real-time becomes possible by utilizing Entity Custom Fields to monitor key risk indicators, encouraging holistic risk management practices.