Payer-ID-Maintenance-Request

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/citi/main/json-schema/citi-payer-id-maintenance-request-schema.json",
  "title": "Payer-ID-Maintenance-Request",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/citi-payeridmaintenance-api-openapi.yml#/components/schemas/Payer-ID-Maintenance-Request",
  "required": [
    "country_code"
  ],
  "type": "object",
  "properties": {
    "country_code": {
      "$ref": "#/$defs/Country-Code"
    },
    "party_type_details": {
      "$ref": "#/$defs/Party-Type-Details"
    },
    "assignee_id": {
      "title": "assignee_id",
      "type": "string",
      "description": "The assignee ID expected from the client for upfront sanction screening and activation of Payer ID number. For Action 'Activation' and 'Deactivation', this field is optional. For Action 'Update', either of payerid-number or assignee_id is mandatory.",
      "minLength": 1,
      "maxLength": 35
    },
    "create_assignee_id": {
      "title": "create_assignee_id",
      "type": "string",
      "enum": [
        "Y",
        "N"
      ],
      "description": "Feature to create assignee ID is given to clients. Citi is required create the assignee ID and send the assignee ID in response push notifications. Allowed values are:<br> Y - YES<br>N - NO"
    },
    "merchant": {
      "$ref": "#/$defs/Merchant-Details"
    },
    "beneficiary": {
      "title": "beneficiaries",
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/Beneficiary-Details"
      }
    }
  },
  "$defs": {
    "Beneficiary-Details": {
      "title": "Beneficiary-Details",
      "allOf": [
        {
          "$ref": "#/$defs/Payer-ID-Address-Details"
        },
        {
          "type": "object",
          "title": "allOf",
          "properties": {
            "beneficiary_id": {
              "title": "beneficiary_id",
              "minLength": 1,
              "maxLength": 35,
              "type": "string",
              "description": "Unique ID for a beneficiary."
            },
            "last_name": {
              "title": "last_name",
              "minLength": 1,
              "maxLength": 140,
              "type": "string",
              "description": "The beneficiary owner's last name."
            },
            "middle_name": {
              "title": "middle_name",
              "minLength": 1,
              "maxLength": 140,
              "type": "string",
              "description": "The beneficiary owner's middle name."
            },
            "first_name": {
              "title": "first_name",
              "minLength": 1,
              "maxLength": 140,
              "type": "string",
              "description": "The beneficiary owner's first name."
            },
            "dob": {
              "title": "dob",
              "type": "string",
              "format": "date",
              "description": "The beneficiary owner's date of birth. As per ISO format, this parameter is in a fixed 10-digit format (YYYY-MM-DD)."
            },
            "tax_identifier": {
              "title": "tax_identifier",
              "minLength": 1,
              "maxLength": 35,
              "type": "string",
              "description": "The beneficiary owner's tax identifier."
            },
            "economic_id": {
              "$ref": "#/$defs/Beneficiary-Economic-Id"
            }
          }
        }
      ]
    },
    "Beneficiary-Economic-Id": {
      "title": "Beneficiary-Economic-Id",
      "minLength": 1,
      "maxLength": 50,
      "type": "string",
      "description": "Beneficiary economic id based on the beneficiary's country."
    },
    "Country-Code": {
      "title": "Country-Code",
      "type": "string",
      "pattern": "^[A-Z]{2}$",
      "description": "The ISO country code specifying which country where the account is held with. For example, if we receive a request for Germany, then the county code is 'DE', for France, the country code is 'FR'. The list of allowed country codes are: <br>'DE' - Germany<br> 'FR' - France<br> 'GB' - Great Britain<br>'IE' - Ireland<br>'NL' - Netherlands<br>'US' - United States<br>'CA' - Canada<br> 'HK' - Hong Kong<br> 'SG' - Singapore<br>'AU' - Australia<br>'NZ' - New Zealand<br>'LU' - Luxembourg<br> 'VN' - Vietnam"
    },
    "Merchant-Details": {
      "title": "Merchant-Details",
      "allOf": [
        {
          "$ref": "#/$defs/Payer-ID-Address-Details"
        },
        {
          "type": "object",
          "title": "allOf",
          "properties": {
            "name_1": {
              "title": "name_1",
              "minLength": 1,
              "maxLength": 140,
              "type": "string",
              "description": "The last name or company name. For 'sole trader', include the last name. For 'company', include the company name."
            },
            "name_2": {
              "title": "name_2",
              "minLength": 1,
              "maxLength": 140,
              "type": "string",
              "description": "For 'sole trader', include the first name. For 'company', leave blank or include the second line of the company name."
            },
            "date": {
              "title": "date",
              "type": "string",
              "format": "date",
              "description": "The sole trader's date of birth or the identification of the company's date of incorporation. This parameter follows the ISO format and is a fixed 10-digit format (YYYY-MM-DD)."
            },
            "tax_identifier": {
              "title": "tax_identifier",
              "minLength": 1,
              "maxLength": 35,
              "type": "string",
              "description": "The merchant's tax identifier based on country."
            },
            "economic_id": {
              "$ref": "#/$defs/Merchant-Economic-Id"
            },
            "website": {
              "title": "website",
              "minLength": 1,
              "maxLength": 255,
              "type": "string",
              "description": "The merchant's profile, website, or storefront."
            }
          }
        }
      ]
    },
    "Merchant-Economic-Id": {
      "title": "Merchant-Economic-Id",
      "minLength": 1,
      "maxLength": 50,
      "type": "string",
      "description": "Merchant economic id based on the merchant's country."
    },
    "Party-Type-Details": {
      "title": "Party-Type-Details",
      "type": "string",
      "enum": [
        "C",
        "S"
      ],
      "description": "Account party type details. Allowed account part type values are:<br> <br>`S` - sole trader, which is an enterprise owned or run by a single person. <br>`C` - a company that is owned by an organization or business entity"
    },
    "Payer-ID-Address-Details": {
      "type": "object",
      "title": "Payer-ID-Address-Details",
      "properties": {
        "address": {
          "minLength": 1,
          "maxLength": 140,
          "type": "string",
          "title": "address",
          "description": "The merchant or beneficiary address."
        },
        "zipcode": {
          "minLength": 1,
          "maxLength": 16,
          "type": "string",
          "title": "zipcode",
          "description": "The merchant or beneficiary zip code."
        },
        "city": {
          "minLength": 1,
          "maxLength": 35,
          "type": "string",
          "title": "city",
          "description": "The merchant or beneficiary city."
        },
        "state": {
          "minLength": 1,
          "maxLength": 35,
          "type": "string",
          "title": "state",
          "description": "The merchant or beneficiary state."
        },
        "country_code": {
          "title": "Country-Code",
          "type": "string",
          "pattern": "^[A-Z]{2}$",
          "description": "The ISO country code specifying which country where the account is held with. For example, if we receive a request for Germany, then the county code is 'DE', for France, the country code is 'FR'."
        }
      }
    }
  }
}