{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/citi/main/json-schema/citi-create-virtual-card-request-schema.json",
  "title": "CreateVirtualCardRequest",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/citi-create-api-openapi.yml#/components/schemas/CreateVirtualCardRequest",
  "type": "object",
  "properties": {
    "vcaId": {
      "type": "number",
      "description": "A reference number that uniquely identifies the virtual card account. "
    },
    "fundingSourceId": {
      "type": "string",
      "description": "Unique identifier of the funding source to which the virtual card rolls up"
    },
    "fundingSourceName": {
      "type": "string",
      "description": "Descriptive name of the real card to which the virtual card rolls up"
    },
    "programId": {
      "type": "string",
      "description": "Unique ID of the company record defined in the virtual cards system"
    },
    "messageId": {
      "type": "string",
      "description": "Unique ID of the API message sent. The messageId will be provided back in the corresponding response. The ID can be used for investigation and troubleshooting. The ID must be unique per integration"
    },
    "mccGrouping": {
      "type": "array",
      "description": "Limits authorizations to defined Merchant Category Codes.",
      "items": {
        "type": "string"
      }
    },
    "getCardImage": {
      "type": "boolean",
      "description": "* Specifies whether cardImage field needs to be included in the response or not.\n\n* True = cardImage field will be sent in the response\n* False = cardImage field will not be sent in the response.\n* `Optional field` if not included, cardImage will be sent in the response."
    },
    "currencyCode": {
      "type": "string",
      "description": "Currency Code in which VCA amounts are expressed"
    },
    "currencyType": {
      "type": "string",
      "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."
    },
    "timeZone": {
      "type": "string",
      "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."
    },
    "paymentBeneficiaryId": {
      "type": "number",
      "description": "Uniquely identifies the payment beneficiary for which the virtual card is created"
    },
    "paymentBeneficiaryEmails": {
      "type": "array",
      "description": "Lists the email addresses to which the virtual card details should be sent to.In order for emails to get delivered, the following two settings must be enabled in the VCA system:1. Allow VCN details to be emailed to this supplier2. Allow VCN requestor to manually enter a new email address when requesting a VCN",
      "items": {
        "type": "string"
      }
    },
    "customReference": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/CustomReference"
      }
    },
    "templateId": {
      "type": "number",
      "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."
    },
    "expiryDate": {
      "type": "string",
      "description": "Expiry Date of the virtual card account. "
    },
    "cumulativeSpendLimit": {
      "type": "number",
      "format": "bigdecimal",
      "description": "Limits the overall amount spend on the virtual card account."
    },
    "enableSpendVelocityControl": {
      "type": "boolean",
      "description": "Limits the frequency and total cumulative amount of authorizations performed on the VCA within a specified period. Mastercard: The control is mandatory unless Aging Velcotiy Control is used. This control cannot be used in combination with the Aging Velocity Control.Visa: Spend Velocity Control is mandatory."
    },
    "spendVelocity": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/SpendVelocityRequest"
      }
    },
    "enableValidityPeriodControl": {
      "type": "boolean",
      "description": "Limits authorization activity to a specific time period. "
    },
    "validityStartDate": {
      "type": "string",
      "description": "Identifies the date from which the virtual card account can be used for transactions."
    },
    "validityEndDate": {
      "type": "string",
      "description": "Identifies the date until which the virtual card account can be used for transactions."
    },
    "enableAmountRangeControl": {
      "type": "boolean",
      "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."
    },
    "maxAmount": {
      "type": "number",
      "format": "bigdecimal",
      "description": "Identifies the maximum allowed transaction amount."
    },
    "minAmount": {
      "type": "number",
      "format": "bigdecimal",
      "description": "Identifies the minimum allowed transaction amount."
    },
    "enableTransactionLimitControl": {
      "type": "boolean",
      "description": "Limits individual transactions to a maximum amount."
    },
    "amountLimit": {
      "type": "number",
      "format": "bigdecimal",
      "description": "Identifies the maximum allowed transaction amount."
    },
    "enableCurfewControl": {
      "type": "boolean",
      "description": "Limits authorization activity to a single time period for each day selected."
    },
    "curfewTime": {
      "$ref": "#/$defs/CurfewTime"
    },
    "enableTimeOfDayControl": {
      "type": "boolean",
      "description": "Limits authorization request to defined time periods each day"
    },
    "timeOfDay": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/TimeOfDay"
      }
    },
    "enableAgingVelocityControl": {
      "type": "boolean",
      "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."
    },
    "authorizationHoldDays": {
      "type": "number",
      "format": "long",
      "description": "Identifies the number of days after which an authorization gets aged off if no matching clearing record was received."
    },
    "enableGeographyControl": {
      "type": "boolean",
      "description": "Limits authorization requests to a defined geographic location."
    },
    "countryCodes": {
      "type": "array",
      "description": "Defines the merchant country in which the VCA can be used.",
      "items": {
        "type": "string"
      }
    },
    "allowed": {
      "type": "boolean",
      "description": "Indicate whether the values in countryCode are allowed or disallowed"
    },
    "enableMerchantIdControl": {
      "type": "boolean",
      "description": "Limits authorizations to a particular merchant using the Merchant ID and Acquirer ID (Mastercard) or Card Acceptor ID (Visa)."
    },
    "merchantId": {
      "$ref": "#/$defs/MerchantIdRequest"
    }
  },
  "$defs": {
    "CurfewTime": {
      "type": "object",
      "properties": {
        "startTime": {
          "type": "string",
          "description": "Specifies the end time until which the virtual card account can be used on the particular day specified in weekDaysEffective."
        },
        "endTime": {
          "type": "string",
          "description": "Specifies the end time until which the virtual card account can be used on the particular day specified in weekDaysEffective."
        },
        "weekdaysEffective": {
          "type": "array",
          "description": "Specifies the day applicable to the start and end times defined.",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "CustomReference": {
      "type": "object",
      "properties": {
        "customReferenceValue": {
          "type": "string",
          "description": "Specifies the label of a custom reference field.Mastercard: All field labels included in the template used for this virtual card account request should be included."
        },
        "customReferenceLabel": {
          "type": "string",
          "description": "Specifies the value of a custom reference field. Mastercard: 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."
        }
      }
    },
    "MerchantIdRequest": {
      "type": "object",
      "properties": {
        "allowed": {
          "type": "boolean",
          "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"
        },
        "cardAcceptorId": {
          "type": "string",
          "description": "Specifies the Card Acceptor ID that should be allowed / disallowed when transacting with the virtual card"
        },
        "merchantId": {
          "type": "string",
          "description": "Specifies the Merchant ID that should be allowed / disallowed when transacting with the virtual card. Must always be provided in combination with a Acquirer ID."
        },
        "acquirerId": {
          "type": "integer",
          "format": "int64",
          "description": "Specifies the Acquirer ID that should be allowed / disallowed when transacting with the virtual card. Must always be provided in combination with a Merchant ID."
        }
      }
    },
    "SpendVelocityRequest": {
      "type": "object",
      "properties": {
        "maxAuth": {
          "type": "number",
          "format": "long",
          "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. Mastercard: Set to 0, if unlimited authorizations should be allowed. (0 is not applicable for Visa)"
        },
        "cumulativeSpendLimit": {
          "type": "number",
          "format": "bigdecimal",
          "description": "Limits the overall amount spend on the virtual card account."
        },
        "periodType": {
          "type": "string",
          "description": "Period for which the control values are valid before they reset"
        }
      }
    },
    "TimeOfDay": {
      "type": "object",
      "properties": {
        "startTime": {
          "type": "string",
          "description": "Specifies the start time from which the virtual card account can be used on the particular day specified in weekDaysEffective."
        },
        "endTime": {
          "type": "string",
          "description": "Specifies the end time until which the virtual card account can be used on the particular day specified in weekDaysEffective."
        },
        "weekdayEffective": {
          "type": "string",
          "description": "Specifies the day applicable to the start and end times defined."
        }
      }
    }
  }
}