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.

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 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:

Click here for Portal Setup Steps - Entity Custom Fields

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.

Click here for the /entityCustomFields Endpoint Reference

Entity Custom Fields Headers

CODE

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

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

JSON

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

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

JSON

{
  "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
`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`

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

JSON

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

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

Example:

CODE

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

JSON Request - Merchant Signup Form with Entity Custom Fields

CODE

{
    "type": 2,
    "name": "Entity Company",
    "address1": "1234 River Lane",
    "address2": null,
    "city": "Frisco",
    "state": "TX",
    "zip": "75034",
    "country": "USA",
    "phone": "8556729749",
    "fax": null,
    "email": "test@examplemail.com",
    "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": "example@hotmail.com",
                "fax": null,
                "phone": "5903324578",
                "primary": "1",
                "address1": "123 Main St",
                "address2": null,
                "city": "Rico",
                "state": "CO",
                "zip": "12345",
                "country": "USA"
            }
        ]
    }
}

Pre-Populated Signup Form - HTTP Query String

CODE

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

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

Example:

CODE

&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

CODE

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=ex1@examplemail.com&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]=excb@examplemail.com&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]=ex2@examplemail.com&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 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.

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.

Setting up Entity Custom Fields for Risk Policies using the Portal

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

Step 1: Click Policies (under the Risk tab) on the Portal navigation sidebar.
Step 2: Click the Add Policy button to create a new policy.
Step 3: Define the Name, Stage, Target, and Status components.
Step 4: Select the new Policy from the Table to Add Decisions.
Step 5: Select the primary Decision from the list available, then click Next.
Step 5: For “Select a Sub-Decision”, select ENTITY_CUSTOM from the dropdown, then enter your Entity Custom Field name into the lightbox. Set your Value accordingly.
Step 6: Set your Operator & Action then click Next.
Step 7: Add any Rules, Dependencies and Failover Dependencies, then click the Create button to complete the process.

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