openapi: 3.2.0
info:
  title: Dispute Management Disputes Actions API
  description: End to end disputes management interface.
  version: 1.1.3
  contact:
    name: Disputes API Support
    url: https://developer.jpmorgan.com/support
    email: developer_help@jpmorgan.com
servers:
- url: https://api.payments.jpmorgan.com/commerce/v1
  description: PRODUCTION - OAUTH
- url: https://api-sandbox.payments.jpmorgan.com/commerce/v1
  description: CLIENT TESTING - OAUTH
security:
- bearerAuth: []
tags:
- name: Disputes Actions
  description: Operations for executing actions on disputes, such as challenging, accepting, and fulfilling requests.
paths:
  /disputes/{disputeId}/challenge:
    post:
      summary: Challenge a dispute
      operationId: challengeDispute
      tags:
      - Disputes Actions
      description: The consumers of this API can request the acquirer to challenge a dispute by attaching evidence documents. Once the dispute has been requested to be challenged, the acquirer will review the remedy details and will challenge the dispute back to the payment brands and then to the cardholder.
      parameters:
      - name: disputeId
        in: path
        required: true
        schema:
          type: integer
          format: int64
          minimum: 10000
          maximum: 9223372036854776000
        description: A unique identifier assigned by the acquirer to track each inquiry or case created for a transaction dispute on an account.
        examples:
          Success:
            value: 9876543210
      - name: request-id
        in: header
        required: true
        schema:
          type: string
          format: uuid
        description: Unique request identifier provided by the requestor.
        examples:
          Success:
            value: f47ac10b-58cc-4372-a567-0e02b2c3d479
      - name: merchant-id
        in: header
        required: true
        schema:
          type: string
          pattern: ^\d+$
          minLength: 1
          maxLength: 12
        description: Identifies a unique entity for transaction processing at the lowest level of the account hierarchy of the backend proprietary merchant acquiring processing platform. This level organizes transaction types for submission, funding, and reporting.
        examples:
          Success:
            value: '9876543'
      - $ref: '#/components/parameters/platformIdHeader'
      requestBody:
        description: Challenge Request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/challengeRequest'
            examples:
              Success:
                value:
                  last4CardNumber: '6543'
                  supportingDocuments:
                  - documentName: sample1.pdf
                    documentContent: JVBERi0xLjYNJeLjz9MNCjEwIDAgb2JqDTw8L0xpbmVhcml6ZWQgMS9MIDI4NTczL08gMTIvRSAyNDI2NS9OIDEvVCA
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/challengeDisputeResponse'
              examples:
                Success:
                  value:
                    requestId: f47ac10b-58cc-4372-a567-0e02b2c3d479
                    disputeId: 9876543210
                    actionProcessingStatus: COMPLETED
                    disputeStatus: CHALLENGED_MERCHANT
                    statusUpdateTimestamp: '2025-01-01T12:00:00Z'
                    traceId: 9f8c4b2e-3d6a-4f1b-9a2e-5b7c8d9e0f1a
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
        '406':
          description: Not Acceptable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
  /disputes/{disputeId}/fulfill:
    post:
      summary: Fulfill a retrieval request dispute
      operationId: fulfillDispute
      tags:
      - Disputes Actions
      description: The consumers of this API can request the acquirer to fulfill a retrieval request dispute by attaching evidence documents. Once the dispute has been fulfilled, the acquirer will fulfill the retrieval request back to the payment brands.
      parameters:
      - name: disputeId
        in: path
        required: true
        schema:
          type: integer
          format: int64
          minimum: 10000
          maximum: 9223372036854776000
        description: A unique identifier assigned by the acquirer to track each inquiry or case created for a transaction dispute on an account.
        examples:
          Success:
            value: 9876543210
      - name: request-id
        in: header
        required: true
        schema:
          type: string
          format: uuid
        description: Unique request identifier provided by the requestor.
        examples:
          Success:
            value: f47ac10b-58cc-4372-a567-0e02b2c3d479
      - name: merchant-id
        in: header
        required: true
        schema:
          type: string
          pattern: ^\d+$
          minLength: 1
          maxLength: 12
        description: Identifies a unique entity for transaction processing at the lowest level of the account hierarchy of the backend proprietary merchant acquiring processing platform. This level organizes transaction types for submission, funding, and reporting.
        examples:
          Success:
            value: '9876543'
      - $ref: '#/components/parameters/platformIdHeader'
      requestBody:
        description: Fulfill a retrieval request dispute
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/fulfillRequest'
            examples:
              Success:
                value:
                  last4CardNumber: '4567'
                  supportingDocuments:
                  - documentName: sample1.pdf
                    documentContent: JVBERi0xLjYNJeLjz9MNCjEwIDAgb2JqDTw8L0xpbmVhcml6ZWQgMS9MIDI4NTczL08gMTIvRSAyNDI2NS9OIDEvVCA
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/fulfillDisputeResponse'
              examples:
                Success:
                  value:
                    requestId: f47ac10b-58cc-4372-a567-0e02b2c3d479
                    disputeId: 9876543211
                    actionProcessingStatus: COMPLETED
                    disputeStatus: CHALLENGED_MERCHANT
                    statusUpdateTimestamp: '2025-01-01T12:00:00Z'
                    traceId: f47ac10b-58cc-4372-a567-0e02b2c3d479
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
        '406':
          description: Not Acceptable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
  /disputes/{disputeId}/accept:
    post:
      summary: Accept a dispute
      operationId: acceptDispute
      tags:
      - Disputes Actions
      description: The consumers of this API can accept the dispute and take financial liability for the transaction.
      parameters:
      - name: disputeId
        in: path
        required: true
        schema:
          type: integer
          format: int64
          minimum: 10000
          maximum: 9223372036854776000
        description: A unique identifier assigned by the acquirer to track each inquiry or case created for a transaction dispute on an account.
        examples:
          Success:
            value: 9876543210
      - name: request-id
        in: header
        required: true
        schema:
          type: string
          format: uuid
        description: Unique request identifier provided by the requestor.
        examples:
          Success:
            value: f47ac10b-58cc-4372-a567-0e02b2c3d479
      - name: merchant-id
        in: header
        required: true
        schema:
          type: string
          pattern: ^\d+$
          minLength: 1
          maxLength: 12
        description: Identifies a unique entity for transaction processing at the lowest level of the account hierarchy of the backend proprietary merchant acquiring processing platform. This level organizes transaction types for submission, funding, and reporting.
        examples:
          Success:
            value: '9876543'
      - $ref: '#/components/parameters/platformIdHeader'
      requestBody:
        description: Accept Request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/acceptRequest'
            examples:
              Success:
                value:
                  last4CardNumber: '9876'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/acceptDisputeResponse'
              examples:
                Success:
                  value:
                    requestId: f47ac10b-58cc-4372-a567-0e02b2c3d479
                    disputeId: 9876543212
                    actionProcessingStatus: COMPLETED
                    disputeStatus: ACCEPTED
                    statusUpdateTimestamp: '2025-01-01T12:00:00Z'
                    traceId: 9f8c4b2e-3d6a-4f1b-9a2e-5b7c8d9e0f1a
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
        '406':
          description: Not Acceptable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
components:
  schemas:
    fulfillRequest:
      description: Contains request attributes required to fulfill retrieval-request dispute.
      type: object
      required:
      - last4CardNumber
      - supportingDocuments
      properties:
        last4CardNumber:
          $ref: '#/components/schemas/last4CardNumber'
        supportingDocuments:
          type: array
          minItems: 1
          maxItems: 10
          description: Provide list of supporting document(s) in .pdf or .tiff or .tif format for the fulfill request.
          items:
            $ref: '#/components/schemas/supportingDocument'
    requestId:
      description: Unique request identifier provided by the requestor.
      type: string
      format: uuid
    messages:
      description: A list of errors and warnings
      type: object
      properties:
        httpStatus:
          $ref: '#/components/schemas/httpStatus'
        title:
          $ref: '#/components/schemas/title'
        requestId:
          $ref: '#/components/schemas/requestId'
        traceId:
          $ref: '#/components/schemas/traceId'
        context:
          type: array
          minItems: 0
          maxItems: 100
          description: Error Object Array for Failed requests
          items:
            $ref: '#/components/schemas/contextMessage'
    traceId:
      description: A number assigned by a transaction originator to assist in identifying a transaction uniquely. The systems trace audit number remains unchanged for all messages within a transaction.
      type: string
      readOnly: true
      format: uuid
    actionProcessingStatus:
      description: 'Codifies dispute action processing status code, in response of the case action requested by merchant. Possible values are, IN_PROGRESS: The request is being processed asynchronously and this is applicable for HTTP response status code 202. Check the retrieve-status endpoint for updates. COMPLETED: The request was processed successfully and this is applicable for HTTP response status code 200. Check error messages for details.'
      type: string
      enum:
      - IN_PROGRESS
      - COMPLETED
    location:
      description: Location of the field for which the error occurred in the request
      type: string
      minLength: 0
      maxLength: 1000
      enum:
      - BODY
      - PATH
      - QUERY
      - HEADER
    httpStatus:
      description: The response code that is returned to the client based on how a backend service handled the request
      type: integer
      format: int32
      minimum: 100
      maximum: 999
    last4CardNumber:
      description: Identifies the last 4 digits of card number. The truncated value is used in place of the full number to protect against exposure of confidential information.
      type: string
      minLength: 4
      maxLength: 4
    field:
      description: The field for which the error has occured.
      type: string
    statusUpdateTimestamp:
      description: Represents the date and time when the status of a dispute case was last updated in UTC timezone. The format is YYYY-MM-DDTHH:MM:SSZ.
      type: string
      format: date-time
    disputeStatus:
      description: The label for the current stage of a case in the dispute resolution process
      type: string
      maxLength: 50
      enum:
      - NEW
      - NEEDS_RESPONSE
      - EXPIRED
      - CHALLENGED_JPMC
      - UNDER_ISSUER_REVIEW
      - CHALLENGED_MERCHANT
      - ACCEPTED
      - CHALLENGE_DENIED
      - CLOSED
      - NEED_ADDITIONAL_INFORMATION
    fulfillDisputeResponse:
      description: Fulfill action response
      type: object
      properties:
        requestId:
          $ref: '#/components/schemas/requestId'
        disputeId:
          $ref: '#/components/schemas/disputeId'
        actionProcessingStatus:
          $ref: '#/components/schemas/actionProcessingStatus'
        disputeStatus:
          $ref: '#/components/schemas/disputeStatus'
        statusUpdateTimestamp:
          $ref: '#/components/schemas/statusUpdateTimestamp'
        traceId:
          $ref: '#/components/schemas/traceId'
    contextMessage:
      description: Object containing information in the file
      type: object
      properties:
        code:
          $ref: '#/components/schemas/code'
        message:
          $ref: '#/components/schemas/message'
        field:
          $ref: '#/components/schemas/field'
        location:
          $ref: '#/components/schemas/location'
    acceptDisputeResponse:
      description: Accept dispute response.
      type: object
      properties:
        requestId:
          $ref: '#/components/schemas/requestId'
        disputeId:
          $ref: '#/components/schemas/disputeId'
        actionProcessingStatus:
          $ref: '#/components/schemas/actionProcessingStatus'
        disputeStatus:
          $ref: '#/components/schemas/disputeStatus'
        statusUpdateTimestamp:
          $ref: '#/components/schemas/statusUpdateTimestamp'
        traceId:
          $ref: '#/components/schemas/traceId'
    code:
      description: Codifies a raised exception encountered by an internal or external system, sub-system, interface, job, module, system component with which the web service application interfaces.  In this instance it refers to the error raised when reporting job failed.
      type: string
    message:
      description: Provides textual description of a problem that has occurred and is preventing the system from completing a task. Messages can be a confirmation, warning or notification, and can trigger the system to apply a customized default value or override to a field, record or file, halt or postpone processing, skip or reject the entry generating the problem. Messages can be displayed on-screen in the user interface or in reporting.
      type: string
    title:
      description: Short human readable title of the error
      type: string
      minLength: 0
      maxLength: 1000
    challengeDisputeResponse:
      description: Challenge action response
      type: object
      properties:
        requestId:
          $ref: '#/components/schemas/requestId'
        disputeId:
          $ref: '#/components/schemas/disputeId'
        actionProcessingStatus:
          $ref: '#/components/schemas/actionProcessingStatus'
        disputeStatus:
          $ref: '#/components/schemas/disputeStatus'
        statusUpdateTimestamp:
          $ref: '#/components/schemas/statusUpdateTimestamp'
        traceId:
          $ref: '#/components/schemas/traceId'
    acceptRequest:
      description: Contains request attributes required to accept a dispute.
      type: object
      required:
      - last4CardNumber
      properties:
        last4CardNumber:
          $ref: '#/components/schemas/last4CardNumber'
    supportingDocument:
      description: Contains supporting document information for the dispute action.
      type: object
      required:
      - documentName
      - documentContent
      properties:
        documentName:
          description: Provide name of the document.
          type: string
        documentContent:
          description: Provide document content in base64-encoded format.
          type: string
    disputeId:
      description: A unique identifier assigned by the acquirer to track each inquiry or case created for a transaction dispute on an account.
      type: integer
      format: int64
      minimum: 10000
      maximum: 9223372036854776000
    challengeRequest:
      description: Contains request attributes required to challenge a dispute.
      type: object
      required:
      - last4CardNumber
      - supportingDocuments
      properties:
        last4CardNumber:
          $ref: '#/components/schemas/last4CardNumber'
        supportingDocuments:
          type: array
          minItems: 1
          maxItems: 10
          description: Provide list of supporting document(s) in .pdf or .tiff or .tif format for the challenge request.
          items:
            $ref: '#/components/schemas/supportingDocument'
  parameters:
    platformIdHeader:
      name: platform-id
      in: header
      required: false
      description: Platform identifier provided by the requestor. Identifies the platform used to onboard the merchant and enforce the authentication.
      schema:
        type: string
        maxLength: 20
        pattern: ^\d+$
      examples:
        Success:
          value: '2179821798'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-jpmc-securityDefinitions:
  JPMC-OAuth2:
    jpmc-claims:
      jpmc-roles:
      - 108919_DISPUTES_MERCH_ACCESS: allows all api access for disputes management
x-jpmc-security:
- JPMC-OAuth2:
    jpmc-claims:
      jpmc-roles:
      - 108919_DISPUTES_MERCH_ACCESS: allows all api access for disputes management