Dispute Management API
End to end disputes management interface.
OpenAPI Specification
# Harvested verbatim from the J.P. Morgan Payments Developer Portal.
# method: searched
# source: https://developer.payments.jpmorgan.com/api/llm-content?path=en%2Fapi%2Fcommerce%2Fdispute-management%2Fdispute-management-oas.md
# generated: '2026-07-28'
openapi: 3.0.1
info:
title: Dispute Management 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 Data Retrieval
description: Operations for fetching dispute-related data, such as list of disputes, details, status,
and issuer documents
- name: Disputes Actions
description: Operations for executing actions on disputes, such as challenging, accepting, and fulfilling
requests.
- name: Health Check
description: Check if Dispute Management service is available
paths:
/disputes/health:
get:
summary: Validate the health of the service.
operationId: getHealthCheck
tags:
- Health Check
description: Healthcheck endpoint to validate the health of the service.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/healthCheckResource'
'408':
description: Request Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/healthCheckResource'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/healthCheckResource'
/disputes:
post:
summary: Retrieve a list of disputes
operationId: fetchDisputes
tags:
- Disputes Data Retrieval
description: This API endpoint allows consumers to retrieve a list of disputes, including chargebacks,
retrieval requests, and pre-arbitration cases. Users can filter disputes by providing one or more
Transaction Division IDs, Processing Entity IDs, or Company IDs. The response is paginated, with
a maximum of 5,000 records per page. Disputes are sorted by due date in ascending order when available;
otherwise, they are sorted by the initiated date in ascending order. If no date range is specified,
the API returns disputes created within the last 90 days.
parameters:
- name: request-id
in: header
required: true
schema:
type: string
format: uuid
description: Unique request identifier provided by the requestor.
examples:
Success:
value: 123e4567-e89b-12d3-a456-426614174000
- $ref: '#/components/parameters/platformIdHeader'
requestBody:
description: Disputes Request
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/disputesRequest'
examples:
Success:
value:
entityIds:
companyIds:
- '12345678'
merchantIds:
- '9876543210'
disputeTypes:
- FIRST_CHARGEBACK
disputeStatuses:
- NEW
- NEEDS_RESPONSE
paymentMethodList:
- VI
- MC
initiatedStartDate: '2025-01-01'
initiatedEndDate: '2025-01-02'
disputeReceivedStartDate: '2025-01-01'
disputeReceivedEndDate: '2025-01-02'
responseDueStartDate: '2025-01-01'
responseDueEndDate: '2025-01-02'
pagination:
cursor: cGFnZVRva2VuMTIzNDU=
pageSize: 2000
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/disputesResponse'
examples:
Success:
value:
requestId: f47ac10b-58cc-4372-a567-0e02b2c3d479
disputes:
- disputeType: FIRST_CHARGEBACK
disputeId: 254311672
acquirerReferenceNumber: '24692166211000002406020'
disputeInitiatedDate: '2025-01-01'
disputeReceivedDate: '2025-01-01'
responseDueDate: '2025-01-18'
disputeValue:
amount: 100
currencyCode: USD
disputeReason:
reasonCode: '13.1'
reason: SERVICES NOT RENDERED/MDSE NOT RECVD
disputeCategoryCode: AUTHORIZATION
disputeStatus: NEEDS_RESPONSE
statusUpdateTimestamp: '2025-01-01T12:00:00Z'
outcome: PENDING
paymentMethod:
paymentMethodCode: VI
paymentMethodName: Visa
maskedAccountNumber: 123456XXXXXX4000
issuerDocumentCode: 1
issuerDocumentExpected: true
issuerDocumentReceived: true
authorizationData:
authorizationTimestamp: '2024-12-25T07:00:00Z'
authorizationReferenceNumber: ''
transactionData:
merchantOrderNumber: 123456ORD
transactionTimestamp: '2024-12-25T22:00:00Z'
transactionAmount: 100
transactionCurrency: USD
transactionId: '1707071808295'
submitterPlatformId: '2179821798'
merchantData:
companyId: '569874562'
merchantId: '498613834'
companyName: SAMPLE COMPANY
merchantName: SAMPLE DIVISION
pagination:
cursor: cGFnZVRva2VuMTIzNDU=
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'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
/disputes/{disputeId}:
get:
summary: Get dispute details
operationId: getDisputeDetails
tags:
- Disputes Data Retrieval
description: The consumers of this API endpoint can get additional details about a dispute by providing
the dispute case id.
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
- $ref: '#/components/parameters/platformIdHeader'
- 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'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/disputeDetailsResponse'
examples:
Success:
value:
requestId: f47ac10b-58cc-4372-a567-0e02b2c3d479
disputeDetails:
disputeType: FIRST_CHARGEBACK
disputeId: 9876543210
acquirerReferenceNumber: '25103246259000000000126'
bankIdentificationNumber: '12345678'
disputeValue:
amount: 100
currencyCode: USD
saleRefundCode: S
isCurrencyConversion: false
disputeCategoryCode: CONSUMER_DISPUTE
disputeReason:
reasonCode: '13.1'
reason: SERVICES NOT RENDERED/MDSE NOT RECVD
disputeReasonDetailed: '• Merchandise Not Received: The cardholder was charged for
merchandise that was not delivered/received, has attempted to resolve the issue
with the merchant. • Services Not Rendered: The cardholder was charged for a service
that was not rendered and has attempted to resolve the issue with the merchant.
• Expanded to include disputes related to no-show transactions, where merchant
cannot or is unable to render services (applies only to hotel merchants and U.S.
Domestic peak-time and specialized vehicle car rental merchants who are permitted
to process no-show transactions).'
potentialRemedies: 'Provide a letter of explanation detailing the transaction and
any attempts to remedy the dispute in addition to providing evidence of the following:
Provide a letter of explanation detailing the transaction and any attempts to
remedy the dispute in addition to providing evidence of the following: • Credit
was issued prior to first chargeback, including posting date and credit receipt.
• Documentation to prove that the cardholder or an authorized person received
the merchandise or services at the agreed location or by the agreed date. • Examples:
Signed proof of delivery to shipping address, signed pick up slips or job completion
certification. • For an Airline Transaction, evidence showing that the name is
included in the manifest for the departed flight and it matches the name provided
on the purchased itinerary. • Retail: Provide itemized sales slip. • Card Not
Present: Provide proof of AVS response, an itemized bill with bill-to and ship-to
addresses and proof of delivery. • Compelling Evidence: Visa will accept compelling
evidence for representment. This includes, but is not limited to: Evidence such
as photographs or emails to prove the person received the merchandise or service.
For download of digital goods, the IP address, email address, description of goods,
date and time goods were downloaded and/or proof the merchant’s website was accessed
for services after the transaction date. • Passenger transport — evidence the
ticket was received at cardholder’s billing address, boarding pass was scanned
at the gate, details of frequent flyer miles claimed, additional incidental transactions
purchased (such as baggage fees, seat upgrades, alcohol, etc.). • Previous undisputed
transaction — provide evidence that the information provided is the same as that
from a previous undisputed transaction. • Evidence that the transaction was completed
by a member of the Cardholder’s household.'
issuerMemo: This message is from issuer
messageToMerchant: This is a sample message to merchant.
disputeInitiatedDate: '2025-01-01'
disputeReceivedDate: '2025-01-01'
responseDueDate: '2025-01-18'
disputeStatus: NEEDS_RESPONSE
statusUpdateTimestamp: '2025-01-01T12:00:00Z'
outcome: PENDING
paymentMethod:
paymentMethodCode: VI
paymentMethodName: Visa
maskedAccountNumber: 123456XXXXXX4000
issuerDocumentCode: 1
issuerDocumentExpected: true
issuerDocumentReceived: true
transactionDataDetailed:
transactionData:
merchantOrderNumber: 123456ORD
transactionTimestamp: '2024-12-25T22:00:00Z'
transactionAmount: 100
transactionCurrency: USD
transactionId: '1707071708295'
submitterPlatformId: '2179821798'
transactionTypeCode: R
authorizationDataDetailed:
authorizationTimestamp: '2024-12-25T07:00:00Z'
authorizationIdentifier: a10078
authorizationReferenceNumber: ''
authorizationResponseCode: 100
authorizationAmount: 100
authorizationCurrency: USD
cavvResponseCode: '7'
secureIndicator: false
terminalNumber: TERM1234
posEntryMode: '02'
merchantDataDetailed:
merchantData:
companyId: '569874562'
merchantId: '498613834'
companyName: SAMPLE COMPANY
merchantName: SAMPLE DIVISION
merchantCategoryCode: '2331'
merchantCountryCode: USA
merchantRegionCode: US
merchantAccountId: 9874563210
relatedItems:
- disputeId: 9876543211
disputeType: RETRIEVAL_REQUEST
disputeValue:
amount: 100
currencyCode: USD
disputeReason:
reasonCode: '13.1'
reason: SERVICES NOT RENDERED/MDSE NOT RECVD
disputeInitiatedDate: '2024-11-01'
isReversed: false
caseTimeline:
- eventName: New
eventDate: '2024-12-25'
eventDetailText: Dispute Received.
traceId: f57ac10b-58cc-4372-a567-0e02b2c3d480
'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'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
/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'
/disputes/status-query:
post:
summary: Retrieve disputes status
operationId: fetchDisputeStatuses
tags:
- Disputes Data Retrieval
description: The consumers of this API can request the status for list of disputes.
parameters:
- 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
- $ref: '#/components/parameters/platformIdHeader'
requestBody:
description: Dispute Status Request
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/disputesStatusRequest'
examples:
Success:
value:
statusInquiryParameters:
companyIds:
- '987654'
merchantIds:
- '345686'
disputeIds:
- 9876543210
startDateTime: '2025-01-01T12:00:00Z'
endDateTime: '2025-01-02T12:00:00Z'
pagination:
cursor: cGFnZVRva2VuMTIzNDU=
pageSize: 2000
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/disputesStatusResponse'
examples:
Success:
value:
requestId: f47ac10b-58cc-4372-a567-0e02b2c3d479
disputesStatusList:
- disputeId: 9876543210
disputeStatus: UNDER_ISSUER_REVIEW
statusUpdateTimestamp: '2025-01-01T12:00:00Z'
outcome: PENDING
financialAdjustmentIndicator: false
isReversed: false
relatedFinancialItems:
- relatedFinancialItemsData:
transactionTypeCode: C
relatedItemsData: Related Items Data
traceId: f47ac10b-58cc-4372-a567-0e02b2c3d479
pagination:
cursor: cGFnZVRva2VuMTIzNDU=
'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'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
/disputes/{disputeId}/documents:
get:
summary: Get dispute doc
# --- truncated at 32 KB (89 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/jp-morgan-chase/refs/heads/main/openapi/jp-morgan-chase-dispute-management-api-openapi.yml