{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://raw.githubusercontent.com/api-evangelist/citi/main/json-schema/citi-card-maintenance-request-schema.json",
"title": "CardMaintenanceRequest",
"x-generated": "2026-10-12",
"x-method": "derived",
"x-generator": "derive-json-schema.py",
"x-source": "openapi/citi-mvca-api-openapi.yml#/components/schemas/CardMaintenanceRequest",
"properties": {
"requestType": {
"description": "Action which would help to define the processing flow",
"type": "string",
"items": {
"enum": [
"CARD_MODIFY",
"CARD_CANCEL",
"DEMOGRAPHIC_UPDATE"
]
},
"format": "alpha[a-zA-Z]"
},
"cardHolderUserId": {
"description": "Unique ID to be generated & sent by Citi clients to identify user profile.",
"type": "string",
"format": "alphanumeric [a-zA-Z0-9//s]",
"maxLength": 20,
"minLength": 1
},
"countryOfIssuance": {
"description": "Country based on which the santions screening rules are applied.",
"type": "string",
"format": "alphabets [a-zA-Z]",
"maxLength": 3,
"minLength": 2
},
"modifyCardInfo": {
"description": "This object should be populated when requestType is CARD_MODIFY",
"type": "object",
"format": "object",
"$ref": "#/$defs/ModifyCardRequest"
},
"cancelCardInfo": {
"description": "This object should be populated when requestType is CARD_CANCEL",
"type": "object",
"format": "object",
"$ref": "#/$defs/CancelCardRequest"
},
"demographicInfo": {
"description": "This object should be populated when requestType is DEMOGRAPHIC_UPDATE",
"type": "object",
"format": "object",
"$ref": "#/$defs/DemographicUpdateInfo"
}
},
"required": [
"requestType",
"cardHolderUserId",
"countryOfIssuance"
],
"$defs": {
"CancelCardRequest": {
"properties": {
"vcaRequestId": {
"description": "unique id assigned to each virtual card",
"type": "string",
"format": "numeric [0-9]",
"maxLength": 20
},
"vcaGuid": {
"description": "Unique Id to refer Virtual Card Account.",
"type": "integer",
"format": "int64",
"maxLength": 19
},
"vcaRequestor": {
"type": "object",
"$ref": "#/$defs/VcaRequestor"
},
"vcaUser": {
"type": "object",
"$ref": "#/$defs/VcaUser"
}
},
"required": [
"vcaRequestId",
"vcaGuid"
]
},
"CurfewTime": {
"properties": {
"startTime": {
"description": "Specifies the start time from when the card can be used each of the specified days.",
"type": "string",
"format": "HH:MM 24-hour format (^[0-9]{1,2}:[0-9]{2}:[0-9]{2})",
"maxLength": 5
},
"endTime": {
"description": "Specifies the end time until which the card can be used each of the specified days.",
"type": "string",
"format": "HH:MM 24-hour format (^[0-9]{1,2}:[0-9]{2}:[0-9]{2})",
"maxLength": 5
},
"weekdayEffective": {
"description": "Listing of days to which the time curfew applies.",
"type": "array",
"items": {
"type": "string"
},
"format": "[a-zA-Z]{3}"
}
},
"required": [
"startTime",
"endTime",
"weekdayEffective"
]
},
"CustomReference": {
"properties": {
"customReferenceLabel": {
"description": "Specifies the label of a custom reference field.",
"type": "string",
"format": "alphanumeric [a-zA-Z0-9]",
"maxLength": 50,
"minLength": 1
},
"customReferenceValue": {
"description": "Specifies the value of a custom reference field. If the template used for this VCA request identifies a given custom reference field as required, then the value provided in this field cannot be blank.",
"type": "string",
"format": "alphanumeric [a-zA-Z0-9]",
"maxLength": 80,
"minLength": 1
}
}
},
"DemographicUpdateInfo": {
"required": [
"firstName",
"lastName",
"city",
"country",
"zip",
"state",
"addressLine1",
"dateOfBirth",
"provinceOfBirth",
"countryOfBirth"
],
"properties": {
"firstName": {
"description": "First name of the cardholder",
"type": "string",
"format": "alphabets [a-zA-Z]",
"maxLength": 140
},
"middleName": {
"description": "Middle name of the cardholder",
"type": "string",
"format": "alphabets [a-zA-Z]",
"maxLength": 140
},
"lastName": {
"description": "Last name of the cardholder",
"type": "string",
"format": "alphabets [a-zA-Z]",
"maxLength": 140
},
"emailId": {
"description": "Email address of the cardholder",
"type": "string",
"format": "alphabets [a-zA-Z]",
"maxLength": 240
},
"mobileNumber": {
"description": "Mobile number of the cardholder",
"type": "string",
"format": "[0-9]",
"minLength": 5,
"maxLength": 13
},
"mobileCountryCode": {
"description": "Mobile country code of the cardholder. It should start with +, minimum length is 1 numeric digit and maximum is 3 numeric digit excluding +.",
"type": "string",
"format": "+[0-9]",
"minLength": 3,
"maxLength": 4
},
"city": {
"description": "City of the cardholder",
"type": "string",
"format": "alphanumeric",
"maxLength": 50,
"minLength": 1
},
"state": {
"description": "State of the cardholder",
"type": "string",
"format": "alphanumeric",
"maxLength": 50,
"minLength": 1
},
"country": {
"description": "Country of the cardholder",
"type": "string",
"format": "alphanumeric",
"maxLength": 50,
"minLength": 1
},
"zip": {
"description": "Postal code of the cardholder",
"type": "string",
"format": "alphanumeric",
"maxLength": 13,
"minLength": 1
},
"addressLine1": {
"description": "Address Line1 of the cardholder",
"type": "string",
"format": "alphanumeric",
"maxLength": 100,
"minLength": 1
},
"addressLine2": {
"description": "Address Line2 of the cardholder",
"type": "string",
"format": "alphanumeric",
"maxLength": 100,
"minLength": 1
},
"addressLine3": {
"description": "Address Line3 of the cardholder",
"type": "string",
"format": "alphanumeric",
"maxLength": 100,
"minLength": 1
},
"dateOfBirth": {
"description": "Date of birth of the cardholder",
"type": "string",
"format": "alphanumeric",
"maxLength": 50,
"minLength": 1
},
"provinceOfBirth": {
"description": "Province of birth of the cardholder",
"type": "string",
"format": "alphanumeric",
"maxLength": 50,
"minLength": 1
},
"countryOfBirth": {
"description": "Country of birth of the cardholder",
"type": "string",
"format": "alphanumeric",
"maxLength": 50,
"minLength": 1
},
"documents": {
"type": "array",
"items": {
"$ref": "#/$defs/Documents"
}
},
"nationalities": {
"type": "array",
"items": {
"$ref": "#/$defs/Nationalities"
}
}
}
},
"Documents": {
"properties": {
"documentType": {
"description": "Type of the document likeSSN, TIN, SSS, GSIS, Passport, IC, Local ID Number, PAN, Cadastro de Pessoas F�sicas (CPF), Registro Federal de Contribuyentes (RFC), Permanent ID, DNI",
"type": "string",
"format": "alphabets [a-zA-Z]",
"maxLength": 10
},
"documentValue": {
"description": "Document Value",
"type": "string",
"format": "alphabets [a-zA-Z0-9]",
"maxLength": 50
},
"country": {
"description": "Country of the document",
"type": "string",
"format": "alphabets [a-zA-Z]",
"maxLength": 10
}
},
"required": [
"documentValue"
]
},
"ModifyCardRequest": {
"required": [
"vcaGuid",
"programId",
"vcaRequestId",
"vcaRequestor",
"vcaUser"
],
"properties": {
"vcaGuid": {
"description": "Unique Id to refer Virtual Card Account.",
"type": "integer",
"format": "int64",
"maxLength": 19,
"minLength": 1
},
"programId": {
"description": "Unique ID of the company record defined in the virtual cards system.",
"type": "string",
"format": "numeric [0-9]",
"maxLength": 19,
"minLength": 1
},
"vcaRequestId": {
"description": "Unique reference Id generated by Citi for MASTER network.",
"type": "string",
"format": "alphanumeric [a-zA-Z0-9-]",
"maxLength": 20
},
"programName": {
"description": "Company Name as defined in Virtual Card System.",
"type": "string",
"format": "alphanumeric [a-zA-Z0-9] + special character",
"maxLength": 250,
"minLength": 1
},
"fundingSourceId": {
"description": "Unique identifier of the funding source to which the virtual card rolls up. It's numeric for MASTER & alphanumeric for VISA.",
"type": "string",
"format": "alphanumeric [a-zA-Z0-9//s]",
"maxLength": 19
},
"fundingSourceName": {
"description": "Descriptive name of the real card to which the virtual card rolls up. Apllicable only for MASTER.",
"type": "string",
"format": "alphanumeric [a-zA-Z0-9]",
"maxLength": 100
},
"expiryDate": {
"description": "Expiry Date of the virtual card account. Must not be more than 24 months in the future. If a modification of this parameter is not needed, the field can be left out of the modification request call. Citi will then apply the most recently defined value for this field. Data type has been kept has String instead of Number due to prceeding 0 may get truncated. Applicable only for MASTER.",
"type": "string",
"format": "MMYYYY ([0-9]{6})",
"maxLength": 6
},
"mccGrouping": {
"description": "Limits authorizations to defined Merchant Category Codes. Must be the Purchase Type name associated to the template.",
"type": "array",
"items": {
"type": "string"
},
"format": "alphabets [a-zA-Z]"
},
"currencyCode": {
"description": "Currency Code in which VCA amounts are expressed. currencyCode is not required if currencyType = B",
"type": "string",
"format": "numeric [0-9]",
"maxLength": 3
},
"currencyType": {
"description": "Defines the type of the VCA currency. - Value B stands for Billing Currency which indicates that the VCA currency is equal to the billing currency of the underlying funding source. - Value M stands for Merchant Currency which indicates that the VCA currency is expressed in merchant currency and not in billing currency. Mandatory for Mastercard",
"type": "string",
"format": "B/M",
"enum": [
"B",
"M"
]
},
"timeZone": {
"description": "Defines the time zone applicable for any date or time parameters within controls set for a VCA.If any of the following controls are used, timeZone is required:Validity Period Control,Aging Velocity Control (Mastercard only), Curfew Control and Time of Day Control.It sets the specific timeframe when the account and its controls will become active.",
"type": "string",
"format": "UTC-OFFSET (UTC-[0-9]{2}:[0-9]{2})",
"maxLength": 9
},
"templateId": {
"description": "Identifies the template that was setup in the VCA system and that should be used for this virtual card. The template setup in the VCA system defines which controls, custom data fields and MCC groupings can be used. Mandatory for Mastercard",
"type": "integer",
"format": "int64",
"maximum": 19
},
"getCardImage": {
"description": "A visual representation of the virtual card account front and back.",
"type": "boolean",
"format": "boolean"
},
"customReference": {
"description": "Up to 29 custom reference field lables and values can be defined in a given request. A custom reference value cannot be sent without a corresponding custom reference label.",
"type": "array",
"items": {
"$ref": "#/$defs/CustomReference"
}
},
"modifySpendVelocityControl": {
"description": "Limits the frequency and total cumulative amount of authorizations performed on the VCA within a specified period. The control is mandatory unless Aging Velcotiy Control is used. This control cannot be used in combination with the Aging Velocity Control.",
"type": "boolean",
"format": "boolean"
},
"spendVelocity": {
"type": "array",
"items": {
"$ref": "#/$defs/SpendVelocityRequest"
}
},
"modifyValidityPeriodControl": {
"description": "Limits authorization activity to a specific time period. This is an optional control. If this control is not used, pass False or leave this section out from the request. If value passed as True, validityStartDate and validityEndDate are required.",
"type": "boolean",
"format": "boolean"
},
"validityStartDate": {
"description": "Identifies the date from which the virtual card account can be used for transactions. The Start Date must be prior to the End Date. Mandatory if enableValidityPeriodControl is true. Mandatory for MASTER, optional for VISA.",
"type": "string",
"format": "ISO 8601: YYYY-MM-DD (^(19|20)[0-9]{2}-(((0[13578]|(10|12))-(0[1-9]|[1-2][0-9]|3[0-1]))|(02-(0[1-9]|[1-2][0-9]))|((0[469]|11)-(0[1-9]|[1-2][0-9]|30))))",
"maxLength": 10
},
"validityEndDate": {
"description": "Identifies the date until which the virtual card account can be used for transactions. The Start Date must be prior to the End Date. Mandatory if enableValidityPeriodControl is true",
"type": "string",
"format": "ISO 8601: YYYY-MM-DD (^(19|20)[0-9]{2}-(((0[13578]|(10|12))-(0[1-9]|[1-2][0-9]|3[0-1]))|(02-(0[1-9]|[1-2][0-9]))|((0[469]|11)-(0[1-9]|[1-2][0-9]|30))))",
"maxLength": 10
},
"modifyAmountRangeControl": {
"description": "Approves a transaction only if the requested amount for authorization is equal to or greater than the Minimum Amount and less than or equal to the Maximum Amount. This is an optional control. If this control is not used, pass False or leave this section out from the request. If value passed is True, maxAmount and minAmount are required.",
"type": "boolean",
"format": "boolean"
},
"maxAmount": {
"description": "For MASTER: Identifies the maximum allowed transaction amount. 14 digits max to the left of decimal and 2 digits max to the right of the decimal. For VISA: Identifies the maximum allowed transaction amount. 12 digits max to the left of decimal and 2 digits max to the right of the decimal. Mandatory if enableAmountRangeControl is true ",
"type": "number",
"format": "[0-9]{17}$|(?=^.{1,18}$)^[0-9]+\\.[0-9]{1,4}",
"maximum": 15
},
"minAmount": {
"description": "For MASTER: Identifies the minimum allowed transaction amount. 14 digits max to the left of decimal and 2 digits max to the right of the decimal. For VISA: Identifies the maximum allowed transaction amount. 12 digits max to the left of decimal and 2 digits max to the right of the decimal. Mandatory if enableAmountRangeControl is true ",
"type": "number",
"format": "[0-9]{17}$|(?=^.{1,18}$)^[0-9]+\\.[0-9]{1,4}",
"maximum": 15
},
"modifyTransactionLimitControl": {
"description": "Limits individual transactions to a maximum amount. This is an optional control. If this control is not used, pass False or leave this section out from the request. If value passed is True, amountLimit is required.",
"type": "boolean",
"format": "boolean"
},
"amountLimit": {
"description": "Identifies the maximum allowed transaction amount. Mandatory if enableTransactionLimitControl is true",
"type": "number",
"format": "[0-9]{17}$|(?=^.{1,18}$)^[0-9]+\\.[0-9]{1,4}",
"maximum": 15
},
"modifyCurfewControl": {
"description": "Limits authorization activity to a single time period for each day selected. This is an optional control. If this control is not used, pass False or leave this section out from the request. If value passed is True, curfewTime is required. Applicable only for MASTER.",
"type": "boolean",
"format": "boolean"
},
"curfewTime": {
"type": "object",
"format": "object",
"$ref": "#/$defs/CurfewTime"
},
"modifyTimeOfDayControl": {
"description": "Limits authorization request to defined time periods each day. This is an optional control. If this control is not used, pass False or leave this section out from the request. If value passed is True, timeOfDay is required.",
"type": "boolean",
"format": "boolean"
},
"timeOfDay": {
"type": "array",
"items": {
"$ref": "#/$defs/TimeOfDay"
}
},
"modifyAgingVelocityControl": {
"description": "Sets a cumulative amount and keeps track of the current remaining balance. Allows the requester to \"age off\" approved authorization requests that have not been cleared by the merchant after a defined number of days. This is an optional control. If this control is not used, pass False or leave this section out from the request. If value passed is True, authorizationHoldDays and cumulativeSpendLimit are required.",
"type": "boolean",
"format": "boolean"
},
"authorizationHoldDays": {
"description": "Identifies the number of days after which an authorization gets aged off if no matching clearing record was received. Mandatory if enableAgingVelocityControl is true. Applicable only for MASTER.",
"type": "number",
"format": "numeric [0-9]",
"maximum": 19
},
"cumulativeSpendLimit": {
"description": "Limits the overall amount spend on the virtual card account. Setting the this value to 0 will be interpreted as an open limit. In this case, the underlying funding accounts available balance will drive the authorization decision to approve or decline a transaction. Mandatory if enableAgingVelocityControl is true",
"type": "number",
"format": "[0-9]{17}$|(?=^.{1,18}$)^[0-9]+\\.[0-9]{1,4}",
"maximum": 15
},
"modifyGeographyControl": {
"description": "Limits authorization requests to a defined geographic location. This is an optional control. If this control is not used, pass False or leave this section out from the request. For Mastercard, if value passed is True, countryCodes and isCountryAllowed are required.",
"type": "boolean",
"format": "boolean"
},
"countryCodes": {
"type": "array",
"items": {
"type": "string"
},
"format": "alphabets [a-zA-Z]",
"maximum": 3
},
"isCountryallowed": {
"description": "Indicate whether the values in countryCode are allowed or disallowed. True= values provided in countryCode are allowed. False = values provided in countryCode are not allowed. ",
"type": "boolean",
"format": "boolean"
},
"modifyMerchantIdControl": {
"description": "Limits authorizations to a particular merchant using the Merchant ID and Acquirer ID (Mastercard) or Card Acceptor ID (Visa).",
"type": "boolean",
"format": "boolean"
},
"isMerchantIdAllowed": {
"description": "Indicate whether the values in merchantId and acquirerId are allowed or disallowed. True = values provided in merchantId and acquirerId are allowed False = values provided in merchantId and acquirerId are not allowed",
"type": "boolean",
"format": "boolean"
},
"cardAcceptorId": {
"description": "Specifies the Card Acceptor ID that should be allowed / disallowed when transacting with the virtual card. Only applicable for VISA.",
"type": "string",
"format": "alphanumeric [a-zA-Z0-9//s]",
"maxLength": 15
},
"vcaRequestor": {
"type": "object",
"$ref": "#/$defs/VcaRequestor"
},
"vcaUser": {
"type": "object",
"$ref": "#/$defs/VcaUser"
}
}
},
"Nationalities": {
"properties": {
"country": {
"description": "Country",
"type": "string",
"format": "alphanumeric [a-zA-Z0-9]",
"maxLength": 10
}
},
"required": [
"country"
]
},
"SpendVelocityRequest": {
"properties": {
"maxAuth": {
"description": "Limits the number of authorizations that can be made with a VCA. Should be set to 1, if a single-use VCA is created. Specify any value larger than one for a multi-use VCA. If a modification of this parameter is not needed, the field can be left out of the modification request call. Citi will then apply the most recently defined value for this field. Set to 0, if unlimited authorizations should be allowed. For MASTER: 8, VISA: 10",
"type": "number",
"format": "numeric [0-9]",
"maximum": 10
},
"cumulativeSpendLimit": {
"description": "Limits the overall amount spend on the virtual card account. If a modification of this parameter is not needed, the field can be left out of the modification request call. Citi will then apply the most recently defined value for this field.",
"type": "number",
"format": "[0-9]{17}$|(?=^.{1,18}$)^[0-9]+\\.[0-9]{1,4}",
"maximum": 15
},
"periodType": {
"description": "Period for which the control values are valid before they reset.
If a modification of this parameter is not needed, the field can be left out of the modification request call. Citi will then apply the most recently defined value for this field. Mastercard: D = Daily -- The balances of control parameters enabled for a VCA are reset with their original values every day at 00:00:00. M = Monthly -- The balances of control parameters enabled for a VCA are reset with their original values at the start of every month. W = Weekly -- The balances of control parameters enabled for a VCA are reset with their original values every Monday at 00:00:00. Q = Quarterly -- The balances of control parameters enabled for a VCA are reset with their original values on the first day of every quarter at 00:00:00. Quarter 1: January 01 - March 31. Quarter 2: April 01 - June 30. Quarter 3: July 01 - September 30. Quarter 4: October 01 - December 31. Y = Annually -- The balances of control parameters enabled for a VCA are reset with their original values every year on January 1st at 00:00:00. C = Continuous -- The balances of control parameters enabled for a VCA are retained continuously for the validity period defined. Balances do not reset with their original values throughout the validity period. Visa: 1 = Recurring : The balances of control parameters enabled for a VCA are reset with their original values on a specified recurring day for every month.
If you select this periodType, you must also specify the resetDay field. 2 = Monthly : The balances of control parameters enabled for a VCA are reset with their original values at the start of every month. 3 = Date Range : The balances of control parameters enabled for a VCA are retained continuously for the validity period defined. Balances do not reset with their original values throughout the validity period.
If you select this periodType, you must also specify the validityStartDate and validityEndDate fields.",
"type": "string",
"format": "alphanumeric [a-zA-Z0-9]",
"maxLength": 1
}
},
"required": [
"maxAuth",
"cumulativeSpendLimit",
"periodType"
]
},
"TimeOfDay": {
"properties": {
"startTime": {
"description": "Specifies the start time from when the card can be used each of the specified days.",
"type": "string",
"format": "HH:MM 24-hour format (^[0-9]{1,2}:[0-9]{2}:[0-9]{2})",
"maxLength": 5
},
"endTime": {
"description": "Specifies the end time until which the virtual card account can be used on the particular day specified in weekDaysEffective.",
"type": "string",
"format": "HH:MM 24-hour format (^[0-9]{1,2}:[0-9]{2}:[0-9]{2})",
"maxLength": 5
},
"weekdayEffective": {
"description": "Specifies the day applicable to the start and end times defined.",
"type": "string",
"format": "alphabets [a-zA-Z]",
"maxLength": 3
}
},
"required": [
"startTime",
"endTime",
"weekdayEffective"
]
},
"VcaRequestor": {
"properties": {
"requestorType": {
"description": "Defines whether VCA requestor type. Possible values are INDIVIDUAL, ORG",
"type": "string",
"format": "alphabets [a-zA-Z]",
"maxLength": 20
},
"firstName": {
"description": "Last name of Virtual Card requestor. Applicable only for requestorType: INDIVIDUAL",
"type": "string",
"format": "alphabets [a-zA-Z]",
"maxLength": 140
},
"middleName": {
"description": "Middle name of Virtual Card requestor. Applicable only for requestorType: INDIVIDUAL",
"type": "string",
"format": "alphabets [a-zA-Z]",
"maxLength": 140
},
"lastName": {
"description": "Last name of Virtual Card requestor. Applicable only for requestorType: INDIVIDUAL",
"type": "string",
"format": "alphabets [a-zA-Z]",
"maxLength": 140
},
"id": {
"description": "Unique ID of Virtual Card requestor. Applicable for requestorType as INDIVIDUAL & ORG.",
"type": "string",
"format": "numeric [0-9]",
"maxLength": 200,
"minLength": 6
},
"orgName": {
"description": "Organization name of Virtual Card requestor. Applicable only for requestorType: ORG",
"type": "string",
"format": "alphabets [a-zA-Z]",
"maxLength": 140
}
},
"required": [
"requestorType",
"firstName",
"middleName",
"lastName",
"id",
"orgName"
]
},
"VcaUser": {
"properties": {
"emailId": {
"description": "Email Id of the card holder/user",
"type": "string",
"format": "alphabets [a-zA-Z]",
"maxLength": 240
},
"mobileNumber": {
"description": "Mobile number the card holder/user",
"type": "string",
"format": "numeric [0-9]",
"minLength": 5,
"maxLength": 13
},
"mobileCountryCode": {
"description": "Mobile number country code of the card holder/user",
"type": "string",
"format": "^(\\+[0-9]+)",
"minLength": 2,
"maxLength": 4
}
},
"required": [
"emailId",
"mobileNumber",
"mobileCountryCode"
]
}
}
}