Entity Custom Fields

Updated
  • Updated on Jun 10, 2025
  • Published on May 13, 2025
  • 8 minute(s) read
Prev Next

Entity Custom Fields  empower partners to send identifiers and Risk-requested items with new entities 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 through their respective Profile pages in the Portal or through an API call:

  • Merchant

  • Partner

  • 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.

Important!

Each custom field must be manually set because we do not provide a dropdown menu of previously added custom fields or an auto-complete feature.

You must 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 uses 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.

Key (Field) Naming Best Practices

As Entity Custom Fields is the process of creating your own API parameter and value set (also reflected in 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:

  1. Simplicity: Avoid unnecessary complexity and be descriptive with your name.

  2. Naming Convention: Choose one format: camel case (yourField), snake case (your_field), or kebab case (your-field). We recommend camel case.

    1. Use the same naming convention from your CRM or other system for your Keys where applicable for easy visibility.

  3. Use Full Words: To avoid ambiguity among developers, use full words for names (for example, qty should be quantity).

  4. Action-Based: For Keys that accept a Boolean value (yes|1/no|0), use action prefixes (such as hasAccess or isVIP).

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. Because no dropdown menus, duplication function, auto-complete options, or predefined lists are available to select previously created Entity Custom Fields, you must 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 for Existing Entities

Complete the following steps to set up new Entity Custom Fields in the Portal:

  1. Select the desired User or Entity from its Management page to access its Profile page.

  2. Under Account Overview, scroll down to the Custom Fields section.

  3. Click Add Custom Field to open the Add Custom Field modal.

  4. Set the Field name (the Key), and the Value you want to assign for that field.

  5. Click Add 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 for Existing Entities

The expandable content below includes the API reference for the /entityCustomFields endpoint, the endpoint used to create new Entity Custom Fields overall.

Note

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

Note that this endpoint can only be used to create new entity custom fields for existing Merchants because an existing Entity ID (such as t1_ent_123abc4d567890efg1h2i34) is a mandatory request body parameter when sending a POST /entityCustomFields request independently. Visit the API Documentation for a complete /entityCustomFields endpoint reference.

Request Example: 

POST /entityCustomFields HTTP/1.1
Content-Type: application/json
Accept: application/json
APIKEY:{{apiKey or txnSessionKey}}
Host: api-test.payrix.com
{
  "entity": "t1_ent_123abc4d567890efg1h2i34",
  "key": "{New_Custom_FieldKey_Name}",
  "value": "{Your_Custom_Value_or_ID}"
}

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
}

Note

The steps below don’t explicitly require an Entity ID because the Entity ID is generated in the backend during any entity setup. The Entity ID is a mandatory request body parameter when sending a POST /entityCustomFields request independently.

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 Partner Boarding, you can optionally add the following JSON object array to the signup form at the entity level like so:

{
  "type": 2,
  "name": "Entity Company",
  ...
  "entityCustomFields": [
      {
          "key": "{yourCustomKey}",
          "value": "{This is your custom ID or field value.}"
      }
  ],
  ...
}

To send more than one custom field, you can add more JSON objects to the entityCustomFields array, using unique key names for each. For example:

{
  "key": "isVIP", 
  "value": "1"
},
{
  "key": "crmID", 
  "value": "hkmym58s6gkuokldjlafb9w81j65419"
},

JSON Request - Merchant Signup Form with Entity Custom Fields:

{
    "type": 2,
    "name": "Entity Company",
    "address1": "1234 River Lane",
    "address2": null,
    "city": "Frisco",
    "state": "TX",
    "zip": "75034",
    "country": "USA",
    "phone": "8556729749",
    "fax": null,
    "email": "[email protected]",
    "ein": "123456789",
    "website": "http://examplemail.com",
    "tcVersion": "1.0",
    "currency": "USD",
    "accounts": [
        {
            "primary": "1",
            "currency": "USD",
            "account": {
                "method": "8",
                "number": "3829803325",
                "routing": "021000021"
            }
        }
    ],
    "entityCustomFields": [
        {
          "entity": "t1_ent_123abc4d567890efg1h2i34",
          "key": "isVIP", 
          "value": "1"
        },
        {
          "entity": "t1_ent_123abc4d567890efg1h2i34",
          "key": "crmID",
          "value": "hkmym58s6gkuokldjlafb9w81j65419"
        },
    ],
    "merchant": {
        "dba": null,
        "new": "1",
        "mcc": "1799",
        "status": "1",
        "members": [
            {
                "title": "CEO",
                "first": "FirstName",
                "middle": null,
                "last": "LastName",
                "ssn": null,
                "dob": "19910131",
                "dl": "123456789",
                "dlstate": "NY",
                "ownership": 10000,
                "email": "[email protected]",
                "fax": null,
                "phone": "5903324578",
                "primary": "1",
                "address1": "123 Main St",
                "address2": null,
                "city": "Rico",
                "state": "CO",
                "zip": "12345",
                "country": "USA"
            }
        ]
    }
}

Prepopulated Signup Form: HTTP Query String

&entityCustomFields[0][key]={New_Custom_FieldKey_Name}&entityCustomFields[0][value]={Your_Custom_Value_or_ID}

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.

To send more than one custom field, you can duplicate the "entityCustomFields": [] query array and change the key and value for each new duplicate. For example:

&entityCustomFields[0][key]=isVIP&entityCustomFields[0][value]=1&entityCustomFields[0][key]=crmID&entityCustomFields[0][value]=hkmym58s6gkuokldjlafb9w81j65419

HTTP Query - Pre-Populated Merchant Signup Form with Entity Custom Field:

public=0&website=https://example-site.com&globalBusinessId=123456789&globalBusinessType=tin&customerPhone=5555555555&irsFilingName=Bob's Bicycles LLC&type=2&haveEmployees=0&address1=123 Main St.&address2=Suite 123&city=New York&state=NY&zip=10001&country=USA&custom=New York-based online custom bike store.&termsAgree=true&tcAttestation=true&industry=Custom Bicycle Sales&payoutSecondaryDescriptor=Example Bikes&name=Bob’s Bikes&[email protected]&phone=5555555555&displayName=Example Bikes&tcVersion=PAYRIXSUBMERCHANT123&tcDate=202401201200&tcIp=0.0.0.0&tcAcceptDate=202401201200&tcAcceptIp=0.0.0.0&accounts[0][account][method]=8&accounts[0][account][routing]=012345678&accounts[0][account][number]=0123456789012345&accounts[0][account][confirmNumber]=0123456789012345&accounts[0][primary]=1&accounts[0][type]=all&accounts[0][name]=Example Checking&accounts[0][description]=Business Account for Example Bike Merchant.&entityCustomFields[0][key]=isVIP&entityCustomFields[0][value]=1&entityCustomFields[0][key]=crmID&entityCustomFields[0][value]=hkmym58s6gkuokldjlafb9w81j65419&merchant[dba]=Bob’s Bike Store&merchant[new]=0&merchant[established]=20160120&merchant[annualCCSales]=22000000&merchant[avgTicket]=150000&merchant[amex]=123456789012345&merchant[discover]=123456789012345&merchant[mcc]=5940&merchant[status]=1&merchant[boarded]=1&merchant[inactive]=0&merchant[frozen]=0&merchant[environment]=e-commerce&merchant[visaMvv]=123456&merchant[chargebackNotificationEmail][email protected]&merchant[statusReason]=&merchant[totalApprovedSales]=25000030&merchant[autoBoarded]=1&merchant[saqType]=SAQ-B&merchant[saqDate]=20160120&merchant[qsa]=Example+QSA&merchant[letterStatus]=1&merchant[letterDate]=20160120&merchant[tcAttestation]=1&merchant[visaDisclosure]=1&merchant[disclosureIP]=0.0.0.0&merchant[disclosureDate]=20160120&merchant[accountClosureReasonCode]=&merchant[accountClosureReasonDate]=&merchant[annualCCSaleVolume]=50000&merchant[annualACHSaleVolume]=2000&merchant[riskLevel]=low&merchant[creditRatio]=2&merchant[creditTimeliness]=1&merchant[chargebackRatio]=0&merchant[ndxDays]=3&merchant[ndxPercentage]=100&merchant[advancedBilling]=0&merchant[locationType]=78&merchant[percentKeyed]=0&merchant[totalVolume]=5000000&merchant[percentEcomm]=100&merchant[seasonal]=0&merchant[amexVolume]=15000&merchant[incrementalAuthSupported]=0&merchant[tmxSessionId]=12a345bc-67d8-9012-3e45-6f7g8901a234&merchant[percentBusiness]=15&merchant[applePayActive]=1&merchant[applePayStatus]=&merchant[googlePayActive]=1&merchant[passTokenEnabled]=1&merchant[naics]=44&merchant[naicsDescription]=Retail Trade&merchant[expressBatchCloseMethod]=TimeInitiated&merchant[expressBatchCloseTime]=1830&merchant[members][0][first]=Robert&merchant[members][0][middle]=Karl&merchant[members][0][last]=Wheelwright&merchant[members][0][email][email protected]&merchant[members][0][phone]=5555555555&merchant[members][0][ssn]=123456789&merchant[members][0][dob]=01011985&merchant[members][0][title]=CEO&merchant[members][0][address1]=123 Main St.&merchant[members][0][address2]=Suite 456&merchant[members][0][city]=New York&merchant[members][0][state]=NY&merchant[members][0][zip]=10001&merchant[members][0][primary]=1&merchant[members][0][country]=USA&merchant[members][0][significantResponsibility]=1&merchant[members][0][ownership]=10000

Applying Entity Custom Fields with Risk Policies

By using 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.

Below is a high-level overview on how to apply your new Entity Custom Field as a rule condition for a Policy or Decision. For more detailed setup steps and all information available, visit Using the Risk Management Page.

Set Up Entity Custom Fields for Risk Policies using the Portal

To simplify the setup step, only the high-level action items are included here. For more details about every parameter and the functionality of Risk Policies, visit Understanding Policies - Risk.

  1. Click Policies (under Risk) on the Portal navigation sidebar.

  2. Click Add Policy to create a new policy.

  3. Define the Name, Stage, Target, and Status components.

  4. Select the new Policy from the Table to Add Decisions.

  5. Select the primary Decision from the list available, then click Next.

  6. For Select a Sub-Decision, select ENTITY_CUSTOM from the dropdown menu, then enter your Entity Custom Field name into the lightbox. Set your Value accordingly.

  7. Set your Operator & Action, then click Next.

  8. Add any Rules, Dependencies and Failover Dependencies, then click Create to complete the process.

Result: Your Risk Policy is now configured to use your Entity Custom Field as an additional criteria to trigger the Risk.

Related articles