{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/api-evangelist/citi/main/json-schema/citi-case-request-schema.json", "title": "CaseRequest", "x-generated": "2026-10-12", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/citi-create-dispute-request-api-openapi.yml#/components/schemas/CaseRequest", "properties": { "reasonCode": { "description": "Reason Code provides the Dispute reason for sending the chargeback. Based on the selected reason code, the respective reason code details need to be passed in the request.", "type": "string", "format": "string", "title": "reasonCode", "enum": [ "DuplicateProcessing", "AlteredAmount", "IncorrectTransactionCurrency", "MultipleProcessing", "CreditAppliedAsCharge", "HotelCancellation", "AirlineTicketCancellation", "MerchandiseReturned", "CreditNotReceived", "CancelledRecurringTransaction", "PaidByOtherMeans", "ATMDiscrepancy", "NotAsDescribed", "NeverReceived", "FraudulentTransaction" ] }, "reasonCodeDetails": { "$ref": "#/$defs/ReasonCodeDetails" }, "transactionDetails": { "description": "Dispute transactions details", "type": "array", "maxLength": 1, "title": "transactionDetails", "items": { "$ref": "#/$defs/TransactionDetails" } } }, "required": [ "reasonCode", "transactionDetails", "reasonCodeDetails" ], "$defs": { "ATMDiscrepancy": { "properties": { "amntDispensed": { "description": "Amount dispensed at the ATM.", "type": "string", "format": "Double", "title": "amntDispensed", "maxLength": 19 } }, "required": [ "amntDispensed" ] }, "AirlineTicketCancellation": { "title": "AirlineTicketCancellation", "properties": { "isCancelled": { "description": "Is the airline ticket cancelled? True/False", "type": "string", "format": "string", "title": "isCancelled" }, "cancelledDate": { "description": "Cancellation Date.If isCancelled == 'true', then cancelledDate is required ", "type": "string", "format": "Date", "title": "cancelledDate" }, "cancelReason": { "description": "Cancellation Reason", "type": "string", "format": "string", "title": "cancelReason" }, "ticketNumber": { "description": "Ticket Number", "type": "string", "format": "string", "title": "ticketNumber" }, "contactedAirlineOn": { "description": "Date on which the client contacted the airline ", "type": "string", "format": "Date", "title": "contactedAirlineOn" }, "airlineResponse": { "description": "Response from the airline", "type": "string", "format": "string", "title": "airlineResponse" }, "travelAgentDetails": { "description": "Details of the Travel Agent ", "type": "string", "format": "string", "title": "travelAgentDetails" }, "cancellationPolicyAndNum": { "description": "Cancellation Policy and Number", "type": "string", "format": "string", "title": "cancellationPolicyAndNum" }, "isMerchantBankrupt": { "description": "Is merchant in bankruptcy/liquidation? True/False", "type": "string", "format": "string", "title": "isMerchantBankrupt" }, "serviceDate": { "description": "Date of service or expected service", "type": "string", "format": "Date", "title": "serviceDate" } }, "required": [ "isCancelled", "isMerchantBankrupt", "serviceDate" ] }, "AlteredAmount": { "properties": { "chComments": { "description": "Cardholder comments", "type": "string", "format": "alphanumeric", "title": "chComments", "maxLength": 250 }, "chAlteredAmtFrm": { "description": "This is the expected original transaction amount", "type": "string", "format": "Double", "title": "chAlteredAmtFrm", "maxLength": 19 }, "chAlteredAmtTo": { "description": "This is the amount that the original transaction amount was altered to", "type": "string", "format": "Double", "title": "chAlteredAmtTo", "maxLength": 19 } }, "required": [ "chAlteredAmtFrm", "chAlteredAmtTo" ] }, "CancelledRecurringTransaction": { "title": "CancelledRecurringTransaction", "properties": { "chNotificationDt": { "description": "Cardholder notification date to the merchant.", "type": "string", "format": "Date", "title": "chNotificationDt" }, "contactedMerchantDt": { "description": "Cardholder contact date with the Merchant.Either Contacted Merchant Date or Merchant Response is required ", "type": "string", "format": "Date", "title": "contactedMerchantDt" }, "merchantResponse": { "description": "Merchant response text to the card holder.Either Contacted Merchant Date or Merchant Response is required", "type": "string", "format": "string", "title": "merchantResponse" }, "cancellationNumber": { "description": "Cancellation number provided by the merchant to the Cardholder.", "type": "string", "format": "string", "title": "cancellationNumber" }, "cancellationReason": { "description": "Cancellation Reason", "type": "string", "format": "string", "title": "cancellationReason", "maxLength": 250 } }, "required": [ "chNotificationDt", "cancellationReason" ] }, "CreditAppliedAsCharge": { "properties": { "chComments": { "description": "Cardholder comments", "type": "string", "format": "alphanumeric", "title": "chComments", "maxLength": 250 } }, "additionalProperties": false }, "CreditNotReceived": { "properties": { "disputeAmnt": { "description": "Disputed Amount for which the credit is not received", "type": "string", "format": "Double", "title": "disputeAmnt", "maxLength": 19 }, "creditVoucherDate": { "description": "Date of credit voucher, transaction receipt or refund acknowledgement", "type": "string", "format": "Date", "title": "creditVoucherDate" }, "cancellationDate": { "description": "Date the cardholder cancelled the service or returned the merchandise", "type": "string", "format": "Date", "title": "cancellationDate" } }, "required": [ "disputeAmnt", "creditVoucherDate", "cancellationDate" ] }, "DuplicateProcessing": { "properties": { "chComments": { "description": "Cardholder comments", "type": "string", "format": "alphanumeric", "title": "chComments", "maxLength": 250 }, "chAckd": { "description": "Checkbox Answer to the Question -I certify that the information provided is true to the best of my knowledge (True/False)", "type": "string", "format": "string", "title": "chAckd" } }, "required": [ "chAckd" ] }, "FraudulentTransaction": { "title": "FraudulentTransaction", "properties": { "fraudulentType": { "description": "fraudulentType of fraud: Lost/Stolen/NeverReceived", "type": "string", "format": "string", "title": "fraudulentType" }, "cardInPossessionDuringTxn": { "description": "Was the card in possession of the CH during txn (True/False).", "type": "string", "format": "string", "title": "cardInPossessionDuringTxn" }, "anyoneHadAccessToCard": { "description": "Anyone else had access to the Card.True/False", "type": "string", "format": "string", "title": "anyoneHadAccessToCard" }, "relationToCH": { "description": " Relationship of the CH with the person who had access to the Card.", "type": "string", "format": "string", "title": "relationToCH", "maxLength": 16 }, "cardLostDt": { "description": "Date when the card was lost. Should be YYYYMMDD format", "type": "string", "format": "Date", "title": "cardLostDt" }, "cardLostDiscDt": { "description": "Date when the card lost was discovered.. Should be YYYYMMDD format", "type": "string", "format": "Date", "title": "cardLostDiscDt" }, "cardStolenDt": { "description": "Date when the card was stolen. Should be YYYYMMDD format", "type": "string", "format": "Date", "title": "cardStolenDt" }, "cardStolenDiscDt": { "description": "Date when the card stolen was discovered. Should be YYYYMMDD format", "type": "string", "format": "Date", "title": "cardStolenDiscDt" }, "descOnCardStolen": { "description": "Describe how the card was stolen. should not exceed 250 char limit", "type": "string", "format": "string", "title": "descOnCardStolen", "maxLength": 250 }, "isReportedToCiti": { "description": "Is card lost or stolen reported to Citi (true/false).", "type": "string", "format": "string", "title": "isReportedToCiti" }, "cardDeliveryAdd": { "description": "Address where the card to be delivered.", "type": "string", "format": "string", "title": "cardDeliveryAdd", "maxLength": 250 }, "chComments": { "description": "Cardholder comments", "type": "string", "format": "string", "title": "chComments", "maxLength": 250 } }, "required": [ "cardInPossessionDuringTxn" ] }, "HotelCancellation": { "title": "HotelCancellation", "properties": { "chComments": { "description": "Cardholder comments ", "type": "string", "format": "alphanumeric", "title": "chComments", "maxLength": 250 }, "cancelledDate": { "description": "Cardholder cancellation date. Should be YYYYMMDD format", "type": "string", "format": "Date", "title": "cancelledDate" }, "cancelledTime": { "description": "Cardholder cancellation time. Should be HH:MM format", "type": "string", "format": "Time", "title": "cancelledTime" }, "cancellationNumber": { "description": "Cancellation number .If isCancelPolicyProvided == Y then, Either Cancellation Number or Cancellation Details is required", "type": "string", "format": "numeric", "title": "cancellationNumber" }, "isCancelPolicyProvided": { "description": "Is the cancellation policy provided? True/False", "type": "string", "format": "string", "title": "isCancelPolicyProvided" }, "cancellationDetails": { "description": "Cancellation details.Either Cancellation Number or Cancellation Details is required", "type": "string", "format": "alphanumeric", "title": "cancellationDetails", "maxLength": 250 }, "contactedMerchantDt": { "description": "Cardholder contact date with the Merchant. Should be YYYYMMDD format", "type": "string", "format": "Date", "title": "contactedMerchantDt" }, "merchantResponse": { "description": "Response from the Merchant .If CancellationDetails is iprovided then Merchant Response is Mandatory", "type": "string", "format": "alphanumeric", "title": "merchantResponse" }, "isMerchantBankrupt": { "description": "Is the Merchant Bankrupt? (True/False)", "type": "string", "format": "string", "title": "isMerchantBankrupt" }, "serviceType": { "description": "Type of Service :T=Timeshare/G=Guaranteed Reservation", "type": "string", "format": "string", "title": "serviceType" }, "reservationType": { "description": "If Service Type is G , then choose any of the below :GR = The cardholder properly cancelled the guaranteed reservation/RC = The cardholder attempted to cancel within 24 hours of delivery of the reservation confirmation/AR = The merchant billed a no show transaction for more than one day's accommodation or rental", "type": "string", "format": "string", "title": "reservationType" }, "serviceDate": { "description": "Date of service or expected service", "type": "string", "format": "Date", "title": "serviceDate" }, "cancellationReason": { "description": "Cancellation Reason", "type": "string", "format": "alphanumeric", "title": "cancellationReason", "maxLength": 250 } }, "required": [ "cancelledDate", "isCancelPolicyProvided", "isMerchantBankrupt", "serviceType", "serviceDate", "cancellationReason" ] }, "IncorrectTransactionCurrency": { "properties": { "merchantProcessedCurr": { "description": "Merchants processed currency only. E.g. USD, INR, IDR, SGD", "type": "string", "format": "string", "title": "merchantProcessedCurr", "maxLength": 3, "minLength": 3 }, "chReceiptCurr": { "description": "Cardholders receipt currency only. E.g. USD, INR, IDR, SGD", "type": "string", "format": "string", "title": "chReceiptCurr", "maxLength": 3, "minLength": 3 } }, "required": [ "merchantProcessedCurr", "chReceiptCurr" ] }, "MerchandiseReturned": { "title": "MerchandiseReturned", "properties": { "merchandiseAmnt": { "description": "Merchandise Amount", "type": "string", "format": "Double", "title": "merchandiseAmnt", "maxLength": 19 }, "merchandiseReturnedOn": { "description": "Date the merchandise was returned on (YYYYMMDD)", "type": "string", "format": "Date", "title": "merchandiseReturnedOn" }, "returnReason": { "description": "Reason for returning the merchandise", "type": "string", "format": "string", "title": "returnReason" }, "contactedMerchantOn": { "description": "Date the merchant was contacted on (YYYYMMDD)", "type": "string", "format": "Date", "title": "contactedMerchantOn" }, "merchantResponse": { "description": "Merchant Response", "type": "string", "format": "string", "title": "merchantResponse" }, "merchantReturnPolicy": { "description": "Merchant Return Policy", "type": "string", "format": "string", "title": "merchantReturnPolicy" }, "returnItems": { "description": "Items returned to the merchant", "type": "string", "format": "string", "title": "returnItems" }, "isReturnAuthorized": { "description": "Is the Return Authorized? (True/False)", "type": "string", "format": "string", "title": "isReturnAuthorized" }, "merchantAdvise": { "description": "Merchant advise", "type": "string", "format": "string", "title": "merchantAdvise" }, "merchandiseReceivedOn": { "description": "Date the merchandise was received (YYYMMDD)", "type": "string", "format": "Date", "title": "merchandiseReceivedOn" }, "invoiceNumber": { "description": "Invoice Number", "type": "string", "format": "string", "title": "invoiceNumber" }, "packageSignedBy": { "description": "Package Signed by ", "type": "string", "format": "string", "title": "packageSignedBy" }, "deliveryAddress": { "description": "Delivery Address", "type": "string", "format": "string", "title": "deliveryAddress" }, "returnMethod": { "description": "\"Return Method.Mandatory if invoice number is present.
Domain Values:
FF=Face to Face
FE=Fed Ex
D=DHL
U=UPS
P=Postal Service
O=Other\"", "type": "string", "format": "string", "title": "returnMethod" }, "otherComments": { "description": "Other Comments.Mandatory if value Other selected in Retun Method", "type": "string", "format": "string", "title": "otherComments", "maxLength": 250 }, "merchantReturnReceivedDt": { "description": "Date of receipt of returned merchandise", "type": "string", "format": "Date", "title": "merchantReturnReceivedDt" } }, "required": [ "merchandiseAmnt", "merchandiseReturnedOn", "returnReason", "contactedMerchantOn", "merchantResponse", "returnItems", "isReturnAuthorized", "merchantReturnReceivedDt" ] }, "MultipleProcessing": { "properties": { "chComments": { "description": "Cardholder comments", "type": "string", "format": "alphanumeric", "title": "chComments", "maxLength": 250 }, "chProvidedTransDt": { "description": "Cardholder provided transaction date, Should be YYYYMMDD format", "type": "string", "format": "Date", "title": "chProvidedTransDt" }, "chProvidedTransAmnt": { "description": "Cardholder provided transactional amount .", "type": "string", "format": "Double", "title": "chProvidedTransAmnt", "maxLength": 19 } }, "required": [ "chProvidedTransDt", "chProvidedTransAmnt" ] }, "NeverReceived": { "title": "NeverReceived", "properties": { "whatNotReceived": { "description": "Details of merchandise or service.", "type": "string", "format": "string", "title": "whatNotReceived", "maxLength": 250 }, "purchaseAmnt": { "description": "Amount of Purchase", "type": "string", "format": "Double", "title": "purchaseAmnt", "maxLength": 19 }, "expectedDt": { "description": "Expected date of the Merchandise. ", "type": "string", "format": "Date", "title": "expectedDt" }, "deliveredAddress": { "description": "Delivery Address", "type": "string", "format": "string", "title": "deliveredAddress" }, "contactNm": { "description": "Name/Number of the person contacted.", "type": "string", "format": "string", "title": "contactNm" }, "contactMethod": { "description": "Contact Method like phone etc.", "type": "string", "format": "string", "title": "contactMethod" }, "contactDt": { "description": "Date Contacted", "type": "string", "format": "Date", "title": "contactDt" }, "merchantResponse": { "description": "Merchant response.", "type": "string", "format": "string", "title": "merchantResponse" }, "merchandiseOrService": { "description": "What was not received? Merchandise or Service? ", "type": "string", "format": "string", "title": "merchandiseOrService" }, "didMerchantCancel": { "description": "Did merchant cancel services? / Did merchant cancel the merchandise? True/False", "type": "string", "format": "string", "title": "didMerchantCancel" }, "merchantCancelledDt": { "description": "Date merchant cancelled merchandise/services.Mandatory if 'didMerchantCancel' is True", "type": "string", "format": "string", "title": "merchantCancelledDt" }, "isMerchantBankrupt": { "description": "Is merchant in bankruptcy/liquidation? True/False", "type": "string", "format": "string", "title": "isMerchantBankrupt" } }, "required": [ "whatNotReceived", "purchaseAmnt", "expectedDt", "deliveredAddress", "contactDt", "merchandiseOrService", "didMerchantCancel", "isMerchantBankrupt" ] }, "NotAsDescribed": { "properties": { "chExplanation": { "description": "CH provided explanation of what merchandise or service was received and what was expected.", "type": "string", "format": "string", "title": "chExplanation", "maxLength": 250 }, "transactionHappenedAt": { "description": "Where the transaction took place", "type": "string", "format": "string", "title": "transactionHappenedAt" }, "merchandiseReceivedDt": { "description": "Merchandise received or expected to receive date.", "type": "string", "format": "Date", "title": "merchandiseReceivedDt" }, "merchandiseCancelledDt": { "description": "Merchandise returned or cancelled date.", "type": "string", "format": "Date", "title": "merchandiseCancelledDt" }, "contactedMerchantDt": { "description": "Merchant contact date.", "type": "string", "format": "Date", "title": "contactedMerchantDt" }, "merchantResponse": { "description": "Merchant response detail.", "type": "string", "format": "string", "title": "merchantResponse", "maxLength": 250 }, "isMerchantRefused": { "description": "Merchant Accepted or refuse to accept (true/false).", "type": "string", "format": "string", "title": "isMerchantRefused" }, "merchantAdvise": { "description": "What did the merchant refuse or advise.", "type": "string", "format": "string", "title": "merchantAdvise" }, "invoiceNumber": { "description": "Invoice or Tracking number for return.", "type": "string", "format": "string", "title": "invoiceNumber", "maxLength": 64 }, "packageSignedBy": { "description": "Who signed the package.", "type": "string", "format": "string", "title": "packageSignedBy", "maxLength": 64 }, "deliveryAddress": { "description": "Delivery Address", "type": "string", "format": "string", "title": "deliveryAddress", "maxLength": 250 }, "whatPurchased": { "description": "What was purchased? Merchandise or Service?", "type": "string", "format": "string", "title": "whatPurchased" }, "merchantReturnReceivedDt": { "description": "Date merchant received returned merchandise", "type": "string", "format": "Date", "title": "merchantReturnReceivedDt" }, "merchantAcceptedCancellation": { "description": "Did the merchant accept the cancellation?If What was purchased = Service: True/False", "type": "string", "format": "string", "title": "merchantAcceptedCancellation" }, "returnMethod": { "description": "Return Method Applicable if invoice number is present. choose any one of below allowed return methods:
  1. 'FF=Face to Face'
  2. 'FE=Fed Ex'
  3. 'D=DHL'
  4. 'U=UPS'
  5. 'P=Postal Service'
  6. 'O=Other'
", "type": "string", "format": "string", "title": "returnMethod" }, "otherComments": { "description": "Other Comments", "type": "string", "format": "string", "title": "otherComments", "maxLength": 250 } }, "required": [ "chExplanation", "transactionHappenedAt", "merchandiseReceivedDt", "merchandiseCancelledDt", "contactedMerchantDt", "isMerchantRefused", "invoiceNumber", "whatPurchased", "merchantReturnReceivedDt" ] }, "PaidByOtherMeans": { "title": "PaidByOtherMeans", "properties": { "contactedMerchantDt": { "description": "Cardholder contact date with the Merchant. Format YYYYMMDD", "type": "string", "format": "Date", "title": "contactedMerchantDt" }, "meansOfPayment": { "description": "Providing proof of payment by other means,values- A, T, C, F,V,S,O", "type": "string", "format": "string", "title": "meansOfPayment" }, "merchantResponse": { "description": "Merchant response text to the card holder.", "type": "string", "format": "string", "title": "merchantResponse", "maxLength": 250 } }, "required": [ "contactedMerchantDt", "meansOfPayment", "merchantResponse" ] }, "ReasonCodeDetails": { "description": "Pass the reason code details based on the reason code selected.", "oneOf": [ { "$ref": "#/$defs/DuplicateProcessing" }, { "$ref": "#/$defs/AlteredAmount" }, { "$ref": "#/$defs/IncorrectTransactionCurrency" }, { "$ref": "#/$defs/MultipleProcessing" }, { "$ref": "#/$defs/CreditAppliedAsCharge" }, { "$ref": "#/$defs/HotelCancellation" }, { "$ref": "#/$defs/MerchandiseReturned" }, { "$ref": "#/$defs/CreditNotReceived" }, { "$ref": "#/$defs/AirlineTicketCancellation" }, { "$ref": "#/$defs/CancelledRecurringTransaction" }, { "$ref": "#/$defs/NeverReceived" }, { "$ref": "#/$defs/NotAsDescribed" }, { "$ref": "#/$defs/ATMDiscrepancy" }, { "$ref": "#/$defs/PaidByOtherMeans" }, { "$ref": "#/$defs/FraudulentTransaction" } ] }, "TransactionDetails": { "properties": { "requestId": { "description": "Unique Request ID. UUID generated by a client for each individual transaction", "type": "string", "format": "alphanumeric", "title": "requestId", "maxLength": 36, "minLength": 36 }, "acquirerReferenceNumber": { "description": "The Acquirer Reference Number of the transaction against which the dispute case creation request is being raised", "type": "string", "format": "numeric", "title": "acquirerReferenceNumber", "maxLength": 24, "minLength": 23 }, "disputeAmount": { "description": "Dispute Amount", "type": "number", "format": "Double", "title": "disputeAmount", "maxLength": 19 }, "disputeCurrency": { "description": "Disputed amount currency. ISO-3 Currency Code only. E.g. USD, INR, IDR, SGD", "type": "string", "format": "string", "title": "disputeCurrency", "minLength": 3, "maxLength": 3 } }, "required": [ "requestId", "acquirerReferenceNumber", "disputeAmount", "disputeCurrency" ] } } }