PIpismo
Disputes

Update dispute

Update one or more dispute fields. Parameters that are not passed are not updated.

Note: You can only update a dispute if its group status is OPEN, FAILED, DENIED or MIGRATION. Refer to the Dispute state machine for more information.

put/v1/disputes/{disputeId}

Request

  • Base URL
    https://sandbox.pismolabs.io/disputes
  • URL
    https://sandbox.pismolabs.io/disputes/v1/disputes/{disputeId}
  • Auth
    HTTP bearer

Path parameters

disputeIdnumber required

Dispute ID

Request body

disputed_amountnumber

Disputed amount.

currency_codestring

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

Note: Only allowed if you are updating a dispute in a Zero balance program.

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)

commentstring nullable

Client custom dispute comment.

REQUIRED for Visa partial dispute to explain why partial.

first_installment_amountnumber

Amount to be updated on first installment chargeback.

stop_automated_installmentboolean

Stop automated dispute installment control. If an issuer opens a dispute for a transaction that has more than one installment, with installments that can still be posted, the issuer will need to open a dispute for subsequent installments as well. With automated dispute installment control, once you open a chargeback for the first installment, the same information can be used for subsequent transaction installments. Default = false.

transaction_amountnumber

Transaction amount.

Note: Only allowed if you are updating a dispute in a Zero balance program.

arnstring

Acquirer reference number for first installment

Note: Only allowed if you are updating a dispute in a Zero balance program.

transaction_datestring

Transaction date. Format = yyyy-mm-dd

Note: Only allowed if you are updating a dispute in a Zero balance program.

Example request

{
  "disputed_amount": 10,
  "currency_code": "986",
  "reason_code": 4853,
  "comment": "Custom comment",
  "first_installment_amount": 86753.09,
  "stop_automated_installment": true,
  "transaction_amount": 86753.09,
  "arn": "73669599903",
  "transaction_date": "2025-09-23"
}

Response

OK

idnumber

Dispute ID

org_idstring

Organization/tenant ID.

account_idnumber

Pismo 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

Created at datetime, format = yyyy-mm-dd hh:mm:ss"

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.

metadataMetadata

Can be used for caller's dispute information and process. Objects and name-value pairs.

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-34778262-f4f0-464d-b4c6-a14exxxxxxxx",
  "account_id": 577830,
  "authorization_id": 4352243,
  "comment": "Custom comment",
  "dispute_reason": 4853,
  "modality": 4855,
  "dispute_status": "PENDING",
  "dispute_status_group": "OPEN",
  "created_at": "2024-10-18 11:21:45",
  "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": {
    "field1": "value",
    "field2": "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"
}

Changes

No recorded changes to this operation across all 1 revision of this API.