Disputes and chargebacks
Open a dispute against a transaction, attach the evidence, and cancel a case that should not have been raised.
createDisputeCase
Creates a new dispute case for a credit card transaction. Supports multiple dispute case details and DMS references. Returns the case number and related dispute transaction details.
Part of:
- Journey 02 · Managing a card product — step 1, Open and evidence a case
Headers
evrst-ptrnidCorrelation id for this request. Echo it in your own logs to trace the call through the platform.
createDisputeCase › Request Body
ChannelThree-digit code identifying the channel on behalf of which the request is made (e.g. 002 for Internet). Mandatory in every request. Used for entitlement checks, limit enforcement and audit logging. Channel codes are managed through configuration parameters and may change over time. Refer to the Channels page for the current list of valid codes.
ShadowCardNumberShadow number of the disputed card. One of four ways to name the disputed card, and at least one of them is needed: the local route refuses the request with CardInformationRequired when all four are absent. Both routes forward it, but the integration service does not pass it on to the dispute management service, so on that route it narrows nothing.
CardRefNumberCard reference number of the disputed card. One of four ways to name the disputed card, and at least one of them is needed: the local route refuses the request with CardInformationRequired when all four are absent. Only the local route forwards it; the integration route drops it.
EncryptedCardNumberEncrypted card number of the disputed card. One of four ways to name the disputed card, and at least one of them is needed: the local route refuses the request with CardInformationRequired when all four are absent. A key rather than stored data: the local route looks the card up with it and then replaces the value with the one the card service returns, and the integration route drops it.
CardNumberPlain card number of the disputed card. One of four ways to name the disputed card, and at least one of them is needed: the local route refuses the request with CardInformationRequired when all four are absent. The number itself is never stored — the case tables hold a masked form and a hash. The integration route refuses a blank one.
CaseTypeWhich side of the dispute the case is opened on. The local route accepts only the two values below and answers "Undefined Case Type" to anything else; it is stored in CMS_DIS.CASE_MAIN.IA_INDICATOR.
Values:
I— issuer sideA— acquirer side
DisputeDateRequired — Date the dispute is raised. The contract holds a non-nullable date, so leaving the field out forwards 0001-01-01 rather than today, and the local route refuses that.
A date and time as a string, in RFC 3339 form: 2026-10-16T14:30:00Z, or with an offset, 2026-10-16T17:30:00+03:00.
DisputeReasonCodeDispute reason. Use a code returned by Get Dispute Reason Def List: the local route looks the value up in that same definition table and refuses an unknown one. The codes are rows rather than constants, so they can change without a release and are not published as a fixed list.
DisputeExplanationRequired in practice — Free-text explanation of the dispute. Both routes refuse a blank one, and neither declares the field required.
ExternalCaseIdNot read on either route. The local route does not forward it, and the integration route forwards it to a service that then drops it. Set it on each entry of CreateDisputeCaseDetail instead, which is where the integration route reads it and refuses a blank.
SpecialFollowupNot read on either route, for the same reason as ExternalCaseId. The per-detail copy is the one that reaches the service, where a blank becomes N.
VipFlagNot read on either route, for the same reason as ExternalCaseId. The per-detail copy is the one that reaches the service, where a blank becomes N.
Transactions covered by the case. The integration route refuses an empty or missing list; the local route accepts the request and then fails on the first entry, because it reads the list without a null check. The local route also forwards only three fields of each entry — see the entry's own fields.
Document references to attach to the new case. Only the identifier of each entry is forwarded, on both routes.
createDisputeCase › Responses
Success.
CaseNumber and DisputeTransaction come from whichever route ran, and the facade adds nothing of its own: the card resolution, the reason code and every detail line are judged downstream.
On the local route the case row is written first and each detail line matched afterwards, and a line that matches no transaction reverses the whole case — so a failure leaves nothing behind. The dispute-transaction list is then read without a null check, so a downstream response carrying no list surfaces as a technical failure rather than as an empty one.
On the integration route a refusal arrives as a response code rather than as an exception, and the facade turns anything that is not 00 or 0 into a business error carrying the service's own message. Only the first case of CaseList is returned, and a response with an empty list is reported as case number 0.
CaseNumberThe dispute case this belongs to.
The transactions the case covers.
cancelDisputeCase
Cancels a dispute case by calling the BKM batch service with case number, channel, description, dispute transaction ID, and UTID. Returns a response indicating whether the cancellation was successful.
Part of:
- Journey 02 · Managing a card product — step 2, Track and manage
Headers
evrst-ptrnidCorrelation id for this request. Echo it in your own logs to trace the call through the platform.
cancelDisputeCase › Request Body
ChannelThree-digit code identifying the channel on behalf of which the request is made (e.g. 002 for Internet). Mandatory in every request. Used for entitlement checks, limit enforcement and audit logging. Channel codes are managed through configuration parameters and may change over time. Refer to the Channels page for the current list of valid codes.
CaseNumberRequired — Case being withdrawn. The contract holds a non-nullable integer, so leaving the field out sends 0, and the local route refuses that.
DisputeTransactionIdDispute transaction within the case that is being withdrawn. Either this or UTID identifies the line: the local route matches on DISPUTE_TRANSACTION_ID = :id OR UTID = :utid and refuses the request only when both are absent. The contract holds a non-nullable integer, so leaving it out sends 0.
UTIDUnique transaction identifier of the disputed transaction, as an alternative to DisputeTransactionId.
DescriptionFree-text reason for the withdrawal, written to the case history. It is truncated rather than refused: the local route stores SUBSTR(:CUSTOMER_EXPLANATION, 1, 200), so anything past 200 characters is dropped silently.
cancelDisputeCase › Responses
Success.
On the local route the facade copies only isSuccessful, and that flag is the count of rows the update touched — a case or transaction that does not match leaves it false, still with HTTP 200, so the flag has to be read. Nothing else of the clearing response reaches the caller.
On the integration route isSuccessful is always true when the call returns at all: a refusal arrives as a response code and is raised as a business error instead.
isSuccessfulWhether the operation did what it was asked to. A false here arrives with HTTP 200, so it has to be read rather than inferred from the status.
addDocumentByCaseNumber
Adds one or more document references to a case number in the BKM batch system. It requires the channel, case number, and a list of DMS references.
Part of:
- Journey 02 · Managing a card product — step 1, Open and evidence a case
Headers
evrst-ptrnidCorrelation id for this request. Echo it in your own logs to trace the call through the platform.
addDocumentByCaseNumber › Request Body
ChannelThree-digit code identifying the channel on behalf of which the request is made (e.g. 002 for Internet). Mandatory in every request. Used for entitlement checks, limit enforcement and audit logging. Channel codes are managed through configuration parameters and may change over time. Refer to the Channels page for the current list of valid codes.
CaseNumberRequired — Case the documents are attached to. The contract holds a non-nullable integer, so leaving the field out sends 0.
ExternalCaseIdThe case identifier in the external dispute system. Only the integration route reads it; the local route attaches by CaseNumber alone.
ExternalDocumentIdThe document identifier in the external dispute system. Only the integration route reads it.
Documents to attach. Only the identifier of each entry is forwarded, and a null entry in the array is forwarded as a reference with no identifier rather than skipped.
addDocumentByCaseNumber › Responses
Success.
The operation returns no body, so a 200 states only that the call completed without an exception — on the local route it does not confirm that any document was attached, because nothing of the clearing service's outcome is reported.
getDisputeList
Retrieves a list of dispute transactions for a given card or customer. Filters can be applied by card number, card reference number, case number, customer number, dispute transaction ID, shadow card number, encrypted card number, or UTID. Returns detailed information for each dispute including case number, dispute transaction ID, dispute amount and currency, dispute date and reason code, transaction details (amount, currency, date, status, authorization number, MCC, merchant name), source network, and associated customer/card information.
Part of:
- Journey 02 · Managing a card product — step 2, Track and manage
Headers
evrst-ptrnidCorrelation id for this request. Echo it in your own logs to trace the call through the platform.
getDisputeList › Request Body
CaseNumberRestrict the search to one case. The contract holds a non-nullable integer, so a search that does not use this criterion sends 0.
DisputeTransactionIdRestrict the search to one dispute transaction. The contract holds a non-nullable integer, so a search that does not use this criterion sends 0.
UTIDRestrict the search to one unique transaction identifier.
CustomerNumberRestrict the search to one customer. The contract holds a non-nullable integer, so a search that does not use this criterion sends 0.
ShadowCardNumberRestrict the search to one card, by shadow number.
CardRefNumberRestrict the search to one card, by card reference number.
EncryptedCardNumberRestrict the search to one card, by encrypted card number. The facade does not decrypt it.
CardNumberRestrict the search to one card, by plain card number.
ExternalCaseIdRestrict the search to one case in the external dispute system. Only the integration route reads it.
getDisputeList › Responses
Success.
Every criterion is forwarded as sent, including the numeric ones left at 0, and none of them is required — a request with no criteria at all is a valid request.
When the service behind the route answers with nothing, or with a response holding no dispute list, DisputeTransaction is absent from the body rather than an empty array, so a search that matches nothing is indistinguishable from a downstream miss.
The transactions the case covers.
getDisputeReasonDefList
Retrieves a list of all dispute reason definitions in the system. Each item includes the dispute reason code and its corresponding description. No input parameters are required.
Part of:
- Journey 02 · Managing a card product — step 1, Open and evidence a case
Headers
evrst-ptrnidCorrelation id for this request. Echo it in your own logs to trace the call through the platform.
getDisputeReasonDefList › Responses
Success.
The reason codes createDisputeCase validates against, read from the definition table the clearing service holds. They are rows rather than constants, so the list can change without a release — which is why the codes are not published as a fixed enumeration on DisputeReasonCode and this operation exists instead.