Citi Dispute webhook API

openapi: 3.2.0
info:
  description: Cards dispute APIs.
  version: 1.0.0
  title: Cards Disputes Dispute webhook API
  x-ibm-name: cards-disputes
  contact:
    name: GLOBAL Commercial Cards API Production support
    email: dl.icg.global.commercial.cards.digital.production.support@imcap.ap.ssmb.com
tags:
- name: Dispute webhook
  description: Webhook notification to be sent to clients for case status
paths:
  /v1/webhook:
    post:
      summary: Webhooks notifications
      description: Webhooks notifications to client for dispute case status
      operationId: disputeNotifications
      tags:
      - Dispute webhook
      parameters:
      - name: Authorization
        in: header
        description: <br>`Client has option to choose basicAuth for webhook connectivity `</br>`Example:`</br>Basic AAIkMjU2OTI4OGQtODY5Ny00ZjgzLTg0NzEtY2QyZWYwZjM5ZjJk_m3yqnGAbxR_ovVx5bs9OUfF0dd52qHadLtw2ARkwCw2BJcwg1zHsTOuvjPtsW5ioxxd2xXXjlDDCKLuvg15Ce1gzGxTu17xEvLOzSECLIdU_02JbpS3h9ee9GzB
        schema:
          type: string
        required: false
      - name: grace_tracking_id
        in: header
        description: Unique tracking Id sent by Citi
        schema:
          type: string
        required: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DisputeCaseStatusUpdate'
            examples:
              Create:
                $ref: '#/components/examples/create'
              Update:
                $ref: '#/components/examples/update'
              Status Change:
                $ref: '#/components/examples/statusChange'
              Upload Document:
                $ref: '#/components/examples/uploadDocument'
      responses:
        '201':
          description: Dispute Case Status Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/successResponsePayload'
components:
  examples:
    statusChange:
      value:
        trackingId: 7d13245e-243a-5e8f-bc10-8626ec728291
        reasonCode: DuplicateProcessing
        eventType: STATUS_CHANGE
        disputeCaseDetails:
        - caseId: '22345678901'
          statusDescription: CC - Closed in favour of cardholder
          acquirerReferenceNumber: '22345678901234500000000'
          statusAsOnDate: 20260101 02:30:34:000
          remarks: Case closed successfully
          remarksLastUpdatedOn: 20260101 02:30:34:000
    update:
      value:
        trackingId: 7d13245e-243a-5e8f-bc10-8626ec728291
        reasonCode: DuplicateProcessing
        eventType: UPDATE
        disputeCaseDetails:
        - caseId: '22345678901'
          status: SUCCESS
    uploadDocument:
      value:
        trackingId: 7d13245e-243a-5e8f-bc10-8626ec728291
        eventType: UPLOAD_DOCUMENT
        disputeCaseDetails:
        - caseId: '22345678901'
          status: SUCCESS
          documentReferenceId: NchL202404251414678
    create:
      value:
        trackingId: 7d13245e-243a-5e8f-bc10-8626ec728291
        reasonCode: DuplicateProcessing
        eventType: CREATE
        disputeCaseDetails:
        - caseId: '22345678901'
          statusDescription: OP - Open
          acquirerReferenceNumber: '22345678901234500000000'
          requestId: 73d150f5-ee16-4841-a2db-4f24b6d372cc
          statusAsOnDate: 20260101 02:30:34:000
          remarks: Case created successfully
          remarksLastUpdatedOn: 20260101 02:30:34:000
  schemas:
    DisputeCaseStatusUpdate:
      properties:
        trackingId:
          type: string
          format: string
          title: trackingId
          description: Unique identifier associated with the client’s original request. This ID matches the value returned in the synchronous acknowledgement for the corresponding API call (create, update, or upload) and enables the client to track and reconcile webhook notifications.
          example: 7d13245e-243a-5e8f-bc10-8626ec728291
        reasonCode:
          type: string
          format: string
          title: reasonCode
          description: Reason Code provided in the Case Creation request for the Dispute reason
          example: Reason Code sent by client in request e.g DuplicateProcessing, AlteredAmount etc
        eventType:
          type: string
          format: string
          description: Specifies the type of event that triggered this webhook notification, helping the client understand the context and purpose of the payload.
          title: eventType
          enum:
          - CREATE
          - UPDATE
          - STATUS_CHANGE
          - UPLOAD_DOCUMENT
        disputeCaseDetails:
          description: Details of dispute case
          type: array
          title: disputeCaseDetails
          items:
            $ref: '#/components/schemas/DisputeCaseDetails'
      required:
      - trackingId
      - disputeCaseDetails
    successResponsePayload:
      properties:
        response:
          type: string
          format: string
          title: res
          example: Acknowledged
    ErrorMessage:
      title: ErrorMessage
      properties:
        errorCode:
          type: string
          example: ErrorCode
          description: 'ErrorCode * `DISP250` * `DISP251` * `DISP252` * `DISP253` * `DISP254` * `DISP255` * `DISP256` * `DISP257` * `DISP258` * `DISP259` * `DISP260` * `DISP261` * `DISP262` * `DISP263` * `DISP264` * `DISP265` * `DISP266` * `DISP267` * `DISP200` * `GRC0014`

            '
        errorDescription:
          type: string
          example: ErrorDescription
          description: 'ErrorDescription * `DisPute case creation failed- Invalid dispute Reason Code` * `Dispute case creation failed- Settlement Details cannot be fetched for the given ARN` * `Dispute case creation failed- Invalid Client relationship number (GCN)` * `Dispute case creation failed- Invalid dispute Amount` * `Dispute case creation failed- Dispute Amount higher than amount cap` * `Dispute case creation failed- Internal technical failure` * `Dispute case creation failed- Dispute request transaction not posted to cardholder statement` * `Dispute case creation failed- Transaction should be a purchase to dispute` * `Dispute case creation failed- Transaction aging is beyond 90 days` * `Dispute case creation failed- Blocked card. Cannot be disputed` * `Dispute case creation failed- C2AT type transaction. Cannot be disputed` * `Dispute case creation failed- Internal Processing error` * `Dispute case creation failed- Internal Processing error` * `Dispute case creation failed- Internal Processing error` * `Dispute case creation failed- Internal Processing error` * `Dispute case creation failed- Internal Processing error` * `Dispute case creation failed- Internal Processing error` * `Dispute case creation failed- Internal Processing error` * `We have encountered an error and couldn''t process your request. Please call the Dispute Status Enquiry API using the ARN to see whether a case ID was created. If a case ID was not created, please try your case creation request again, or contact Citi support if you have any further questions or comments.`

            '
      required:
      - requestId
      - acquirerReferenceNumber
    DisputeCaseDetails:
      properties:
        requestId:
          description: Request ID sent by client in case creation request
          type: string
          format: alphanumeric
          title: requestId
          example: 73d150f5-ee16-4841-a2db-4f24b6d372cc
          maxLength: 36
          minLength: 36
        acquirerReferenceNumber:
          description: Acquirer Reference Number (ARN)
          type: string
          format: numeric
          title: acquirerReferenceNumber
          example: '22345678901234500000000'
          maxLength: 24
          minLength: 23
        caseId:
          description: The unique identifier assigned to the dispute case related to this webhook event.
          type: string
          format: alphanumeric
          title: caseId
          example: '22345678901'
          minLength: 11
          maxLength: 11
        statusDescription:
          description: Case status description. Possible values - OP - Open; CP - Awaiting Information from Cardholder; CR - Cancelled / Rejected; CM - Closed in favour of bank; CC - Closed in favour of cardholder; CB - Chargeback submitted to Network
          type: string
          format: string
          title: statusDescription
          example: CC - Closed in favour of cardholder
        statusAsOnDate:
          description: This is the Date Timestamp that the status was last updated. This is in the GMT timezone with format YYYYMMDD HH:MM:SS:MMM
          type: string
          format: alphanumeric
          title: statusAsOnDate
          example: 20260101 02:30:34:000
        status:
          description: 'Status of update or upload event. eg: SUCCESS, FAILED'
          type: string
          format: string
          title: status
          example: SUCCESS
        documentReferenceId:
          description: Document Id
          type: string
          format: string
          title: documentReferenceId
          example: NchL202404251414678
          maxLength: 19
          minLength: 19
        remarks:
          description: The latest remarks or comments  added to the dispute case id to provide additional information to the client.
          type: string
          format: string
          title: remarks
        remarksLastUpdatedOn:
          description: Timestamp indicating when the remarks associated with the case were last updated.
          type: string
          format: string
          title: remarksLastUpdatedOn
          example: 20260131 23:09:00:001
        errors:
          title: errors
          type: array
          items:
            $ref: '#/components/schemas/ErrorMessage'