Custom fields can be used to add your own categories and attributes to Numeral resources.

There are two types of custom fields:

Select from a list of values
Text

Custom fields can be applied to:

Payment orders
Transactions
Counterparty accounts

Settings

Create a custom field

Select custom field

Use the request below to create a select custom field named Customer country that can be applied to payment orders and transactions and can have France and United Kingdom as values. 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": "customer_country",
	"name": "Customer country",
	"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": "customer_country",
	"name": "Customer country",
	"object_types": ["payment_order","transaction"],
	"type": "select",
	"values": [
		{ "key": "fr", "name": "France" },
		{ "key": "uk", "name": "United Kingdom" },
	],
	"created_at": "2024-03-01T12:00:00Z"

Text custom field

Use the request below to create a text custom field named Custom reference that can be applied to payment orders and transactions.

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

After a custom field is created, you can:

Change its name
For custom fields of type select:
- Add new values
- Change value names, but not keys

To edit a custom field, you must include:

The name of the custom field, even if it has not changed
For select-type custom fields:
- Existing values with their keys and names, even if they have not changed
- New values values with their keys and names

Change the name of the custom field

Use the following request to rename a custom field.

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": "Country of customer",
	"values": [
		{ "key": "fr", "name": "France" },
		{ "key": "uk", "name": "United Kingdom" },
	]
}
'

{
	"id": "d55b714c-550c-4d88-acdc-5b576502b779",
	"object": "custom_field",
	"key": "customer_country",
	"name": "Country of customer",
	"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 custom field key has not changed.

Change a value name

To rename value United Kingdom in UK, 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 country",
	"values": [
		{ "key": "fr", "name": "France" },
		{ "key": "uk", "name": "UK" }
	]
}
'

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

Add a new value

To add a new value 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 country",
	"values": [
		{ "key": "fr", "name": "France" },
		{ "key": "uk", "name": "UK" },
		{ "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 created, 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"
  }
}