Custom fields can be used to add your own categories, attributes, and IDs to Numeral objects.

There are 2 types of custom fields:

Select, which can only take values from a list of values
Text, which can take any text as value

Custom fields can be applied to:

Payment orders
Transactions
Counterparty accounts

Settings

Create a new custom field

Custom field of type select

To create a custom field named “Country of Customer”, applicable to payment orders and transactions, and that can be either “France” or “United Kingdom”, use the request below. The API will return the custom field object with its ID and its creation timestamp.

curl --request POST \
     --url https://sandbox.numeral.io/v1/custom_fields \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-Key: Your_API_Key'
     --data '
{
	"key": "country_of_customer",
	"name": "Country of Customer",
	"type": "select", 
	"object_types": ["payment_order","transaction"],
	"values": [
		{ "key": "fr", "name": "France" },
		{ "key": "uk", "name": "United Kingdom" }
	]
}
'

{
	"id": "d55b714c-550c-4d88-acdc-5b576502b779",
	"object": "custom_field",
	"key": "country_of_customer",
	"name": "Country of Customer",
	"object_types": ["payment_order","transaction"],
	"type": "select",
	"values": [
		{ "key": "fr", "name": "France" },
		{ "key": "uk", "name": "United Kingdom" },
	],
	"created_at": "2024-03-01T12:00:00Z"

Custom field of type text

To create a “Custom reference” custom field of type text, you can use the following request, which does not include a list of values, as custom fields of type text are not based on a list of values.

curl --request POST \
     --url https://sandbox.numeral.io/v1/custom_fields \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-Key: Your_API_Key'
     --data '
{
	"key": "custom_reference",
	"name": "Custom reference",
	"type": "text", 
	"object_types": ["payment_order","transaction"],
}
'

{
	"id": "a94ae944-c8ad-4cbe-9a28-48f2e4fc6600",
	"object": "custom_field",
	"key": "custom_reference",
	"name": "Custom reference",
	"object_types": ["payment_order","transaction"],
	"type": "text",
	"created_at": "2024-03-01T12:00:00Z"
}

Edit a custom field

Once a custom field is created, you can either:

Change its name
For custom fields of type select:
- Change its values’ names
- Create new values

To edit a custom field, you must include in the payload:

The name of the custom filed, whether it has changed or not,
For custom fields of type select:
- Each existing values with their keys and names, whether the latter have changed or not,
- The new values you wish to create, with their keys and names.

Change the name of the custom field

To rename a custom field “Customer's country”, use the following query:

curl --request POST \
     --url https://sandbox.numeral.io/v1/custom_fields/d55b714c-550c-4d88-acdc-5b576502b779 \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-Key: Your_API_Key'
     --data '
{
	"name": "Customer's country",
	"values": [
		{ "key": "fr", "name": "France" },
		{ "key": "uk", "name": "United Kingdom" },
	]
}
'

{
	"id": "d55b714c-550c-4d88-acdc-5b576502b779",
	"object": "custom_field",
	"key": "country_of_customer",
	"name": "Customer's country",
	"object_types": ["payment_order","transaction"],
	"type": "select",
	"values": [
		{ "key": "fr", "name": "France" },
		{ "key": "uk", "name": "U-K" }
	],
	"created_at": "2024-03-01T12:00:00Z"
}

Please note that the key of the custom field has not changed. Once created, it is impossible to change the key of a custom field.

Change the name of a value

To rename the value “United Kingdom” in “U-K”, use the following query:

curl --request POST \
     --url https://sandbox.numeral.io/v1/custom_fields/d55b714c-550c-4d88-acdc-5b576502b779 \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-Key: Your_API_Key'
     --data '
{
	"name": "Customer's country",
	"values": [
		{ "key": "fr", "name": "France" },
		{ "key": "uk", "name": "U-K" }
	]
}
'

{
	"id": "d55b714c-550c-4d88-acdc-5b576502b779",
	"object": "custom_field",
	"key": "country_of_customer",
	"name": "Customer's country",
	"object_types": ["payment_order","transaction"],
	"type": "select",
	"values": [
		{ "key": "fr", "name": "France" },
		{ "key": "uk", "name": "U-K" }
	],
	"created_at": "2024-03-01T12:00:00Z"
}

Please note that the key of the value has not changed. Once created, it is impossible to change the key of a value.

Add a new value

To add a new value, Germany for example, use the following query:

curl --request POST \
     --url https://sandbox.numeral.io/v1/custom_fields/d55b714c-550c-4d88-acdc-5b576502b779 \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-Key: Your_API_Key'
     --data '
{
	"name": "Customer's country",
	"values": [
		{ "key": "fr", "name": "France" },
		{ "key": "uk", "name": "U-K" },
		{ "key": "ge", "name": "Germany" }
	]
}
'

{
	"id": "d55b714c-550c-4d88-acdc-5b576502b779",
	"object": "custom_field",
	"key": "country_of_customer",
	"name": "Customer's country",
	"object_types": ["payment_order","transaction"],
	"type": "select",
	"values": [
		{ "key": "fr", "name": "France" },
		{ "key": "uk", "name": "U-K" },
		{ "key": "ge", "name": "Germany" }
	],
	"created_at": "2024-03-01T12:00:00Z"
}

Use

Once your custom fields are properly created and configured, it is time to use them on your objects! Custom fields can be applied to payment orders, transactions and counterparty accounts.

We will take the example of a payment order, but all the following descriptions also apply to transactions and counterparty accounts.

Set a custom field when creating an object

When creating a new payment order, you can attach custom fields to it. To do so, you should pass an object listing:

Custom fields’ keys along with:
The key of the value for custom fields of type select,
The text for custom fields of type text.

To create a payment order with 2 custom fields, use the following query:

curl --request POST \
     --url https://sandbox.numeral.io/v1/payment_orders \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  // All required attributes for payment_order creation
  
  // List of custom fields to be applied to the new payment_order
  "custom_fields": {
    "country_of_customer": "fr", // Custom field of type select, with the key of the value
    "custom_reference": "1234-ABCD" // Custom field of type text, with a free text
  }
}
'

{
  // All attributes for payment_order
  
  // List of custom fields applied
  "custom_fields": {
    "country_of_customer": "fr", // Custom field of type select, with the key of the value
    "custom_reference": "1234-ABCD" // Custom field of type text, with a free text
  }
}

Please note that the API does check the validity of the custom field and/or of the values.

Add a custom field to an object

To add a custom field to an object, use the following query:

curl --request POST \
     --url https://sandbox.numeral.io/v1/payment_orders/276e8083-b005-487c-afc6-064a466195c4 \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "custom_fields": {
    "business_unit": "sales"
  }
}
'

{
  // All attributes for payment_order
  
  // List of custom fields
  "custom_fields": {
    "business_unit": "sales",
    "country_of_customer": "fr",
    "custom_reference": "1234-ABCD"
  }
}

Edit a custom field for an existing object

To update the value of a custom field, for example to change the business unit, use the following query:

curl --request POST \
     --url https://sandbox.numeral.io/v1/payment_orders/276e8083-b005-487c-afc6-064a466195c4 \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "custom_fields": {
    "business_unit": "marketing"
  }
}
'

{
  // All attributes for payment_order
  
  // List of custom fields
  "custom_fields": {
    "business_unit": "marketing",
    "country_of_customer": "fr",
    "custom_reference": "1234-ABCD"
  }
}

Remove a custom field from an object

To remove a custom field from an object, use the following query:

curl --request POST \
     --url https://sandbox.numeral.io/v1/payment_orders/276e8083-b005-487c-afc6-064a466195c4 \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "custom_fields": {
    "business_unit": null
  }
}
'

{
  // All attributes for payment_order
  
  // List of custom fields
  "custom_fields": {
    "country_of_customer": "fr",
    "custom_reference": "1234-ABCD"
  }
}