{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/citi/main/json-schema/citi-get-vca-details-inbound-response-schema.json",
  "title": "GetVcaDetailsInboundResponse",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/citi-getvcadetails-api-openapi.yml#/components/schemas/GetVcaDetailsInboundResponse",
  "properties": {
    "vcaId": {
      "description": "A reference number that uniquely identifies the virtual card account.",
      "type": "string",
      "format": "long",
      "maxLength": 19
    },
    "virtualCardAccountNumber": {
      "description": "The virtual card account number to use for transactions.",
      "type": "string",
      "format": "alphanumeric",
      "maxLength": 19
    },
    "messageId": {
      "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 request.",
      "type": "string",
      "format": "alphanumeric",
      "maxLength": 36
    },
    "programId": {
      "description": "Unique ID of the company record defined in the virtual cards system.<br><br>Mastercard - This value is returned in the ID Provisioning API. This value is generated when the VCA program is onboarded to Mastercard's VCA platform. Data format - Long (Numeric). Max character length - 19<br><br>Visa - This value is generated when the VCA program is onboarded to Visa's VCA platform. Data format - Alphanumeric. Max character length - 25",
      "type": "string",
      "format": "long",
      "maxLength": 19
    },
    "securityCode": {
      "description": "The security code (i.e. cvv) corresponding to the virtual card accunt.<br><br>Mastercard - Required<br>Visa - Not applicable",
      "type": "string",
      "format": "alphanumeric",
      "maxLength": 3
    },
    "templateId": {
      "description": "Identifies the template that was setup in the VCA system and that should be used for this virtual card.<br><br>The template setup in the VCA system defines which controls, custom data fields and MCC groupings can be used.<br><br>Mastercard - Required<br>Visa - Not applicable",
      "type": "string",
      "format": "long",
      "maxLength": 19
    },
    "requestStatus": {
      "description": "The status of the VCA.<br><br>Mastercard - Required<br>Visa - Not applicable<br><br>Possible values:<br>          - Approved<br>          - Canceled<br>          - Pending Approval<br>          - Declined<br>          - Blocked",
      "type": "string",
      "format": "alphanumeric",
      "maxLength": 16
    },
    "expiryDate": {
      "description": "Expiry Date of the virtual card account. Represented in UTC time zone.<br>`Format:` YYYY-MM",
      "type": "string",
      "format": "alphanumeric",
      "maxLength": 7
    },
    "timeZone": {
      "description": "Defines the time zone applicable for any of the following date or time parameters within controls set for a VCA:\n* Validity Period Control\n* Aging Velocity Control (Mastercard only)\n* Curfew Control\n* Time of Day Control",
      "type": "string",
      "format": "alphanumeric",
      "maxLength": 9
    },
    "currencyCode": {
      "description": "Currency Code in which VCA amounts are expressed.",
      "type": "string",
      "format": "alphanumeric",
      "maxLength": 3
    },
    "currencyType": {
      "description": "Mastercard -  Defines the type of the VCA currency.<br>  <ul><li>Value \"B\" stands for Billing Currency which indicates that the VCA spend limit is expressed in the billing account currency of the underlying funding source. When currencyType = \"B\", then the VCA can be trasacted with a merchant in any currency.</li> <li>Value \"M\" stands for Merchant Currency which indicates that Merchant transactions are limited to the VCA currency provided in the currencyCode field.</li></ul>\n<br>Visa\n- The only valid value is \"M\", which stands for Merchant Currency and indicates that merchant transactions are limited to the VCA currency specified in the currencyCode field. If a currencyType is not provided, then the VCA can be used for any merchant transaction currency.",
      "type": "string",
      "format": "alphanumeric",
      "maxLength": 1
    },
    "paymentBeneficiaryId": {
      "description": "Uniquely identifies the payment beneficiary for which the virtual card is created.<br>Mastercard - Required<br>Visa - Not applicable",
      "type": "string",
      "format": "long",
      "maxLength": 19
    },
    "paymentBeneficiaryEmails": {
      "description": "Lists of up to 5 email addresses separated by semicolon 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:<br>1. Allow VCN details to be emailed to this supplier<br>2. Allow VCN requestor to manually enter a new email address when requesting a VCN<br><br>Mastercard - Optopnal<br>Visa - Not applicable",
      "type": "array",
      "items": {
        "type": "string"
      },
      "format": "alphanumeric"
    },
    "cardImage": {
      "description": "A visual representation of the virtual card account front and back.<br><br>Mastercard - Optional<br>Visa - Not applicable",
      "type": "string",
      "format": "alphanumeric"
    },
    "mccGrouping": {
      "description": "Limits authorizations to defined Merchant Category Codes. Cannot be used in conjunction with the mccRange field<br/><br/>Mastercard - This the name of the Purchase Type that's been configured on the Purchase Template on Mastercard's VCA platform. The Purchase Type value is returned in the Purchase Template Details API<br/><br/>Visa - pass a list of MCCGs defined by Visa to allow or block VCA transactions for the specified MCCGs.<br/><br/>Visa Possible values:<br/><br/>\"ATM\" - Block ATM cash withdrawals.<br/><br/>\"ECOM\" - Block all Internet-based transactions.<br/><br/>\"CNP\" - Block all transactions made over the Internet, phone or mail order.<br/><br/>\"NOC\" - Block all other cash access. This includes non-ATM transactions such as cash advances and purchase with cashback.<br/><br/>\"ADT\" - Block purchases at adult-themed merchants.<br/><br/>\"FUEL\" - Block purchases conducted at fuel/driver merchants (including gas stations, car washes, parking lots and tolls).<br/><br/>\"HOT\" - All purchases made at hotel merchants will be declined.<br/><br/>\"AUTO\" - All purchases made at auto-rental merchants will be declined.<br/><br/>\"AIR\" - All purchases made at airline merchants will be declined.<br/><br/>\"REST\"- All purchases made at restaurants will be declined.<br/><br/>\"JEWL\"- All purchases made at jewelry store locations will be declined<br/><br/>\"ELEC\" - All purchases conducted at electronics themed-merchants will be declined.<br/><br/>\"ALC\" - All purchases conducted at alcohol and tobacco merchants will be declined.<br/><br/>\"GTM\" - All purchases conducted at ground transportation merchants will be declined (includes taxis, trains, and bridge tolls).<br/><br/>\"OSS\" - All purchases conducted at office supply merchants will be declined.<br/><br/>\"GROC\" - All purchases conducted at grocery store and pharmacy merchants will be declined.<br/><br/>\"ENT\" - All purchases conducted at entertainment and sports merchants will be declined (includes movie theaters, music stores and sporting goods stores).<br/><br/>\"UTIL\" - All purchases conducted at utilities will be declined (includes cable, phone and electric companies).<br/><br/>\"CLOTH\" - All purchases conducted at clothing and general retail merchants will be declined (includes department stores, shoe stores and book stores).<br/><br/>\"MED\" - All purchases made at medical merchants will be declined.",
      "type": "array",
      "items": {
        "type": "string"
      },
      "format": "alphanumeric"
    },
    "mccgAllowed": {
      "description": "Returned if the mccGrouping field is populated or if the mccRange field is populated.<br>Specifies whether the  mccGrouping are allowed or disallowed.<br>If true is passed, the mccGrouping or mccRange is allowed.<br>If false is passed, then the mccGrouping or mccRange is disallowed.<br>Mastercard - Not applicable<br>Visa - Optional",
      "type": "string",
      "format": "boolean"
    },
    "mccRange": {
      "description": "Limits authorizations to a defined range of Merchant Category Codes.(eg: [0001-9999, 2000-2999]). Cannot be used in conjunction with the mccGrouping field<br>Mastercard - Not Applicable<br>Visa - Optional",
      "type": "array",
      "items": {
        "type": "string"
      },
      "format": "alphanumeric"
    },
    "cumulativeSpendLimit": {
      "description": "Limits the overall amount that can be spent on the virtual card account. This field is associated to the Aging Velocity Control<br>Mastercard - Optional. Max character length - 14 digits (12 digits to the left of the decimal and 2 digits to the right of the decimal)<br>Visa - Not applicable",
      "type": "string",
      "format": "BigDecimal",
      "maxLength": 14
    },
    "authorizationHoldDays": {
      "description": "Identifies the number of days after which an authorization gets aged off if no matching clearing record was received. This field is associated to the Aging Velocity Control<br>Mastercard - Optional<br>Visa - Not applicable",
      "type": "string",
      "format": "long",
      "maxLength": 19
    },
    "availableBalance": {
      "description": "Specifies the remaining balance available to spend on the virtual card. In response to a VCA creation API request, this value will typically be equal to the cumulativeSpendLimit since no transactions were made on the card yet. This field is associated to the Aging Velocity Control<br>Mastercard - Optional<br>Visa - Not applicable",
      "type": "string",
      "format": "BigDecimal"
    },
    "spendVelocity": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/SpendVelocity"
      }
    },
    "amountLimit": {
      "description": "Identifies the maximum allowed transaction amount, associated to the transaction limit control.",
      "type": "string",
      "format": "BigDecimal",
      "maxLength": 14
    },
    "minAmount": {
      "description": "Identifies the minimum allowed transaction amount, associated to the amount range control.",
      "type": "string",
      "format": "BigDecimal",
      "maxLength": 14
    },
    "maxAmount": {
      "description": "Identifies the maximum allowed transaction amount, associated to the amount range control.",
      "type": "string",
      "format": "BigDecimal",
      "maxLength": 14
    },
    "validityStartDate": {
      "description": "Identifies the date from which the virtual card account can be used for transactions. <br>The Start Date must be prior to the End Date.<br>`Format:` YYYY-MM-DD",
      "type": "string",
      "format": "alphanumeric",
      "maxLength": 10
    },
    "validityEndDate": {
      "description": "Identifies the date until which the virtual card account can be used for transactions. <br>The Start Date must be prior to the End Date.<br>`Format:` YYYY-MM-DD",
      "type": "string",
      "format": "alphanumeric",
      "maxLength": 10
    },
    "curfewTime": {
      "$ref": "#/$defs/CurfewTime"
    },
    "timeOfDay": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/TimeOfDay"
      }
    },
    "countryCodes": {
      "description": "Defines the merchant country in which the VCA can or cannot be used.",
      "type": "array",
      "items": {
        "type": "string"
      },
      "format": "alphanumeric"
    },
    "allowed": {
      "description": "Indicate whether the values in countryCode are allowed or disallowed.<br>True = values provided in countryCode are allowed<br>False = values provided in countryCode are not allowed",
      "type": "string",
      "format": "boolean"
    },
    "merchantInfo": {
      "$ref": "#/$defs/MerchantInfo"
    },
    "customReference": {
      "description": "Array of custom refernce lable & value pairs",
      "type": "array",
      "items": {
        "$ref": "#/$defs/CustomReference"
      }
    }
  },
  "required": [
    "vcaId",
    "virtualCardAccountNumber",
    "messageId",
    "programId",
    "expiryDate",
    "timeZone"
  ],
  "$defs": {
    "CurfewTime": {
      "properties": {
        "startTime": {
          "description": "Specifies the start time from when the card can be used each of the specified days.<br><br>Mastercard - Optional<br>Visa - Not applicaable<br><br>`Format:` hh:mm",
          "type": "string",
          "format": "alphanumeric",
          "maxLength": 5
        },
        "endTime": {
          "description": "Specifies the end time until which the card can be used each of the specified days.<br><br>Mastercard - Optional<br>Visa - Not applicaable<br><br>`Format:` hh:mm",
          "type": "string",
          "format": "alphanumeric",
          "maxLength": 5
        },
        "weekdaysEffective": {
          "description": "Listing of days to which the time curfew applies.<br><br>Mastercard - Optional<br>Visa - Not applicaable<br><br>Possible Values:<br><br>MON<br>TUE<br>WED<br>THU<br>FRI<br>SAT<br>SUN<br>",
          "type": "array",
          "items": {
            "type": "string"
          },
          "format": "alphanumeric"
        }
      }
    },
    "CustomReference": {
      "properties": {
        "customReferenceLabel": {
          "description": "Specifies the label of a custom reference field.",
          "type": "string",
          "format": "alphanumeric",
          "maxLength": 50
        },
        "customReferenceValue": {
          "description": "Specifies the value of a custom reference field.<br><br>Mastercard - Max Length - 80 characters<br>Visa - Max Length - 100 characters'",
          "type": "string",
          "format": "alphanumeric",
          "maxLength": 100
        }
      }
    },
    "MerchantId": {
      "properties": {
        "merchantId": {
          "description": "Specifies the Merchant ID that should be allowed / disallowed when transacting with the virtual card.<br>Mastercard - Optional<br>Visa - Not applicable",
          "type": "string",
          "format": "alphanumeric",
          "maxLength": 15
        },
        "acquirerId": {
          "description": "Specifies the Acquirer ID that should be allowed / disallowed when transacting with the virtual card. <br>Mastercard - Optional<br>Visa - Optional",
          "type": "string",
          "format": "long",
          "maxLength": 6
        },
        "cardAcceptorId": {
          "description": "Specifies the Card Acceptor ID that should be allowed / disallowed when transacting with the virtual card. <br>Mastercard - Not applicable<br>Visa - Optional",
          "type": "string",
          "format": "alphanumeric",
          "maxLength": 15
        }
      }
    },
    "MerchantInfo": {
      "properties": {
        "allowed": {
          "description": "Indicate whether the values in merchantId and acquirerId are allowed or disallowed.<br> True = values provided in merchantId and acquirerId are allowed<br> False = values provided in merchantId and acquirerId are not allowed",
          "type": "string",
          "format": "boolean"
        },
        "merchantIds": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/MerchantId"
          }
        }
      }
    },
    "SpendVelocity": {
      "properties": {
        "cumulativeSpendLimit": {
          "description": "Limits the overall amount that can be spent on the virtual card account.<br>Mastercard - Allows a maximumm of 14 digits (12 digits to the left of the decimal and 2 digits to the right of the decimal)<br>Visa - Allows a maximumm of 12 digits (10 digits to the left of the decimal and 2 digits to the right of the decimal)",
          "type": "string",
          "format": "BigDecimal",
          "maxLength": 14
        },
        "maxAuth": {
          "description": "Limits the number of authorizations that can be made with a VCA. Mastercard: If set to 0, unlimited authorizations are allowed on the VCA. (0 is not applicable for Visa)",
          "type": "string",
          "format": "long",
          "maxLength": 19
        },
        "periodType": {
          "description": "Period for which the control values are valid before they reset.<br><br>Mastercard: <br>D = Daily <br>The balances of control parameters enabled for a VCA are reset with their original values every day at 00:00:00.<br><br>M = Monthly<br>The balances of control parameters enabled for a VCA are reset with their original values at the start of every month. <br><br>W = Weekly<br>The balances of control parameters enabled for a VCA are reset with their original values every Monday at 00:00:00.<br><br>Q = Quarterly<br>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.<br>  Quarter 1: January 01 - March 31.<br>  Quarter 2: April 01 - June 30.<br>  Quarter 3: July 01 - September 30.<br>  Quarter 4: October 01 - December 31.<br><br>Y = Annually<br>The balances of control parameters enabled for a VCA are reset with their original values every year on January 1st at 00:00:00.<br><br>C = Continuous<br>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.<br><br>Visa: <br>1 = Recurring<br>The balances of control parameters enabled for a VCA are reset with their original values on a specified recurring day for every month. <br><br>If you select this periodType, you must also specify the resetDay field. <br><br>2 = Monthly<br>The balances of control parameters enabled for a VCA are reset with their original values at the start of every month. <br><br>3 = Date Range<br>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.<br><br>If you select this periodType, you must also specify the validityStartDate and validityEndDate fields.",
          "type": "string",
          "format": "alphanumeric",
          "maxLength": 1
        },
        "periodEndDate": {
          "description": "End date of the current period based on the periodType selected.<br><br>Mastercard - Optional<br>Visa - Not applicable",
          "type": "string",
          "format": "alphanumeric",
          "maxLength": 10
        },
        "availableBalance": {
          "description": "Remaining available amount balance on the VCA",
          "type": "string",
          "format": "BigDecimal"
        },
        "resetDay": {
          "description": "The day of each month when the control parameter balances should reset to their original value.<br>Mastercard - Not applicable<br>Visa - Optional",
          "type": "string",
          "format": "long",
          "maxLength": 19
        },
        "consumedAmount": {
          "description": "The amount consumed on the VCA<br>Mastercard - Not applicable<br>Visa - Required",
          "type": "string",
          "format": "BigDecimal"
        },
        "availableCountBalance": {
          "description": "Remaining available authorization count balance on the VCA<br>Mastercard - Not applicable<br>Visa - Required",
          "type": "string",
          "format": "long",
          "maxLength": 19
        },
        "consumedCount": {
          "description": "The number of authorizations consumed on the VCA<br>Mastercard - Not applicable<br>Visa - Required",
          "type": "string",
          "format": "long",
          "maxLength": 19
        }
      }
    },
    "TimeOfDay": {
      "properties": {
        "startTime": {
          "description": "Specifies the start time from when the card can be used each of the specified days.t<br><br>Mastercard - Optional<br>Visa - Optional. The minutes digit must be populated with zero only<br><br>`Format:` hh:mm",
          "type": "string",
          "format": "alphanumeric",
          "maxLength": 5
        },
        "endTime": {
          "description": "Specifies the end time until which the card can be used each of the specified days.<br><br>Mastercard - Optional<br>Visa - Optional. The minutes digit must be populated with zero only<br><br>`Format:` hh:mm",
          "type": "string",
          "format": "alphanumeric",
          "maxLength": 5
        },
        "weekdayEffective": {
          "description": "Specifies the day applicable to the start and end times defined.<br>Mastercard - Optional<br>Visa - Optional<br><br>Possible Values:<br><br>MON<br>TUE<br>WED<br>THU<br>FRI<br>SAT<br>SUN<br>",
          "type": "string",
          "format": "alphanumeric",
          "maxLength": 3
        }
      }
    }
  }
}