Sign in

v1

latestOpenAPI 3.1.0Copyright Pismo2026-07-247702,7523.1 MB
Disputes

Update dispute status

Change a dispute's status via an event. After creating a dispute and uploading all necessary forms, reports, and evidence files, send the event OPEN to officially begin the dispute process with the network.

For more information on events and statuses, refer to the <a href="https://developers.pismo.io/pismo-docs/docs/disputes-state-machine">Disputes state machine</a>.

This endpoint generates a Dispute status changed event.

post/v1/disputes/{disputeId}/event

Path parameters

disputeIdnumber required

Dispute ID

Request body

event'POST' | 'UPDATE' | 'DELETE' required

Event performed in the request

reasonstring required

Status change reason.

dispute_installment_idnumber

Dispute installment ID. If not passed, the first Installment is used.

memostring

Enter memo pertaining to the case. REQUIRED for ELO dispute. Also REQUIRED when event = SEND_PRE_ARBITRATION and network is Mastercard. Maximum length = 13000 chars.

merchant_namestring

Merchant name - 100 characters maximum. REQUIRED only for disputes without transaction and event = SEND_PRE_ARBITRATION and network is Mastercard.

updated_chargeback_reason_codenumber

Each card network, such as Visa or Mastercard, defines and maintains their own unique set of reason codes, which banks that issue credit and debit cards under their brands apply to disputes. Here's a reason code quick reference for the major credit card networks.

For Visa, this would be either 10 (fraud - card present), 11 (authorization), 12 (processing error), or 13 (consumer dispute).

For more infomation, refer to the Visa or Mastercard chargeback quides.

For example - 4853 (Mastercard - cardholder dispute), 12 (Visa - processing error) or 72 (ELO - denied authorization)

change_reason_code_reasonstring

Explanation for changing the reason code, if that's what you are doing - 1000 characters maximum. REQUIRED if updated_chargeback_reason_code is passed, event = SEND_PRE_ARBITRATION and network is Mastercard.

pre_arb_is_partialboolean

Pre-arbitration is for a partial amount and not the full amount? Used when event = SEND_PRE_ARBITRATION.

pre_arb_currency_codestring

ISO 4217 3-letter currency code, for example, USD (United States) or BRL (Brazilian Real). REQUIRED if pre_arb_is_partial = true and event = SEND_PRE_ARBITRATION.

justify_not_accepted_fullystring

Explanation for asking for full or partial amount - 10000 characters maximum. REQUIRED if pre_arb_is_partial = true or event = DECLINE_PRE_ARBITRATION.

pre_arb_amountnumber

Pre-arbitration amount. REQUIRED if pre_arb_is_partial = true and event = SEND_PRE_ARBITRATION.

is_dispute_migratedboolean

Is dispute migrated? Default is false.

Example request

{
  "event": "POST",
  "reason": "Disputed by account holder.",
  "dispute_installment_id": 234,
  "memo": "Example memo",
  "merchant_name": "Acme Goods",
  "updated_chargeback_reason_code": 4853,
  "pre_arb_currency_code": "BRL",
  "justify_not_accepted_fully": "Partial refund based on already being used",
  "pre_arb_amount": 18.36
}

Response

OK

idnumber

Dispute ID

org_idstring

Organization ID

account_idinteger

Account ID

authorization_idnumber

Authorization ID.

commentstring nullable

Client custom dispute comment.

REQUIRED for Visa partial dispute to explain why partial.

dispute_reasonnumber

Each card network, such as Visa or Mastercard, defines and maintains their own unique set of reason codes, which banks that issue credit and debit cards under their brands apply to disputes. Here's a reason code quick reference for the major credit card networks.

For Visa, this would be either 10 (fraud - card present), 11 (authorization), 12 (processing error), or 13 (consumer dispute).

For more infomation, refer to the Visa or Mastercard chargeback quides.

For example - 4853 (Mastercard - cardholder dispute), 12 (Visa - processing error) or 72 (ELO - denied authorization)

modalitynumber

Dispute modality - legacy term for reason code to file the dispute.

dispute_status'OPENED' | 'PENDING' | 'CANCELED' | 'FAILED' | 'CHARGEBACK_REJECTED' | 'CHARGEBACK_CREATED' | 'CHARGEBACK_ACCEPTED' | 'CHARGEBACK_CLOSED' | 'SECOND_PRESENTMENT' | 'PRE_ARBITRATION_OPENED' | 'PRE_ARBITRATION_ACCEPTED' | 'PRE_ARBITRATION_DECLINED' | 'PRE_ARBITRATION_RECALL' | 'PRE_ARB_ALLOCATION_OPENED' | 'FAILED_PRE_ARBITRATION' | 'PRE_ARB_ALLOCATION_ACCEPTED' | 'PRE_ARB_ALLOCATION_DECLINED' | 'PRE_ARB_ALLOCATION_RECALLED' | 'FAILED_DECLINE_PRE_ARB' | 'FAILED_ACCEPT_PRE_ARB' | 'FAILED_ON_CLOSE' | 'EXPIRED' | 'ISSUER_LOSS' | 'MIGRATION' | 'FAILED_MIGRATION'

Dispute status enums.

dispute_status_group'OPEN' | 'APPROVED' | 'DENIED' | 'CARDNETWORK_CHARGEBACK' | 'ANALYSING' | 'CARDNETWORK_SECOND_PRESENTMENT' | 'FAILED' | 'CARDNETWORK_PREARBITRATION' | 'RESEND' | 'LOSS' | 'WON' | 'REJECTED' | 'FAILED_PROCESSED'

Group status enums

created_atstring date-time

Datetime program calendar strategy was created. Format = YYYY-MM-DDTHH:MM:SS:MM.

updated_atstring date

Dispute last updated date, format = yyyy-mm-dd.

created_at_utcstring date-time

Dispute created in UTC date/time.

updated_at_utcstring

When dispute updated in UTC date/time.

timelinestring nullable

Client custom timeline information.

protocolstring

Client custom protocol ID. This is primarily for you to internally identify a request. If not provided, Pismo creates a CID (correlation ID) field for this purpose.

metadatastring

Any data object with key/value pairs. No limit on length.

Note: This field must not be used to send Personally Identifiable Information (PII), Payment Card Industry (PCI) data, or any sensitive/regulated information. Metadata fields are intended for operational, non-sensitive data only. For sensitive data, use the specific parameters designed for that purpose. For more information, refer to Get started with Pismo APIs.

disputed_amountnumber

Disputed amount.

is_networkboolean

Does dispute have a network authorization?

is_dispute_migratedboolean

Has this dispute been migrated to the Pismo platform?

reversal_idnumber

Event-generated reversal ID

network_return_reason_codestring

Network reason code.

network_brand_type'Visa' | 'Mastercard' | 'Elo'

Network brand

transaction_datestring

Transaction date, format = yyyy-mm-dd hh:mm:ss

transaction_amountnumber

Transaction amount

currency_codestring

ISO-4217 code for transaction currency. For example, 986 = Brazilian real.

Example response

{
  "id": 48670,
  "org_id": "TN-cc8f8b89-233a-4582-9f36-63ee85278d6d",
  "account_id": 6912345,
  "authorization_id": 4352243,
  "comment": "Custom comment",
  "dispute_reason": 4853,
  "modality": 4855,
  "dispute_status": "PENDING",
  "dispute_status_group": "OPEN",
  "created_at": "2024-09-12T16:46:16.43663522",
  "updated_at": "2021-02-22",
  "created_at_utc": "2021-02-21T22:51:43.000000000Z",
  "updated_at_utc": "2022-10-13T19:56:010000000Z",
  "timeline": "{ \"data\": \"test\"}",
  "protocol": "20251128111532456",
  "metadata": "{ \"key\": \"value\"}",
  "disputed_amount": 10,
  "is_network": true,
  "reversal_id": 123,
  "network_return_reason_code": "4853",
  "network_brand_type": "Visa",
  "transaction_date": "2022-08-04 14:26:20",
  "transaction_amount": 86753.09,
  "currency_code": "986"
}