LinkAccountRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/citi/main/json-schema/citi-link-account-request-schema.json",
  "title": "LinkAccountRequest",
  "description": "Request body for linking an external account for payments.",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/citi-linkaccount-api-openapi.yml#/components/schemas/Link-Account-Request",
  "type": "object",
  "required": [
    "creditor_account",
    "creditor_bank",
    "creditor"
  ],
  "properties": {
    "creditor_account": {
      "$ref": "#/$defs/Creditor-Account"
    },
    "creditor_bank": {
      "$ref": "#/$defs/Creditor-Bank"
    },
    "creditor": {
      "$ref": "#/$defs/Creditor"
    },
    "file_id": {
      "$ref": "#/$defs/File-Id"
    }
  },
  "$defs": {
    "Address": {
      "title": "Address",
      "description": "Address/",
      "allOf": [
        {
          "$ref": "#/$defs/Address-Details"
        },
        {
          "type": "object",
          "title": "Address-Details",
          "required": [
            "country_code",
            "city",
            "state"
          ]
        }
      ]
    },
    "Address-Details": {
      "title": "AddressDetails",
      "type": "object",
      "description": "Address information for the bank.",
      "properties": {
        "city": {
          "type": "string",
          "title": "city",
          "description": "City.",
          "minLength": 1,
          "maxLength": 128
        },
        "state": {
          "type": "string",
          "title": "state",
          "description": "State.",
          "minLength": 1,
          "maxLength": 128
        },
        "country_code": {
          "allOf": [
            {
              "$ref": "#/$defs/Country-Code"
            }
          ],
          "title": "country_code",
          "description": "Country code."
        },
        "address_line": {
          "type": "string",
          "title": "address_line",
          "description": "Detailed address of the bank.",
          "minLength": 1,
          "maxLength": 256
        }
      }
    },
    "Common-Creditor": {
      "title": "CommonCreditor",
      "type": "object",
      "description": "This section contains the details information of creditor.",
      "properties": {
        "type": {
          "type": "string",
          "title": "type",
          "description": "Type of creditor.",
          "enum": [
            "00"
          ]
        },
        "name": {
          "allOf": [
            {
              "$ref": "#/$defs/Name"
            },
            {
              "description": "Name of the account."
            }
          ]
        },
        "contact_number": {
          "type": "string",
          "title": "contact_number",
          "description": "Full contact number.",
          "minLength": 1,
          "maxLength": 32
        },
        "contact_prefix": {
          "type": "string",
          "title": "contact_prefix",
          "description": "International telephone area code.",
          "minLength": 1,
          "maxLength": 32
        },
        "email": {
          "type": "string",
          "title": "email",
          "description": "Email address of the merchant.",
          "minLength": 1,
          "maxLength": 32
        }
      }
    },
    "Country-Code": {
      "type": "string",
      "title": "country_code",
      "pattern": "^[A-Z]{2,2}$",
      "description": "Country code."
    },
    "Creditor": {
      "title": "Creditor",
      "description": "This section contains the details information of creditor.",
      "allOf": [
        {
          "$ref": "#/$defs/Common-Creditor"
        },
        {
          "type": "object",
          "title": "Common-Creditor",
          "required": [
            "type",
            "name",
            "address"
          ],
          "properties": {
            "creditor_partner_user_id": {
              "$ref": "#/$defs/Partner-User-Id"
            },
            "address": {
              "$ref": "#/$defs/Creditor-Address"
            }
          }
        }
      ]
    },
    "Creditor-Account": {
      "title": "CreditorAccount",
      "description": "Creditor Account.",
      "allOf": [
        {
          "$ref": "#/$defs/Creditor-Account-Details"
        },
        {
          "type": "object",
          "title": "Creditor-Account'",
          "required": [
            "holder_type",
            "number",
            "name",
            "currency_code"
          ]
        }
      ]
    },
    "Creditor-Account-Details": {
      "title": "CreditorAccountDetails",
      "type": "object",
      "description": "This section contains the details information of account.",
      "properties": {
        "holder_type": {
          "type": "string",
          "title": "holder_type",
          "description": "The type of account holder.",
          "enum": [
            "PERSONAL",
            "COMPANY"
          ]
        },
        "holder_contact_number": {
          "type": "string",
          "title": "holder_contact_number",
          "description": "The full contact number, including the country code if mobile.",
          "minLength": 1,
          "maxLength": 32
        },
        "number": {
          "type": "string",
          "title": "number",
          "description": "Unique account number.",
          "minLength": 1,
          "maxLength": 64
        },
        "name": {
          "allOf": [
            {
              "$ref": "#/$defs/Name"
            },
            {
              "description": "Name of the account."
            }
          ]
        },
        "currency_code": {
          "allOf": [
            {
              "$ref": "#/$defs/Currency-Code"
            }
          ],
          "title": "currency_code",
          "description": "Currency of the account (3-character ISO code)."
        },
        "iban": {
          "type": "string",
          "title": "iban",
          "description": "International Bank Account Number (IBAN). IBAN is not applicable for CN and HK.",
          "minLength": 1,
          "maxLength": 32
        },
        "document_type": {
          "type": "string",
          "title": "document_type",
          "description": "Type of identity document (ID). One of the following 00 Chinese national ID card 01 Chinese residence permit 02 Passport 03 ID card of Hong Kong, Macao or Taiwan 04 Residence permit of Hong Kong, Macao and Taiwan 05 Hong Kong and Macao travel permit 06 Other national ID card 07 Other residence permit",
          "enum": [
            "CHINESE_NATIONAL_ID_CARD",
            "CHINESE_RESIDENCE_PERMIT",
            "PASSPORT",
            "ID_CARD_OF_HONGKONG_MACAO_OR_TAIWAN",
            "RESIDENCE_PERMIT_OF_HONGKONG_MACAO_AND_TAIWAN",
            "HONGKONG_AND_MACAO_TRAVEL_PERMIT",
            "OTHER_NATIONAL_ID_CARD",
            "OTHER_RESIDENCE_PERMIT"
          ]
        },
        "document_number": {
          "type": "string",
          "title": "document_number",
          "description": "Account holder's ID number.",
          "minLength": 1,
          "maxLength": 64
        }
      }
    },
    "Creditor-Address": {
      "title": "CreditorAddress",
      "description": "Address information for the creditor.",
      "allOf": [
        {
          "$ref": "#/$defs/Address-Details"
        },
        {
          "$ref": "#/$defs/Partial-Address"
        },
        {
          "type": "object",
          "title": "Creditor-Address",
          "required": [
            "country_code",
            "city",
            "state"
          ]
        }
      ]
    },
    "Creditor-Bank": {
      "title": "CreditorBank",
      "description": "Creditor Bank.",
      "allOf": [
        {
          "$ref": "#/$defs/Creditor-Bank-Details"
        },
        {
          "type": "object",
          "title": "Creditor-Bank",
          "required": [
            "name",
            "address"
          ],
          "properties": {
            "address": {
              "$ref": "#/$defs/Address"
            }
          }
        }
      ]
    },
    "Creditor-Bank-Details": {
      "title": "CreditorBankDetails",
      "type": "object",
      "description": "This section contains the details information of bank.",
      "properties": {
        "name": {
          "allOf": [
            {
              "$ref": "#/$defs/Name"
            },
            {
              "description": "Name of the bank.",
              "minLength": 1,
              "maxLength": 256
            }
          ]
        },
        "code": {
          "type": "string",
          "title": "code",
          "description": "Bank code.",
          "minLength": 1,
          "maxLength": 32
        },
        "branch_name": {
          "type": "string",
          "title": "branch_name",
          "description": "Branch name where the account is held.",
          "minLength": 1,
          "maxLength": 128
        },
        "branch_number": {
          "type": "string",
          "title": "branch_number",
          "description": "Branch code where the account is held.",
          "minLength": 1,
          "maxLength": 32
        },
        "swift_code": {
          "type": "string",
          "title": "swift_code",
          "description": "SWIFT BIC (Bank Identifier Code).",
          "minLength": 1,
          "maxLength": 64
        },
        "routing_number": {
          "type": "string",
          "title": "routing_number",
          "description": "Routing code.",
          "minLength": 1,
          "maxLength": 64
        },
        "ifsc_code": {
          "type": "string",
          "title": "ifsc_code",
          "description": "Indian Financial System Code (IFSC).",
          "minLength": 1,
          "maxLength": 64
        },
        "sort_code": {
          "type": "string",
          "title": "sort_code",
          "description": "Sort code.",
          "minLength": 1,
          "maxLength": 32
        }
      }
    },
    "Currency-Code": {
      "type": "string",
      "title": "currency_code",
      "description": "The currency code in the transaction.",
      "pattern": "^[A-Z]{3}$"
    },
    "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
    },
    "Partial-Address": {
      "title": "PartialAddress",
      "description": "Address information for the creditor.",
      "type": "object",
      "properties": {
        "street_name": {
          "type": "string",
          "title": "street_name",
          "description": "Street name.",
          "minLength": 1,
          "maxLength": 128
        },
        "postal_code": {
          "type": "string",
          "title": "postal_code",
          "description": "Postal code.",
          "minLength": 1,
          "maxLength": 16
        }
      }
    },
    "Partner-User-Id": {
      "type": "string",
      "description": "Partner user identifier for seller from your system.",
      "title": "partner_user_id",
      "minLength": 1,
      "maxLength": 50
    }
  }
}