Custom fields

Custom fields let you attach merchant-defined fields to standard Payments AI resources. A custom field is defined once per Organization and applied to a chosen resource type from this enum: customers, payment-instruments, plans, products, subscriptions, transactions, websites.

Each custom field has a typeSchema that defines the data type and validation rules (string, number, boolean, datetime, monetary, etc.). Once defined, the field becomes available on every instance of its resource.

Base configuration

Environments

All requests should be directed to the following base URLs depending on the environment:

Environment	Base URL
Production	https://api.payments.ai/v1/public-api
Staging	https://staging-api.payments.ai/v1/public-api

Authentication & Authorization

• Authentication: Requires a valid API Key passed in the Authorization header.
• Role Required: The API Key must belong to a user with the EDITOR role (or higher) in the target organization.

---

Endpoints

1. Create or Upsert Custom Field

Creates a new custom field definition or updates an existing one if it already matches the name and resource.

• Method: POST
• Route: /organizations/{organizationId}/custom-fields

Request Parameters

Path Parameters:

Parameter	Type	Required	Description
organizationId	string	Yes	The unique identifier (UUID) of the organization.

Body Parameters (JSON):

Parameter	Type	Required	Constraints	Description
name	string	Yes	Max 255 chars	The internal identifier name for the field.
resource	string	Yes	Enum	The resource to attach this field to. Allowed values: customers, payment-instruments, plans, products, subscriptions, transactions, websites.
description	string	Yes	Max 255 chars	A human-readable description of the field's purpose.
typeSchema	object	Yes	Valid Schema Object	Configuration defining the data type (string, number, boolean, etc.) and validation rules.

Type Schema Configuration

The typeSchema object requires a type property and an optional additionalSchema object. Supported types are: monetary, string, number, integer, datetime, date, boolean, array.

Example typeSchema structures:

• String:

  {
    "type": "string",
    "additionalSchema": {
      "required": true,
      "maxLength": 100,
      "allowedValues": ["Value A", "Value B"]
    }
  }

• Boolean:

  {
    "type": "boolean",
    "additionalSchema": {
      "default": false
    }
  }

• Monetary:

  {
    "type": "monetary",
    "additionalSchema": {
      "default": { "currency": "USD", "amount": 0 }
    }
  }

Example Request

curl --location --request POST 'https://staging-api.payments.ai/v1/public-api/organizations/${ORGANIZATION_ID}/custom-fields' \
--header 'Content-Type: application/json' \
--header 'Authorization: ApiKey ${API_KEY}' \
--data '{
"name": "hideCustomerAddressOnInvoice",
"resource": "customers",
"description": "Hide customer address on invoice",
"typeSchema": {
"type": "boolean",
"additionalSchema": {
"required": false,
"default": false
        }
    }
}'

Example Response (201 Created)

{
  "type": "object",
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "organizationId": "6f326525-1586-479b-8176-55ba802caea4",
    "name": "hideCustomerAddressOnInvoice",
    "resource": "customers",
    "description": "Hide customer address on invoice",
    "typeSchema": {
        "type": "boolean",
        "additionalSchema": {
            "required": false,
            "default": false
        }
    },
    "createdAt": "2023-11-01T12:00:00Z",
    "updatedAt": "2023-11-01T12:00:00Z"
  }
}

---

2. Retrieve Custom Field

Fetches the configuration details of a specific custom field definition based on its name and associated resource.

• Method: GET
• Route: /organizations/{organizationId}/custom-fields

Request Parameters

Path Parameters:

Parameter	Type	Required	Description
organizationId	string	Yes	The unique identifier (UUID) of the organization.

Query Parameters:

Parameter	Type	Required	Constraints	Description
name	string	Yes	Max 255 chars	The name of the custom field (e.g., customerInvoiceNotes).
resource	string	Yes	Enum	The resource type the field belongs to.

Allowed values: customers, payment-instruments, plans, products, subscriptions, transactions, websites. |

Example Request

curl --location --request GET 'https://staging-api.payments.ai/v1/public-api/organizations/${ORGANIZATION_ID}/custom-fields?name=customerInvoiceNotes&resource=customers' \
--header 'Authorization: ApiKey ${API_KEY}'

Example Response (200 OK)

{
  "type": "object",
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "organizationId": "6f326525-1586-479b-8176-55ba802caea4",
    "name": "customerInvoiceNotes",
    "resource": "customers",
    "description": "Customer invoice notes",
    "typeSchema": {
      "type": "string",
      "additionalSchema": {
        "required": false,
        "default": ""
      }
    },
    "createdAt": "2023-10-27T10:00:00Z",
    "updatedAt": "2023-10-27T10:00:00Z"
  }
}

---

Error Handling

The API returns standard HTTP status codes to indicate the success or failure of requests.

Status Code	Description
200 OK	Resource retrieved successfully.
201 Created	Custom field created or updated successfully.
400 Bad Request	Validation failed (e.g., invalid resource type or schema mismatch).
401 Unauthorized	Missing or invalid API Key.
403 Forbidden	User does not have permission to modify custom fields.
404 Not Found	Custom field not found (for GET requests).
500 Server Error	Internal system error.

Example Error Response (400 Bad Request)

{
  "errorCode": "string",
  "statusCode": 400,
  "message": "Bad request",
  "details": "string"
}

See Errors for the standard error response shape used across the Public API.