Custom Fields

Attach arbitrary key/value data to transactions. Create, update, delete, and list custom field definitions, or pass them through on a Sale.

Custom fields let you define extra data that gets stored with transactions, grouped by a name of your choosing. The flow is: create the field definitions, then reference them in transaction requests via the custom_fields object.

Create a custom field

POST /api/customfield

Field	Type	Required	Description
`name`	string	required	Display name. Regex `[0-9a-z -]{0-100}`.
`type`	string	optional	Field type (e.g. `text`, `radio`, multi-select). Regex `[0-9a-z]{0-50}`.
`group_name`	string	optional	Label used to reference a group of custom fields together. Regex `[0-9a-z]{0-50}`.
`required`	boolean	optional	Whether this field must be present on every transaction. Defaults to `false`.
`validation_type`	string	optional	One of `open`, `alpha`, `numeric`, `alphanumeric`, `sentence`.
`values`	array	optional	Array of `{name, value}` objects — used when the field has a fixed set of options.

List all custom fields

GET /api/customfields

{
  "status": "success",
  "msg": "success",
  "total_count": 1,
  "data": [
    {
      "id": "d0cdss7svrv2303ovkfg",
      "name": "TESTCUSTOMFIELD",
      "group_name": "default",
      "type": "radio",
      "required": false,
      "validation_type": "open",
      "values": [
        { "name": "safely", "value": "safely" }
      ],
      "default": "",
      "created_at": "2025-05-05T15:51:13Z",
      "updated_at": "2025-05-05T15:51:13Z",
      "deleted_at": "0001-01-01T00:00:00Z"
    }
  ]
}

List custom fields for a merchant

GET /api/customfields/{merchant_id}

Same shape as above, scoped to a single merchant.

Get a single custom field

GET /api/customfield/{custom_field_id}

Update a custom field

POST /api/customfield/{custom_field_id}

{
  "name": "TESTCUSTOMFIELD",
  "type": "text",
  "required": false,
  "group_name": "SimplePayments",
  "validation_type": "open",
  "values": null
}

Delete a custom field

DELETE /api/customfield/{custom_field_id}

{
  "status": "success",
  "msg": "success"
}

Passing custom fields on a transaction

Include a custom_fields object in the transaction body. Keys are the custom_field_id values; each value is an array of strings.

Non-default groups need group_name

If the field you are referencing belongs to a group other than default, you must also include group_name at the top level of the transaction request.

{
  "type": "sale",
  "amount": 20000,
  "group_name": "non default group name here",
  "custom_fields": {
    "d0cdss7svrv2303ovkfg": ["safely"]
  }
}