AmendMandateDetails

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/citi/main/json-schema/citi-amend-mandate-details-schema.json",
  "title": "AmendMandateDetails",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/citi-mandates-api-openapi.yml#/components/schemas/AmendMandateDetails",
  "type": "object",
  "required": [
    "amend_details",
    "amendment_mandate_details"
  ],
  "properties": {
    "amend_details": {
      "$ref": "#/$defs/AmendDetails"
    },
    "amendment_mandate_details": {
      "$ref": "#/$defs/AmendmentMandateDetails"
    },
    "amendment_initiating_party": {
      "$ref": "#/$defs/AmendmentInitiatingParty"
    },
    "amendment_creditor": {
      "$ref": "#/$defs/AmendmentCreditor"
    },
    "amendment_ultimate": {
      "$ref": "#/$defs/AmendmentUltimate"
    }
  },
  "$defs": {
    "AmendDetails": {
      "title": "AmendDetails",
      "type": "object",
      "required": [
        "amend_reason"
      ],
      "properties": {
        "amend_reason": {
          "title": "amend_reason",
          "type": "string",
          "enum": [
            "MD16",
            "MD17",
            "MD18",
            "MS02",
            "MS03",
            "NARR"
          ],
          "description": "Specification of amendment reason <br> MD16-Requested By Customer <br> MD17-Requested By Initiating Party<br> MD18-Requested By Initiating Party And Customer<br>MS02-Not Specified Reason Customer<br>MS03-Not Specified Reason Agent Generated <br> MSUC-Mandate suspended after 7 consecutive unsuccessful collections <br> NARR- Reason is provided as narrative information"
        },
        "amend_additional_information": {
          "title": "amend_additional_information",
          "type": "string",
          "description": "Specification of amendment additional information"
        }
      }
    },
    "AmendmentCreditor": {
      "title": "AmendmentCreditor",
      "type": "object",
      "properties": {
        "name": {
          "title": "name",
          "type": "string",
          "minLength": 1,
          "maxLength": 140,
          "description": "Specify the name by which a party is known and which is used to identify that party. For Australia, this parameter is allowed to amend unilaterally."
        },
        "address_1": {
          "title": "address_1",
          "type": "string",
          "minLength": 1,
          "maxLength": 70,
          "description": "Specify the address of the party who involves in the payment flow. This parameter is not applicable to Australia."
        },
        "address_2": {
          "title": "address_2",
          "type": "string",
          "minLength": 1,
          "maxLength": 70,
          "description": "Specify the address of the party who involves in the payment flow. This parameter is not applicable to Australia."
        },
        "address_3": {
          "title": "address_3",
          "type": "string",
          "minLength": 1,
          "maxLength": 70,
          "description": "Specify the address of the party who involves in the payment flow. This parameter is not applicable to Australia."
        },
        "country_code": {
          "title": "country_code",
          "type": "string",
          "pattern": "^[A-Z]{2}$",
          "description": "Specify the country code of the creditor address. This parameter is not applicable to Australia."
        },
        "postal_code": {
          "title": "postal_code",
          "type": "string",
          "minLength": 1,
          "maxLength": 16,
          "description": "Specify the postal code of the creditor address. This parameter is not applicable to Australia."
        },
        "town_name": {
          "title": "town_name",
          "type": "string",
          "minLength": 1,
          "maxLength": 35,
          "description": "Specify the town name of the creditor address. This parameter is not applicable to Australia."
        },
        "mobile_number": {
          "title": "mobile_number",
          "type": "string",
          "pattern": "^\\+[0-9]{1,3}-[0-9()+\\\\-]{1,30}$",
          "description": "Specify the mobile number of the creditor address. This parameter is not applicable to Australia."
        },
        "fax_number": {
          "title": "fax_number",
          "type": "string",
          "pattern": "^\\+[0-9]{1,3}-[0-9()+\\\\-]{1,30}$",
          "description": "Specify the fax number of the creditor address. This parameter is not applicable to Australia."
        },
        "email": {
          "title": "email",
          "type": "string",
          "format": "email",
          "description": "Specify the Address for electronic mail (e-mail). This parameter is not applicable to Australia."
        },
        "other_identification_category": {
          "title": "other_identification_category",
          "type": "string",
          "enum": [
            "ORG",
            "PVT"
          ],
          "description": "Specify the unique and unambiguous identification of a party. The value will be either `ORG` or `PVT`. For Australia, this parameter is allowed to amend unilaterally."
        },
        "other_identification_type": {
          "title": "other_identification_type",
          "type": "string",
          "minLength": 1,
          "maxLength": 35,
          "description": "Specify the unique and unambiguous way to identify an organization/private identification. For Australia, this parameter is allowed to amend unilaterally."
        },
        "other_identification": {
          "title": "other_identification",
          "type": "string",
          "minLength": 1,
          "maxLength": 35,
          "description": "Specify the value of an organization/private identification. For Australia this parameter is allowed to amend unilaterally."
        },
        "iban": {
          "title": "iban",
          "type": "string",
          "minLength": 1,
          "maxLength": 35,
          "description": "An identifier used internationally by financial institutions to uniquely identify the account of a customer at a financial institution, as described in the latest edition of the international standard ISO 13616: 2007 - Banking and related financial services - International Bank Account Number (IBAN). This parameter is not applicable to Australia."
        },
        "bank_routing_code": {
          "title": "bank_routing_code",
          "type": "string",
          "minLength": 1,
          "maxLength": 35,
          "description": "Specify the Code allocated to a financial institution by the ISO 9362 Registration Authority as described in ISO 9362 Banking - Banking telecommunication messages - Business identifier code (BIC). For Australia this parameter is not allowed to amend."
        },
        "bank_branch_code": {
          "title": "bank_branch_code",
          "type": "string",
          "minLength": 1,
          "maxLength": 35,
          "description": "Specify the 6-digit BSB/9-digit account identification assigned by the Entity. For Australia this parameter is not allowed to amend."
        },
        "scheme_identification": {
          "title": "scheme_identification",
          "type": "string",
          "minLength": 1,
          "maxLength": 35,
          "description": "Specify the  originator Creditor Scheme Identifier. This parameter is not applicable for Australia."
        },
        "account": {
          "title": "account",
          "type": "string",
          "minLength": 1,
          "maxLength": 35,
          "description": "Specify the unambiguous identification of the account of the creditor to which a debit entry will be posted as a result of the payment transaction. For Australia, this parameter is allowed to amend unilaterally."
        },
        "account_type": {
          "title": "account_type",
          "type": "string",
          "enum": [
            "AIIN",
            "BBAN",
            "CUID",
            "UPIC",
            "ALIA"
          ],
          "description": "Specify the name of the identification scheme, in a coded form as published in an external list.<br>AIIN -Issuer Identification Number<br>BBAN- BBAN Identifier<br>CUID -CHIPS Universal Identifier<br>UPIC- UPIC Identifier<br>ALIA-Alias (proxy). For Australia this parameter is allowed to amend unilaterally."
        },
        "proxy_id": {
          "title": "proxy_id",
          "type": "string",
          "minLength": 1,
          "maxLength": 2048,
          "description": "Specify the Identification used to indicate the account identification under another specified name. For Australia, this parameter is allowed to amend unilaterally."
        },
        "proxy_type": {
          "title": "proxy_type",
          "type": "string",
          "enum": [
            "TELE",
            "EMAL",
            "DNAM",
            "CINC",
            "COTX",
            "COID",
            "CUST",
            "DRLC",
            "EIDN",
            "EWAL",
            "PVTX",
            "LEIC",
            "MBNO",
            "NIDN",
            "CCPT",
            "SHID",
            "SOSE",
            "TOKN",
            "UBIL",
            "VIPN",
            "BIID"
          ],
          "description": "Specify the name of the identification scheme, in a coded form as published in an external list. Specify the value only when the mandate request is other than the payer (debtor) account number:<br>TELE-TelephoneNumber<br>EMAL-EmailAddress<br>DNAM-DomainName<br>CINC-CertificateOfIncorporationNumber<br>COTX-CorporateTaxIdentification<br>COID-CountryAuthorityIdentification<br>CUST-CustomerIdentificationNumber<br>DRLC-DriverLicenseNumber<br>EIDN-ElectronicIdentification<br>EWAL-EWalletIdentification<br>PVTX-IndividualTaxIdentification<br>LEIC-LegalEntityIdentifierCode<br>MBNO-MobilePhoneNumber<br>NIDN-NationalIdentificationNumber<br>CCPT-PassportNumber<br>SHID-SchemeIdentificationNumber<br>SOSE-SocialSecurityNumber<br>TOKN-TokenIdentification<br>UBIL-UtilitiesSubscriptionIdentification<br>VIPN-VehicleIdentificationPlateNumber<br>BIID-BillerSubscriberIdentification. For Australia, this parameter is allowed to amend unilaterally."
        }
      }
    },
    "AmendmentInitiatingParty": {
      "title": "AmendmentInitiatingParty",
      "type": "object",
      "properties": {
        "name": {
          "title": "name",
          "type": "string",
          "minLength": 1,
          "maxLength": 140,
          "description": "Specify the name by which a party is known and which is used to identify that party. For Australia, this parameter is allowed to amend unilaterally."
        },
        "account": {
          "title": "account",
          "type": "string",
          "minLength": 1,
          "maxLength": 35,
          "description": "Specify the unique identification of an account, as assigned by the account servicer, using an identification scheme. For Australia, this parameter is allowed to amend unilaterally."
        },
        "other_identification_category": {
          "title": "other_identification_category",
          "type": "string",
          "enum": [
            "ORG",
            "PVT"
          ],
          "description": "Specify the unique and unambiguous identification of a party. the value will be organization/Private. For Australia this parameter is not allowed to amend."
        },
        "other_identification_type": {
          "title": "other_identification_type",
          "type": "string",
          "minLength": 1,
          "maxLength": 35,
          "description": "Specify the unique and unambiguous type to identify an organization/private identification. For Australia, this parameter is allowed to amend unilaterally."
        },
        "other_identification": {
          "title": "other_identification",
          "type": "string",
          "description": "Specify the value of an organization/private identification type. For Australia this parameter is not allowed to amend.",
          "minLength": 1,
          "maxLength": 35
        },
        "bank_routing_code": {
          "title": "bank_routing_code",
          "type": "string",
          "minLength": 8,
          "maxLength": 11,
          "description": "Specify the unique identification of an organization, as assigned by an institution, using an identification scheme. For Australia this parameter is not allowed to amend. "
        }
      }
    },
    "AmendmentMandateDetails": {
      "title": "AmendmentMandateDetails",
      "type": "object",
      "required": [
        "country",
        "instruction_priority"
      ],
      "properties": {
        "becs_user_identification": {
          "title": "becs_user_identification",
          "type": "string",
          "minLength": 1,
          "maxLength": 35,
          "description": "BECS user ID related to migrated DDR mandate. For Australia this parameter is not allowed to amend."
        },
        "country": {
          "title": "country",
          "type": "string",
          "pattern": "^[A-Z]{2}$",
          "description": "Specify the country code where the mandate request has been originated.<br>Australia = AU<br>Hongkong = HK<br>Argentina = AR<br>SEPA = UK"
        },
        "mandate_description": {
          "title": "mandate_description",
          "type": "string",
          "minLength": 1,
          "maxLength": 140,
          "description": "Specify the description of the reason for mandate setup as narrative text.<br> This parameter is specific to Australia. both mandate_description and mandate_additional_ information parameters are expected to be sent by client for Australia. For Australia, this parameter is allowed to amend unilaterally."
        },
        "sequence_type": {
          "title": "sequence_type",
          "type": "string",
          "enum": [
            "RCUR",
            "OOFF"
          ],
          "description": "Specify the underlying transaction sequence as either recurring or one-off. For Australia this parameter is not allowed to amend."
        },
        "payment_frequency": {
          "title": "payment_frequency",
          "type": "string",
          "enum": [
            "ADHO",
            "DAIL",
            "FRTN",
            "INDA",
            "MIAN",
            "MNTH",
            "QURT",
            "WEEK",
            "YEAR"
          ],
          "description": "Specify the regularity of an event.<br>ADHO = Ad hoc (Event takes place on request or as necessary)<br>DAIL = Daily (Event takes place every day)<br>FRTN = Fortnightly (Event takes place every two weeks)<br>INDA = Intraday (Event takes place several times a day)<br>MIAN = Semiannual (Event takes place every six months or two times a year)<br>MNTH = Monthly (Event takes place every month)<br>QURT = Quarterly (Event takes place every three months)<br>WEEK = Weekly (Event takes place once a week)<br>YEAR = Annual (Event takes place every year or once a year) For Australia this parameter is allowed to amend bilaterally"
        },
        "count_per_period": {
          "title": "count_per_period",
          "type": "string",
          "pattern": "^(?=.{1,19}$)[0-9]{0,19}(?:\\.[0-9]{0,18})?$",
          "description": "Specify the frequency in terms of the number of instructions to be created and processed during the specified period. For Australia, this parameter is allowed to amend bilaterally."
        },
        "point_in_time": {
          "title": "point_in_time",
          "type": "string",
          "pattern": "^[0-9]{2}$",
          "description": "Specify the frequency in terms of an exact point in time or moment within the specified period. For Australia, this parameter is allowed to amend bilaterally."
        },
        "tracking_indicator": {
          "title": "tracking_indicator",
          "type": "boolean",
          "description": "Specify the indicating value either True or False, whether the direct debit instructions should be automatically re-submitted periodically when bilaterally agreed. For Australia, this parameter is allowed to amend bilaterally."
        },
        "mandate_additional_information": {
          "title": "mandate_additional_information",
          "type": "string",
          "minLength": 1,
          "maxLength": 140,
          "description": "Specify the additional information in free text form to complement the mandate information. For Australia, this parameter is allowed to amend unilaterally."
        },
        "payment_execution_not_before_time": {
          "title": "payment_execution_not_before_time",
          "type": "string",
          "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.[0-9]{1,3})?(?:Z)|(-)$",
          "description": "Indicates that each execution of the mandate payment should not occur before a given time(hh:mm:ss.sssZ) of that execution day. This parameter is specific to Australia. For Australia this parameter is allowed to amend bilaterally."
        },
        "transfer_arrangement": {
          "title": "transfer_arrangement",
          "type": "string",
          "description": "Indication of future transfer date, conditions of sale and requirement to hold funds. This parameter is specific to Australia. For Australia this parameter is allowed to amend bilaterally.",
          "minLength": 1,
          "maxLength": 140
        },
        "resolution_requested_by": {
          "title": "resolution_requested_by",
          "type": "string",
          "minLength": 1,
          "maxLength": 30,
          "description": "Time used to indicate by when resolution of a bilateral action is requested from the other party to the mandate. This parameter is specific to Australia. For Australia, this parameter is not allowed to amend."
        },
        "service_id": {
          "title": "service_id",
          "type": "string",
          "minLength": 1,
          "maxLength": 30,
          "description": "specify a pre-agreed service or level of service between the parties. This parameter is mandatory for Australia. For Australia, this parameter is not allowed to amend unilaterally."
        },
        "instruction_priority": {
          "title": "instruction_priority",
          "type": "string",
          "enum": [
            "NORM",
            "UNAT"
          ],
          "description": " Specifies the priority level of an event. For Australia This parameter is not allowed to amend."
        },
        "mandate_start_date": {
          "title": "mandate_start_date",
          "type": "string",
          "pattern": "^(?:[1-9]\\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)$",
          "description": "Start date of the validity of the mandate. Calender year expressed in the YYYY-MM-DD format. For Australia, this parameter is not allowed for amendment."
        },
        "mandate_expiry_date": {
          "title": "mandate_expiry_date",
          "type": "string",
          "pattern": "^(?:[1-9]\\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)$",
          "description": "Specify the End date of the validity of the mandate. Calender year expressed in the YYYY-MM-DD format. For Australia this parameter is allowed to amend bilaterally."
        },
        "mandate_first_collection_date": {
          "title": "mandate_first_collection_date",
          "type": "string",
          "pattern": "^(?:[1-9]\\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)$",
          "description": "Specify the Date of the first collection of a direct debit as per the mandate. Calender year expressed in the YYYY-MM-DD format. For Australia this parameter is allowed to amend bilaterally."
        },
        "mandate_final_collection_date": {
          "title": "mandate_final_collection_date",
          "type": "string",
          "pattern": "^(?:[1-9]\\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)$",
          "description": "Specify the Date of the final collection of a direct debit as per the mandate. Calender year expressed in the YYYY-MM-DD format. For Australia this parameter is allowed to amend bilaterally."
        },
        "mandate_type": {
          "title": "mandate_type",
          "type": "string",
          "enum": [
            "DDMC",
            "DDMP",
            "DDMU",
            "DDTP",
            "SOTP",
            "OTHR"
          ],
          "description": "Specify the type of mandate. For Australia This parameter is not allowed to amend."
        },
        "mandate_scheme": {
          "title": "mandate_scheme",
          "type": "string",
          "minLength": 1,
          "maxLength": 35,
          "description": "Specify the arrangement (unilateral or bilateral) and the party that established the mandate. For Australia This parameter is not allowed to amend."
        },
        "mandate_purpose": {
          "title": "mandate_purpose",
          "type": "string",
          "minLength": 1,
          "maxLength": 35,
          "description": "Specify the high-level purpose of the mandate. For Australia This parameter is not allowed to amend."
        },
        "payment_amount_type": {
          "title": "payment_amount_type",
          "type": "string",
          "enum": [
            "FIXE",
            "USGB",
            "VARI",
            "BALN"
          ],
          "description": "Specify the mandate payment arrangement.<br>FIXE -Fixed Direct debit amount is fixed.<br>USGB -Usage Based Direct debit amount is based on usage.<br>VARI -Variable Direct debit amount is variable <br> BALN- Balloon Payment. For Australia this parameter is allowed to amend bilaterally."
        },
        "debtor_reference_number": {
          "title": "debtor_reference_number",
          "type": "string",
          "minLength": 1,
          "maxLength": 35,
          "description": "Specify the unique and unambiguous identification as assigned by the creditor to the referred document shared with the debtor for its own reference. For Australia, this parameter is not allowed to amend."
        },
        "debtor_code": {
          "title": "debtor_code",
          "type": "string",
          "minLength": 1,
          "maxLength": 35,
          "description": "Specify the Proprietary identification of the type of the remittance document. For Australia, this parameter is not allowed to amend."
        },
        "creditor_reference_number": {
          "title": "creditor_reference_number",
          "type": "string",
          "minLength": 1,
          "maxLength": 35,
          "description": "Specify the unique and unambiguous identification as assigned by the debtor to the referred document shared with the creditor for its own reference. For Australia, this parameter is allowed to amend unilaterally."
        },
        "payment_reference_number": {
          "title": "payment_reference_number",
          "type": "string",
          "minLength": 1,
          "maxLength": 35,
          "description": "Specify the proprietary identification of the type of the remittance document. This parameter is not applicable to Australia."
        },
        "currency": {
          "title": "currency",
          "type": "string",
          "pattern": "^[A-Z]{3}$",
          "description": "Specify the collection account currency. For Australia, this parameter is not allowed to amend."
        },
        "amount": {
          "title": "amount",
          "type": "number",
          "description": "Specify the Fixed amount to be collected from the debtor’s account. For Australia if payment_amount_type parameter is equal to FIXE then this parameter is mandatory. For Australia, this parameter is allowed to amend bilaterally."
        },
        "maximum_amount": {
          "title": "maximum_amount",
          "type": "number",
          "description": "Specify the Maximum amount to be collected from the debtors account, per instruction. For Australia, this parameter is allowed to amend bilaterally."
        },
        "first_collection_amount": {
          "title": "first_collection_amount",
          "type": "number",
          "description": "Specify the first collection amount to be collected from the debtors account. For Australia this parameter is allowed to amend bilaterally."
        },
        "final_collection_amount": {
          "title": "final_collection_amount",
          "type": "number",
          "description": "Specify the final collection amount to be collected from the debtors account. For Australia this parameter is allowed to amend bilaterally."
        },
        "cummulative_amount": {
          "title": "cummulative_amount",
          "type": "number",
          "description": "Specify the cumulative fixed amount to be collected from the debtors account. This parameter is not applicable to Australia."
        }
      }
    },
    "AmendmentUltimate": {
      "title": "AmendmentUltimate",
      "type": "object",
      "properties": {
        "ultimate_creditor_name": {
          "title": "ultimate_creditor_name",
          "type": "string",
          "minLength": 1,
          "maxLength": 35,
          "description": "Specify the name by which the ultimate creditor is known and which is used to identify that party. For Australia, this parameter is allowed to amend unilaterally."
        }
      }
    }
  }
}