Custom Fields

Custom fields let your merchant account store KYC/KYB data that the standard entity model does not include, such as business activity, source of funds, estimated volumes, or local identifiers. Localpayment defines a schema for your merchant, and you send the values in attributes when you create or update an entity.

Prerequisites

• A custom-fields schema agreed with your account manager and published by Localpayment.
• A Stage access token. See Get Access Token.

How it works

%%{init: {'theme': 'base', 'themeVariables': {'background': '#ffffff', 'primaryColor': '#31467c', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#0c1a29', 'secondaryColor': '#31467c', 'tertiaryColor': '#ffffff', 'lineColor': '#0c1a29', 'textColor': '#0c1a29', 'edgeLabelBackground': '#ffffff', 'fontFamily': 'Manrope'}, 'fontFamily': 'Manrope', 'htmlLabels': false, 'flowchart': {'htmlLabels': false, 'wrappingWidth': 400, 'padding': 20}}}%%
flowchart TD
    A["Your account manager<br/>Agrees the fields: keys, types, constraints"]:::lp --> B["Localpayment<br/>Publishes schema version N"]:::lp
    B --> C["Your backend<br/>GET /api/entity/v1/custom-fields/schema"]
    C --> D["Entities API<br/>200: JSON Schema, or 404 if none is published"]:::lp
    D --> E["Your backend<br/>POST /api/entity/v1/entities with attributes"]
    E --> F["Entities API<br/>201: customFieldSchemaVersion N"]:::lp
    E --> G["Entities API<br/>400 CUSTOM_FIELDS_INVALID<br/>when a value breaks the schema"]:::lp
    classDef default fill:#31467c,stroke:#0c1a29,stroke-width:1px,color:#ffffff,font-family:Manrope
    classDef lp fill:#0c1a29,stroke:#0c1a29,color:#ffffff
    classDef terminal fill:#0c1a29,stroke:#0c1a29,color:#ffffff
    classDef lbl fill:#0c1a29,stroke:#0c1a29,color:#ffffff,font-size:13px

• No schema published: attributes is accepted as sent, and Get Custom Fields Schema returns 404 CUSTOM_FIELD_SCHEMA_NOT_FOUND.
• Schema published: validation is strict. Unknown keys, missing required keys, wrong types, lengths, patterns, and ranges are rejected with 400 CUSTOM_FIELDS_INVALID. Each entity records the customFieldSchemaVersion it was validated with.
• One schema per merchant applies to both INDIVIDUAL and COMPANY. Fields that only make sense for companies are defined as optional.

Field types

Keys are camelCase and start with a lowercase letter (^[a-z][a-zA-Z0-9_]{0,63}$). attributes can weigh up to 64 KB (413 PAYLOAD_TOO_LARGE).

Read the schema

curl https://api.stage.localpayment.com/api/entity/v1/custom-fields/schema \
  -H "Authorization: Bearer $LOCALPAYMENT_ACCESS_TOKEN"

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "reasonForAccountOpening": {
      "type": "string",
      "title": "Reason for account opening",
      "enum": [
        "receive_payments_for_goods_and_services",
        "payroll",
        "other"
      ]
    },
    "sourceOfFundsAndIncome": {
      "type": "string"
    },
    "numberOfEmployees": {
      "type": "string",
      "enum": [
        "1-10",
        "11-50",
        "51-200",
        "200+"
      ]
    },
    "estimatedAnnualRevenueUsd": {
      "type": "string"
    },
    "estimatedMonthlyVolumeUsd": {
      "type": "string"
    },
    "businessActivityDescription": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000
    },
    "countryTaxResidence": {
      "type": "string",
      "minLength": 3,
      "maxLength": 3
    },
    "socialMedia": {
      "type": "string"
    },
    "emailPixKey": {
      "type": "string"
    },
    "percentageOfOwnership": {
      "type": "string"
    },
    "hasControl": {
      "type": "string"
    },
    "documentCountry": {
      "type": "string"
    },
    "countryOfTaxId": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

The default response is a JSON Schema (2020-12). Add ?format=definition to get the native field list instead.

Send the values

Values travel in attributes in Create an Entity and Update an Entity:

{
  "attributes": {
    "reasonForAccountOpening": "receive_payments_for_goods_and_services",
    "sourceOfFundsAndIncome": "sales_of_goods_and_services",
    "numberOfEmployees": "11-50",
    "estimatedAnnualRevenueUsd": "1m_to_10m",
    "estimatedMonthlyVolumeUsd": "50000",
    "businessActivityDescription": "Online retail of home goods. Receives payments from end customers in Brazil via PIX.",
    "countryTaxResidence": "BRA",
    "socialMedia": "https://www.linkedin.com/company/example",
    "emailPixKey": "[email protected]"
  }
}

A value outside the schema returns 400 CUSTOM_FIELDS_INVALID, with one entry per offending field in details:

{
  "type": "about:blank",
  "title": "Validation error",
  "status": 400,
  "detail": "Validation error",
  "instance": "/api/entity/v1/entities",
  "code": "CUSTOM_FIELDS_INVALID",
  "correlationId": "fff39bf8-1cb2-40c7-ac99-37478d819943",
  "details": [
    {
      "field": "numberOfEmployees",
      "issue": "NOT_IN_OPTIONS"
    },
    {
      "field": "legacyNote",
      "issue": "UNKNOWN_FIELD"
    }
  ]
}

Validate attributes against the schema on your side before calling the API, and map each details entry back to your form so the user can fix the value.

Change the schema

Localpayment publishes schema changes as a new version. Existing entities keep their customFieldSchemaVersion, and new writes are validated against the latest published version. Ask your account manager to add, relax, or remove fields.

Next steps