BeneficiaryValidationRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/citi/main/json-schema/citi-beneficiary-validation-request-schema.json",
  "title": "BeneficiaryValidationRequest",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/citi-beneficiary-validation-api-openapi.yml#/components/schemas/Beneficiary-Validation-Request",
  "type": "object",
  "required": [
    "debtor",
    "method"
  ],
  "properties": {
    "end_to_end_id": {
      "type": "string",
      "description": "Client provided reference number. \n - For India IMPS and UPI, this field is mandatory and max length is 16 \n - For US EWS,this field is not applicable \n - For UK,this field is not applicable \n - For IN PAN,this field is not applicable \n - For Pay2China, this field is not required",
      "minLength": 1,
      "maxLength": 35,
      "title": "end_to_end_id"
    },
    "uetr": {
      "type": "string",
      "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$",
      "description": "UUID v4 format unique end-to-end transaction reference",
      "title": "uetr"
    },
    "debtor": {
      "type": "object",
      "title": "debtor",
      "properties": {
        "account": {
          "type": "string",
          "description": "Bank account held with CITI \n - For India IMPS and UPI , this field is mandatory and max length is 34 \n - For US EWS, this field is mandatory and max length is 40 \n - For UK, this field is mandatory and max length is 40 \n - For IN PAN, this field is mandatory and max length is 40 \n - For Pay2China, this field is mandatory and max length is 40",
          "minLength": 1,
          "maxLength": 40,
          "title": "account"
        },
        "name": {
          "type": "string",
          "description": "Debtor Account Name.\n - For India IMPS and UPI ,this field is mandatory and max length is 99 \n - For US EWS,this field is optional and max length is 140 \n - For UK,this field is optional and max length is 140 \n - For IN PAN,this field is optional and max length is 140 \n - For Pay2China - this field is optional and max length is 140",
          "minLength": 1,
          "maxLength": 140,
          "title": "name"
        },
        "proxy_id": {
          "type": "string",
          "description": "Remitter Proxy ID.\n - For India,this field is mandatory for UPI only and max length is 255 \n - For US EWS,this field is not applicable \n - For UK,this field is not applicable \n - For IN PAN,this field is not applicable \n - For Pay2China, this field is not required",
          "minLength": 1,
          "maxLength": 255,
          "title": "proxy_id"
        },
        "ultimate_debtor": {
          "type": "object",
          "title": "ultimate_debtor",
          "properties": {
            "name": {
              "type": "string",
              "description": "Ultimate debtor name. \n - For IMPS India,this field is not applicable \n - For UPI India,this field is not applicable \n - For US EWS,this field is not applicable \n - For UK,this field is not applicable \n - For Pay2China, this field is optional and the max length is 140",
              "minLength": 1,
              "maxLength": 140,
              "title": "ultimate_debtor_name"
            },
            "account": {
              "type": "string",
              "description": "Beneficiary Owner Id/Legal Rep id. \n - For IMPS India,this field is not applicable \n - For UPI India,this field is not applicable \n - For US EWS,this field is not applicable \n - For UK,this field is not applicable \n - For IN PAN,this field is not applicable \n - For Pay2China, this field is mandatory and the max length is 35",
              "minLength": 1,
              "maxLength": 35,
              "title": "ultimate_debtor_account"
            }
          }
        }
      },
      "required": [
        "account"
      ]
    },
    "creditor": {
      "type": "object",
      "title": "creditor",
      "properties": {
        "id": {
          "type": "string",
          "description": "Creditor Id. \n - For IMPS India,this field is not applicable \n - For UPI India, this field is not applicable \n - For US EWS,this field is not applicable \n - For UK,this field is not applicable \n - For IN PAN,this field is not applicable. \n - For Pay2China, this field is merchant ID. It is mandatory and the max length is 32",
          "minLength": 1,
          "maxLength": 35,
          "title": "id"
        },
        "account": {
          "type": "string",
          "description": "Creditor Account Number. \n - For IMPS India,this field is mandatory and max length is 34 \n - For UPI India, this field is optional and length should be 34 \n - For US EWS,this field is conditional and max length is 17.Either creditor.account or creditor.proxy_id or creditor.wallet or creditor.IBAN should be passed by client \n - For UK,this field is conditional and max length is 17.Either creditor.account or creditor.proxy_id or creditor.wallet or creditor.IBAN should be passed by client \n - For IN PAN,this field is not applicable \n - For Pay2China, this field is optional and max length is 32",
          "minLength": 1,
          "maxLength": 40,
          "title": "account"
        },
        "name": {
          "type": "string",
          "description": "Creditor Account Name.\n - For India IMPS and UPI,this field is optional and max length is 99 \n - For US EWS,this field is mandatory and max length is 87. Please provide first middle(if any) last name in this sequence with spaces \n - For UK,this field is mandatory and max length is 87. Please provide first middle(if any) last name in this sequence with spaces \n - For IN PAN,this field is mandatory and max length is 85. Please provide first middle(if any) last name in this sequence with spaces \n - For Pay2China, this field is merchant name. It is a conditional field. It is mandatory for first time onboarding and max length is 128",
          "minLength": 1,
          "maxLength": 140,
          "title": "name"
        },
        "father_name": {
          "type": "string",
          "description": "Creditor' Father's Name.\n - For India IMPS and UPI,this field is not applicable \n - For US EWS,this field is not applicable \n - For UK,this field is not applicable \n - For IN PAN,this field is optional and max length is 75. Please provide first middle(if any) last name in this sequence with spaces \n - For Pay2China, this field is not required",
          "minLength": 1,
          "maxLength": 140,
          "title": "father_name"
        },
        "bank_id": {
          "type": "string",
          "description": "Receiving Financial Institution BIC.\n - For IMPS India,this field is mandatory and length should be 11 \n - For UPI India,this field is optional and length should be 11 \n - For US EWS,this field is mandatory and length should be 9 if routing/clearing code is populated \n - For UK,this field is mandatory and length should be 8 or 11 character if bic (including branch code) is sent \n - For IN PAN,this field is not applicable \n - For Pay2China, this field is optional and max length is 64",
          "minLength": 1,
          "maxLength": 35,
          "title": "bank_id"
        },
        "bank_name": {
          "type": "string",
          "description": "Receiving Financial Institution Name. \n - For IMPS India,this field is not applicable \n - For UPI India,this field is not applicable \n - For US EWS,this field is not applicable \n - For UK,this field is not applicable \n - For IN PAN,this field is not applicable \n - For Pay2China, this is an optional field and  max length is 128",
          "minLength": 1,
          "maxLength": 140,
          "title": "bank_name"
        },
        "proxy_id": {
          "type": "string",
          "description": "Creditor Proxy ID \n - For India,this field is mandatory for UPI only and max length is 255 (UPI ID or Mobile number can be passed).If mobile number is passed it should be greater than or equal to 6 and less than or equal to 16 \n - For US EWS,this field is conditional and max length is 17.Either creditor.account or creditor.proxy_id or creditor.wallet or creditor.IBAN should be passed by client \n - For UK,this field is conditional and max length is 17.Either creditor.account or creditor.proxy_id or creditor.wallet or creditor.IBAN should be passed by client\n - For IN PAN,this field is not applicable \n - For Pay2China, this field is not required",
          "minLength": 1,
          "maxLength": 255,
          "title": "proxy_id"
        },
        "proxy_type": {
          "type": "string",
          "description": "Creditor Proxy type \n - For India,this field is optional for UPI only if mobile number needs to be passed in creditor.proxy_id  \n - For US EWS,this field is not applicable \n - For UK,this field is not applicable \n - For IN PAN,this field is not applicable \n- MBNO - Mobile Number \n- SHID - Scheme identification number (eg. VPA ID) \n - For Pay2China, this field is not required ",
          "enum": [
            "MBNO",
            "SHID"
          ],
          "title": "proxy_type"
        },
        "wallet": {
          "type": "string",
          "description": "Creditor wallet details \n - For India IMPS,this field is not applicable \n - For India UPI,this field is not applicable \n - For US EWS,this field is conditional and max length is 17.Either creditor.account or creditor.proxy_id or creditor.wallet or creditor.IBAN should be passed by client \n - For UK,this field is conditional and max length is 17.Either creditor.account or creditor.proxy_id or creditor.wallet or creditor.IBAN should be passed by client \n - For IN PAN,this field is not applicable \n - For Pay2China, this field is not required",
          "minLength": 1,
          "maxLength": 40,
          "title": "wallet"
        },
        "IBAN": {
          "type": "string",
          "description": "Creditor IBAN number \n - For India IMPS,this field is not applicable \n - For India UPI,this field is not applicable \n - For US EWS,this field is conditional and max length is 17.Either creditor.account or creditor.proxy_id or creditor.wallet or creditor.IBAN should be passed by client \n - For UK,this field is conditional and max length is 34.Either creditor.account or creditor.proxy_id or creditor.wallet or creditor.IBAN should be passed by client \n - For IN PAN,this field is not applicable \n - For Pay2China, this field is not required",
          "minLength": 1,
          "maxLength": 40,
          "title": "IBAN"
        },
        "address_lines": {
          "type": "array",
          "description": "Creditor's address lines \n - For India IMPS,this field is not applicable \n - For India UPI,this field is not applicable \n - For US EWS, this field is optional and allowed 2 lines with each line max length of 40 \n - For UK, this field is optional and allowed 2 lines with each line max length of 40 \n - For IN PAN,this field is not applicable \n - For Pay2China, this field is not required",
          "items": {
            "$ref": "#/$defs/Address"
          },
          "title": "address_lines"
        },
        "street_name": {
          "maxLength": 70,
          "minLength": 1,
          "type": "string",
          "description": "Creditor's street_name \n - For India IMPS,this field is not applicable \n - For India UPI,this field is not applicable \n - For US EWS, this field is optional with max length 70 \n - For UK, this field is optional with max length 70 \n - For IN PAN,this field is not applicable \n - For Pay2China, this field is not required",
          "title": "street_name"
        },
        "building_number": {
          "maxLength": 16,
          "minLength": 1,
          "type": "string",
          "description": "Creditor's building_number \n - For India IMPS,this field is not applicable \n - For India UPI,this field is not applicable \n - For US EWS, this field is optional with max length 16 \n - For UK, this field is optional with max length 16 \n - For IN PAN,this field is not applicable \n - For Pay2China, this field is not required",
          "title": "building_number"
        },
        "postal_code": {
          "maxLength": 16,
          "minLength": 1,
          "type": "string",
          "description": "Creditor's postal_code \n - For India IMPS,this field is not applicable \n - For India UPI,this field is not applicable \n - For US EWS, this field is optional with max length 10 \n - For UK, this field is optional with max length 16 \n - For IN PAN,this field is not applicable \n - For Pay2China, this field is not required",
          "title": "postal_code"
        },
        "city": {
          "maxLength": 35,
          "minLength": 1,
          "type": "string",
          "description": "Creditor's city \n - For India IMPS,this field is not applicable \n - For India UPI,this field is not applicable \n - For US EWS, this field is optional with max length 25 \n - For UK, this field is optional with max length 35 \n - For IN PAN,this field is not applicable \n - For Pay2China, this field is not required",
          "title": "city"
        },
        "state": {
          "maxLength": 35,
          "minLength": 1,
          "type": "string",
          "description": "Creditor's state \n - For India IMPS,this field is not applicable \n - For India UPI,this field is not applicable \n - For US EWS, this field is optional with max length 25 \n - For UK, this field is optional with max length 35 \n - For IN PAN,this field is not applicable \n - For Pay2China, this field is not required",
          "title": "state"
        },
        "country": {
          "type": "string",
          "description": "Creditor's country \n - For India IMPS,this field is not applicable \n - For India UPI,this field is not applicable \n - For US EWS, this field is optional with max length 2 \n - For UK, this field is optional with max length 2 \n - For IN PAN,this field is not applicable \n - For Pay2China, this field is not required",
          "pattern": "^[A-Z]{2,2}$",
          "title": "country"
        },
        "birth_date": {
          "type": "string",
          "format": "date",
          "description": "ISO 8601 (YYYY-MM-DD), Creditor's birth date \n - For India IMPS,this field is not applicable \n - For India UPI,this field is not applicable \n - For US EWS, this field is optional \n - For UK, this field is optional \n - For IN PAN,this field is mandatory \n - For Pay2China, this field is not required",
          "title": "birth_date"
        },
        "home_phone_number": {
          "maxLength": 34,
          "minLength": 6,
          "type": "string",
          "description": "Creditor's home phone number \n - For India IMPS,this field is not applicable \n - For India UPI,this field is not applicable \n - For US EWS, this field is optional with max length 10 \n - For UK, this field is optional with max length 34 \n - For IN PAN,this field is not applicable \n - For Pay2China, this field is not required",
          "title": "home_phone_number"
        },
        "work_phone_number": {
          "maxLength": 34,
          "minLength": 6,
          "type": "string",
          "description": "Creditor's work phone number \n - For India IMPS,this field is not applicable \n - For India UPI,this field is not applicable \n - For US EWS, this field is optional with max length 10 \n - For UK, this field is optional with max length 34 \n - For IN PAN,this field is not applicable \n - For Pay2China, this is a conditional field. It is mandatory for first time onboarding and max length is 32",
          "title": "work_phone_number"
        },
        "beneficial_owner": {
          "type": "object",
          "title": "beneficial_owner",
          "properties": {
            "name": {
              "type": "string",
              "description": "Beneficiary Owner Name/Legal Rep name. \n - For IMPS India,this field is not applicable \n - For UPI India,this field is not applicable \n - For US EWS,this field is not applicable \n - For UK,this field is not applicable \n - For Pay2China, this is a conditional field. If the document.entity is business, this field should present for first time onboarding. If document.entity is Personal, this fields is not application and the max length is 32",
              "minLength": 1,
              "maxLength": 140,
              "title": "owner_name"
            },
            "id": {
              "type": "string",
              "description": "Beneficiary Owner Id/Legal Rep id. \n - For IMPS India,this field is not applicable \n - For UPI India,this field is not applicable \n - For US EWS,this field is not applicable \n - For UK,this field is not applicable \n - For IN PAN,this field is not applicable \n - For Pay2China, this is a conditional field. If the document.entity is business, this filed should present for first time onboarding. If document.entity is Personal, this fields is not application and max length is 32",
              "minLength": 1,
              "maxLength": 35,
              "title": "owner_id"
            }
          }
        },
        "document": {
          "type": "object",
          "title": "document",
          "properties": {
            "entity": {
              "type": "string",
              "description": "Whether the document belongs to Business or Individual \n - For India IMPS,this field is not applicable \n - For India UPI,this field is not applicable \n- For US EWS,this field is optional \n- For UK,this field is optional \n - For IN PAN,this field is not applicable \n - For Pay2China, this is mandatory",
              "enum": [
                "BUSINESS",
                "PERSONAL"
              ],
              "title": "entity"
            },
            "type": {
              "type": "string",
              "description": "Whether the document belongs to Business or Individual \n - For India IMPS,this field is not applicable \n - For India UPI,this field is not applicable \n- For US EWS,this field is optional \n- For UK,this field is optional \n - For IN PAN,this field is mandatory with applicable value  TXID \n - For Pay2China, this field is conditional. It is mandatory for first time onboarding. If the document.entity is Business, this filed value should be EMPL. If document.entity is Personal, this fields value should be NIDN \n- Personal Code values \n- ARNU  AlienRegistrationNumber \n- CCPT PassportNumber \n- CUST CustomerIdentificationNumber \n- DRLC  DriversLicenseNumber \n- EMPL EmployeeIdentificationNumber \n- NIDN  NationalIdentityNumber \n- SOSE SocialSecurityNumber \n- TELE  TelephoneNumber \n- TXID TaxIdentificationNumber \n- POID PersonCommercialIdentification \n - Corporate Code values \n- BANK BankPartyIdentification \n- CBID  Central Bank Identification Number \n- CHID Clearing Identification Number \n- COID CountryIdentificationCode \n- CUST CustomerNumber \n- DUNS Data Universal Numbering System \n- EMPL  EmployerIdentificationNumber \n- GS1G  GS1GLNIdentifier \n- SREN  SIREN \n- SRET SIRET \n- TXID  Tax Identification Number",
              "enum": [
                "ARNU",
                "CCPT",
                "CUST",
                "DRLC",
                "EMPL",
                "NIDN",
                "SOSE",
                "TELE",
                "TXID",
                "POID",
                "BANK",
                "CBID",
                "CHID",
                "COID",
                "DUNS",
                "GS1G",
                "SREN",
                "SRET"
              ],
              "title": "type"
            },
            "number": {
              "maxLength": 35,
              "minLength": 1,
              "type": "string",
              "description": "Creditor's document number \n - For India IMPS,this field is not applicable \n - For India UPI,this field is not applicable \n - For US EWS, this field is optional with max length 28 \n - For UK, this field is optional with max length 35 \n - For IN PAN,this field is mandatory with max length 10 \n - For Pay2China, this field is conditional. It is mandatory for first time onboarding and max length is 20",
              "title": "number"
            },
            "state": {
              "maxLength": 35,
              "minLength": 1,
              "type": "string",
              "description": "Creditor's document state \n - For India IMPS,this field is not applicable \n - For India UPI,this field is not applicable \n - For US EWS, this field is optional with max length 6 \n - For UK, this field is optional with max length 35 \n - For IN PAN,this field is not applicable \n - For Pay2China, this field is not required",
              "title": "state"
            }
          }
        }
      }
    },
    "method": {
      "type": "object",
      "title": "method",
      "properties": {
        "country": {
          "type": "string",
          "description": "ISO 3166 Alpha-2 code for the transaction country",
          "enum": [
            "IN",
            "US",
            "GB",
            "CN"
          ],
          "title": "country"
        },
        "method": {
          "type": "string",
          "description": "Method specified by the debtor for the validation",
          "enum": [
            "IMPS",
            "UPI",
            "BANKACCOUNT",
            "IBAN",
            "CARD",
            "PAYMENTID",
            "ID",
            "MERCHANTID"
          ],
          "title": "method"
        },
        "type": {
          "type": "string",
          "description": "Message type (e.g., CT for credit transfer,AER for Account Enquiry Request) \n - For India,this field is mandatory and allowed value is AER \n - For US EWS,this field is mandatory \n- For UK,this field is mandatory \n- Ownership - Account ownership is limited to validation of correct owner , hence the account number or equivalent ( i.e Virtual account) and Name \n- Attributes- Attributes define the properties of the object , for an account the properties should include Status , type of account, status of account , the address of the account  etc. \n- Structure - Structure refers to the mod 97 and the length as per the country of IBAN \n- TAXID-  Validation of individual or corporate tax id/tax documentation \n - For Pay2China, this field is mandatory with the value Ownership",
          "enum": [
            "AER",
            "Structure",
            "Ownership",
            "Attributes",
            "TAXID"
          ],
          "title": "type"
        },
        "penny_test": {
          "type": "string",
          "description": "This field enables selection of penny,non-penny or both validations \n- Applicable for IN IMPS",
          "enum": [
            "NONPENNY",
            "PENNY",
            "BOTH"
          ],
          "title": "penny_test"
        }
      },
      "required": [
        "country",
        "method",
        "type"
      ]
    }
  },
  "$defs": {
    "Address": {
      "type": "string",
      "maxLength": 70,
      "minLength": 1,
      "maxItems": 7,
      "description": "Address",
      "title": "Address"
    }
  }
}