{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/citi/main/json-schema/citi-certification-request-schema.json",
  "title": "CertificationRequest",
  "description": "Request body for submitting certification information for KYC verification.",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/citi-certification-api-openapi.yml#/components/schemas/Certification-Request",
  "allOf": [
    {
      "$ref": "#/$defs/Certification-Common-Details"
    },
    {
      "type": "object",
      "title": "Certification-Request",
      "required": [
        "country_code",
        "merchant_ack",
        "business"
      ]
    }
  ],
  "$defs": {
    "Account-Usage": {
      "type": "string",
      "title": "account_usage",
      "description": "Description of merchant's business purpose of using PSP account. Required for CN and HK."
    },
    "Birth-Details": {
      "title": "BirthDetails",
      "type": "object",
      "description": "Birth information of the business person.",
      "properties": {
        "date": {
          "allOf": [
            {
              "$ref": "#/$defs/Common-Date"
            }
          ],
          "title": "date",
          "description": "ISO 8601 (YYYY-MM-DD), birth_date is required for CN and HK."
        },
        "country_code": {
          "allOf": [
            {
              "$ref": "#/$defs/Country-Code"
            }
          ],
          "title": "country_code",
          "description": "Country code."
        },
        "state": {
          "type": "string",
          "title": "state",
          "minLength": 1,
          "maxLength": 2048,
          "description": "State (province of birth)."
        }
      }
    },
    "Business": {
      "title": "Business",
      "type": "object",
      "description": "Detailed information of the business for certification.",
      "required": [
        "name"
      ],
      "properties": {
        "name": {
          "allOf": [
            {
              "$ref": "#/$defs/Name"
            },
            {
              "description": "The full legal name of the business in English. Required for CN and HK."
            }
          ]
        },
        "name_in_local_language": {
          "type": "string",
          "title": "name_in_local_language",
          "minLength": 1,
          "maxLength": 128,
          "description": "The full legal name of the business in the local language. Required for CN and HK."
        },
        "establishment_date": {
          "allOf": [
            {
              "$ref": "#/$defs/Common-Date"
            }
          ],
          "title": "establishment_date",
          "description": "Company establishment date. Required for CN and HK."
        },
        "license_expiry_date": {
          "allOf": [
            {
              "$ref": "#/$defs/Common-Date"
            }
          ],
          "title": "license_expiry_date",
          "description": "Expiry date of company license; format yyyy-mm-dd. Fill in 9999-12-31 for a long-term license. Required for CN. For HK, this is expiry date of business registration."
        },
        "address": {
          "$ref": "#/$defs/Business-Address"
        },
        "products_and_services_category": {
          "type": "string",
          "title": "products_and_services_category",
          "description": "Products and services category. Required for CN and HK.",
          "minLength": 1,
          "maxLength": 20
        },
        "tax_id_type": {
          "type": "string",
          "title": "tax_id_type",
          "description": "Tax id type.",
          "enum": [
            "EIN",
            "SSN",
            "VAT",
            "TIN",
            "UTR"
          ]
        },
        "tax_id_number": {
          "type": "string",
          "title": "tax_id_number",
          "minLength": 1,
          "maxLength": 128,
          "description": "Tax id number."
        },
        "account_usage": {
          "type": "array",
          "title": "account_usage",
          "description": "List of account usage. Required for CN and HK.",
          "items": {
            "$ref": "#/$defs/Account-Usage"
          },
          "minItems": 1,
          "maxItems": 25
        },
        "description": {
          "type": "string",
          "title": "description",
          "minLength": 1,
          "maxLength": 2048,
          "description": "Description of the business. This is one of the three ways of proving the business."
        },
        "website": {
          "type": "string",
          "title": "website",
          "minLength": 1,
          "maxLength": 2048,
          "description": "Website URL. This is one of the three ways of proving the business."
        },
        "business_proof_file_id": {
          "allOf": [
            {
              "$ref": "#/$defs/File-Id"
            }
          ],
          "title": "business_proof_file_id",
          "description": "File ID for a screenshot of the business website/dashboards."
        },
        "documents": {
          "type": "array",
          "title": "documents",
          "description": "List of documents.",
          "items": {
            "$ref": "#/$defs/Document"
          }
        },
        "business_persons": {
          "type": "array",
          "title": "business_persons",
          "description": "List of business person.",
          "items": {
            "$ref": "#/$defs/Business-Person"
          }
        }
      }
    },
    "Business-Address": {
      "title": "BusinessAddress",
      "type": "object",
      "description": "Address information for company.",
      "properties": {
        "street_name": {
          "type": "string",
          "title": "street_name",
          "minLength": 1,
          "maxLength": 200,
          "description": "Street name. Required for CHINA and HONGKONG."
        },
        "postal_code": {
          "type": "string",
          "title": "postal_code",
          "minLength": 1,
          "maxLength": 16,
          "description": "Postal code or ZIP code. Required for CHINA and HONGKONG."
        },
        "city": {
          "type": "string",
          "title": "city",
          "minLength": 1,
          "maxLength": 200,
          "description": "City name. Required for CHINA and HONGKONG."
        },
        "district": {
          "type": "string",
          "title": "district",
          "minLength": 1,
          "maxLength": 200,
          "description": "District name. Required for CHINA and HONGKONG."
        },
        "state": {
          "type": "string",
          "title": "state",
          "minLength": 1,
          "maxLength": 200,
          "description": "State or province name. Required for CHINA and HONGKONG."
        }
      }
    },
    "Business-Person": {
      "title": "BusinessPerson",
      "description": "Business person details for KYC certification.",
      "allOf": [
        {
          "$ref": "#/$defs/Personal-Details"
        },
        {
          "type": "object",
          "properties": {
            "role": {
              "type": "string",
              "title": "role",
              "description": "Role of business person. Required for both CHINA and HONGKONG. <br> UBO, DIRECTOR_CONTROL_PERSON_OR_LEGAL_REP, AGENT_OR_AUTHORISED_PERSON are applicable for CHINA. <br> UBO, DIRECTOR_CONTROL_PERSON_OR_LEGAL_REP, AGENT_OR_AUTHORISED_PERSON are applicable for HONGKONG. <br> For the limitation on the number of business persons- <br> UBO - 4 maximum across all regions (as UBO is defined as shareholding above 25%). <br> Legal rep/Director - 1 for CN (only one legal rep per CN law) and up to 25 directors for HK. <br> Agent - 1, as there can only be 1 agent.",
              "enum": [
                "OWNER_OR_OPERATOR",
                "PARTNER",
                "UBO",
                "DIRECTOR_CONTROL_PERSON_OR_LEGAL_REP",
                "AGENT_OR_AUTHORISED_PERSON"
              ]
            },
            "alias": {
              "type": "string",
              "title": "alias",
              "minLength": 1,
              "maxLength": 2048,
              "description": "Business person's alias name."
            },
            "nationality": {
              "type": "string",
              "title": "nationality",
              "description": "Business person's nationality. Required for CHINA and HONGKONG.",
              "pattern": "^[A-Z]{2,2}$"
            },
            "gender": {
              "type": "string",
              "title": "gender",
              "description": "Business person's gender.",
              "enum": [
                "MALE",
                "FEMALE"
              ]
            },
            "birth_details": {
              "$ref": "#/$defs/Birth-Details"
            },
            "address": {
              "$ref": "#/$defs/Business-Person-Address"
            },
            "tax_id_number": {
              "type": "string",
              "title": "tax_id_number",
              "minLength": 1,
              "maxLength": 128,
              "description": "Tax id number."
            },
            "business_title": {
              "type": "string",
              "title": "business_title",
              "minLength": 1,
              "maxLength": 2048,
              "description": "Business title."
            },
            "documents": {
              "type": "array",
              "description": "List of documents",
              "title": "documents",
              "items": {
                "$ref": "#/$defs/Person-Document"
              }
            }
          }
        }
      ]
    },
    "Business-Person-Address": {
      "title": "BusinessPersonAddress",
      "description": "Business person address information.",
      "allOf": [
        {
          "$ref": "#/$defs/Business-Address"
        },
        {
          "type": "object",
          "title": "Business-Person-Address",
          "properties": {
            "country_code": {
              "allOf": [
                {
                  "$ref": "#/$defs/Country-Code"
                }
              ],
              "title": "country_code",
              "description": "Country code. Required for CHINA and HONGKONG."
            }
          }
        }
      ]
    },
    "Certification-Common-Details": {
      "title": "CertificationCommonDetails",
      "type": "object",
      "description": "Certification details.",
      "properties": {
        "country_code": {
          "allOf": [
            {
              "$ref": "#/$defs/Country-Code"
            }
          ],
          "title": "country_code",
          "description": "Country code."
        },
        "merchant_ack": {
          "type": "string",
          "title": "merchant_ack",
          "description": "Has the merchant signed the payment service provider service terms? YES or NO.",
          "enum": [
            "YES",
            "NO"
          ]
        },
        "business": {
          "$ref": "#/$defs/Business"
        }
      }
    },
    "Common-Date": {
      "type": "string",
      "title": "date",
      "format": "date",
      "description": "Date in ISO 8601 (YYYY-MM-DD)."
    },
    "Country-Code": {
      "type": "string",
      "title": "country_code",
      "pattern": "^[A-Z]{2,2}$",
      "description": "Country code."
    },
    "Document": {
      "title": "Document",
      "type": "object",
      "description": "Document information for KYC validation including document type, sub-type, and file reference.",
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "title": "type",
          "description": "Type of identity document (ID). <br> certificate_of_registration is applicable for CHINA. <br> certificate_of_incorporation and business_registration are applicable for HONGKONG.",
          "enum": [
            "CERTIFICATE_OF_REGISTRATION",
            "CERTIFICATE_OF_INCORPORATION",
            "BUSINESS_REGISTRATION",
            "SHARE_STRUCTURE",
            "COMPANY_CONSTITUTION_OR_ANNUAL_REPORT",
            "ARTICLE_OF_ASSOCIATION",
            "UBO_DECLARATION",
            "PARTNERSHIP_MINUTES_OF_MEETING",
            "PARTNERSHIP_DEED",
            "CERTIFICATE_OF_INCUMBENCY",
            "INDONESIA_MINISTRY_OFFICIAL_APPROVAL_PROOF",
            "OFFICE_PHOTO",
            "PROOF_OF_ADDRESS",
            "BANK_ACCOUNT_PROOF",
            "BUSINESS_URL_OWNERSHIP"
          ]
        },
        "sub_type": {
          "type": "string",
          "title": "sub_type",
          "description": "Applicable only if the type is certificate_of_registration.",
          "enum": [
            "ACRA",
            "GST",
            "MSME",
            "CERTIFICATE_OF_REGISTRATION"
          ]
        },
        "number": {
          "type": "string",
          "title": "number",
          "minLength": 1,
          "maxLength": 128,
          "description": "Document ID number. <br> required if type is certificate_of_registration for CHINA. <br> required if type are certificate_of_incorporation and business_registration for HONGKONG."
        },
        "file_id": {
          "$ref": "#/$defs/File-Id"
        }
      }
    },
    "File-Id": {
      "type": "string",
      "description": "Unique identifier for the document uploaded.",
      "title": "file_id",
      "minLength": 1,
      "maxLength": 128
    },
    "Name": {
      "type": "string",
      "title": "name",
      "minLength": 1,
      "maxLength": 128
    },
    "Person-Document": {
      "title": "PersonDocument",
      "type": "object",
      "description": "Document information for business person KYC validation.",
      "required": [
        "type",
        "sub_type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "title": "type",
          "description": "Type of identity document (ID). Provide details for one primary identity document (CHINESE_RESIDENT_IDENTITY_CARD, NATIONAL_OR_STATE_ID, PASSPORT, DRIVERS_LICENSE, RESIDENCE_PERMIT, TAX_ID, PROOF_OF_AGE_CARD, MY_NUMBER_CARD, MAINLAND_TRAVEL_PERMIT), optionally supplemented by AUTHORISED_LETTER, PROOF_OF_ADDRESS, or HAND_HOLD_PHOTO if required. <br> AUTHORISED_LETTER is required if the role is AUTHORISED_PERSON <br> NATIONAL_OR_STATE_ID, PASSPORT, RESIDENCE_PERMIT, MAINLAND_TRAVEL_PERMIT are applicable for CHINA. <br> NATIONAL_OR_STATE_ID, PASSPORT, RESIDENCE_PERMIT, CHINESE_RESIDENT_IDENTITY_CARD, MAINLAND_TRAVEL_PERMIT are applicable for HONGHONG.",
          "enum": [
            "CHINESE_RESIDENT_IDENTITY_CARD",
            "NATIONAL_OR_STATE_ID",
            "PASSPORT",
            "DRIVERS_LICENSE",
            "RESIDENCE_PERMIT",
            "TAX_ID",
            "PROOF_OF_AGE_CARD",
            "MY_NUMBER_CARD",
            "MAINLAND_TRAVEL_PERMIT",
            "AUTHORISED_LETTER",
            "PROOF_OF_ADDRESS",
            "HAND_HOLD_PHOTO"
          ]
        },
        "sub_type": {
          "type": "string",
          "title": "sub_type",
          "description": "Applicable for all id type other than PASSPORT. Front and Back both sub_type is applicable for CN and HK. When BACK is used, number, expiry_date, issue_date, issuing_authority are not required.",
          "enum": [
            "FRONT",
            "BACK"
          ]
        },
        "number": {
          "type": "string",
          "title": "number",
          "minLength": 1,
          "maxLength": 128,
          "description": "Document ID number. Required for CHINA and HONGKONG."
        },
        "expiry_date": {
          "allOf": [
            {
              "$ref": "#/$defs/Common-Date"
            }
          ],
          "title": "expiry_date",
          "description": "The expiry date of the ID document; format yyyy-mm-dd. Fill in 9999-12-31 if there is no expiry date. Required for CHINA and HONGKONG."
        },
        "issue_date": {
          "allOf": [
            {
              "$ref": "#/$defs/Common-Date"
            }
          ],
          "title": "issue_date",
          "description": "Issuing date of the ID document; format yyyy-mm-dd. Required for CHINA and HONGKONG."
        },
        "issuing_authority": {
          "type": "string",
          "title": "issuing_authority",
          "minLength": 1,
          "maxLength": 2048,
          "description": "Issuing authority of merchant's identity document. Required for CHINA and HONGKONG."
        },
        "file_id": {
          "$ref": "#/$defs/File-Id"
        }
      }
    },
    "Personal-Details": {
      "title": "Personal-Details",
      "type": "object",
      "description": "This section contains the name details.",
      "properties": {
        "first_name": {
          "type": "string",
          "title": "first_name",
          "minLength": 1,
          "maxLength": 64,
          "description": "Business person's first name in English. Required for CN and HK."
        },
        "first_name_in_local_language": {
          "type": "string",
          "title": "first_name_in_local_language",
          "minLength": 1,
          "maxLength": 64,
          "description": "Business person's first name in local language. Required for CN and HK."
        },
        "middle_name": {
          "type": "string",
          "title": "middle_name",
          "minLength": 1,
          "maxLength": 64,
          "description": "Business person's middle name in English. Optional for CN and HK."
        },
        "middle_name_in_local_language": {
          "type": "string",
          "title": "middle_name_in_local_language",
          "minLength": 1,
          "maxLength": 64,
          "description": "Business person's middle name in local language. Optional for CN and HK."
        },
        "last_name": {
          "type": "string",
          "title": "last_name",
          "minLength": 1,
          "maxLength": 64,
          "description": "Business person's last name in English. Required for CN and HK."
        },
        "last_name_in_local_language": {
          "type": "string",
          "title": "last_name_in_local_language",
          "minLength": 1,
          "maxLength": 64,
          "description": "Business person's full name in local language. Required for CN and HK."
        }
      }
    }
  }
}