Sign in

v1

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

Create dispute

Create a dispute for a Zero or Full balance program. You can create a dispute for a transaction made with a Pismo-issued card (Full balance) or with another card (Zero balance). You need to pass different parameters depending on which one as noted in the parameter descriptions.

Disputes are initially created with a PENDING status. After you've uploaded all your supporting forms and evidence files, call Update dispute status and use the OPEN event to change the status to OPENED and 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 <a href="https://developers.pismo.io/events/docs/disputes-dispute-installment-creation-1">Dispute installment created</a> event.

Note: For Zero balance customers, this endpoint takes an account token - an access token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a <b>401 Unauthorized</b> message.

post/v1/networkauthorization-disputes

Headers

Authorizationstring required
Example:Bearer eyJhbGci...IUzUx

Account token - an access token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a <b>401 Unauthorized</b> message.

Request body

modalitynumber required

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)

disputed_amountnumber required

Disputed amount.

is_partialboolean required

Is partial amount chargeback? Default is false.

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

Network brand

authorization_idnumber

Related authorization ID. REQUIRED when disputed in a Full balance program or the network brand is Elo.

commentstring nullable

Client custom dispute comment.

REQUIRED for Visa partial dispute to explain why partial.

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.

first_installment_amountnumber

Amount to be disputed on first Installment chargeback.

arnstring

Acquirer reference number. REQUIRED when disputed in a Zero balance program.

transaction_datestring Date

REQUIRED when disputed in a Zero balance program. Format = yyyy-mm-dd

dispute_due_to'NR' | 'CR' | 'ND' | 'DM' | 'Q' | 'CM' | 'M' | 'CN' | 'CS' | 'OC' | 'CL' | 'TC' | 'D' | 'IAN' | 'IA' | 'IC' | 'IT' | 'ID' | 'LP' | 'P'

REQUIRED when dispute is open to Visa Collaboration (Reason code 12 and 13 and Visa network brand). Collaboration is the new name for Visa's old chargeback process, where each party has several chances to investigate and submit evidence in order to determine whether a chargeback is legitimate.<br>

NR = Merchandise/services not receive<br> CR = Cancelled recurring transaction<br> ND = Not as described<br> DM = Damaged or defective merchandise<br> Q = Quality<br> CM = Counterfeit merchandise<br> M = Misrepresentation<br> CN = Credit not processed<br> CS = Cancelled merchandise/services<br> OC = Original credit not accepted<br> CL = Non-receipt of cash<br> TC = Terms of contract (virtual account)<br> D = Duplicate<br> IAN = Incorrect account number<br> IA = Incorrect amount<br> IC = Incorrect currency<br> IT = Incorrect transaction code<br> ID = Invalid data<br> LP = Late presentment<br> P = Paid by other means<br>

For VISA, you need to fill out the collaborationQuestionnaire form object in the Create dispute form endpoint.

currency_codestring

Dispute ISO4217 currency code. Default is 986 - Brazilian real.

This is REQUIRED if you are creating a dispute in a Zero balance program.

fraud_type'0' | '1' | '2' | '3' | '4' | '5' | '6' | 'A' | 'B' | 'C' | 'D'

Fraud type:<br> 0 - Lost<br> 1 - Stolen<br> 2 - Card not received as issued (NRI)<br> 3 - Fraudulent application (cardholder never applied for the card)<br> 4 - Issuer-reported counterfeit<br> 5 - Miscellaneous<br> 6 - Fraudulent use of account number<br> A = Incorrect processing<br> B = Account or credentials takeover<br> C = Merchant misrepresentation<br> D = Manipulation of account holder<br>

document_indicatorboolean

Document submission indicator (ELO). Default is true.

airport_taxboolean

For ELO network, should dispute for airport tax be created? Default is true for ELO.

airport_tax_partialboolean

For ELO network, should airport tax be partially disputed? Default is false.

airport_tax_amountnumber

Airport tax amount to be disputed. REQUIRED if airport_tax_partial is true.

card_hashstring

Card number hash.

authorization_codestring

Authorization code

transaction_amountnumber

Transaction amount

Example request

{
  "modality": 4853,
  "disputed_amount": 10,
  "network_brand_type": "Visa",
  "authorization_id": 123,
  "comment": "Custom comment",
  "protocol": "20251128111532456",
  "metadata": "{ \"key\": \"value\"}",
  "first_installment_amount": 5,
  "arn": "0000000000539598",
  "dispute_due_to": "NR",
  "currency_code": "986",
  "document_indicator": true,
  "airport_tax_amount": 25,
  "card_hash": "XYZdd887tt",
  "authorization_code": "F0JR9H",
  "transaction_amount": 86753.09
}

Response

OK

idnumber

Dispute ID

authorization_idnumber

Network authorization ID

account_idinteger

Account ID

airport_taxboolean

Should dispute for airport tax be created? Default is true for the ELO card network.

airport_tax_partialboolean

Should airport tax be partially disputed? Default is false.

airport_tax_amountnumber

Airport tax amount to be disputed. REQUIRED if airport_tax_partial is true.

commentstring nullable

Client custom dispute comment.

REQUIRED for Visa partial dispute to explain why partial.

dispute_installment_idinteger

Dispute installment ID.

Example response

{
  "id": 48670,
  "authorization_id": 1001,
  "account_id": 6912345,
  "airport_tax_amount": 25,
  "comment": "Custom comment",
  "dispute_installment_id": 8675309,
  "reason": {
    "dispute_reason_id": 1,
    "description": "Fraudulent transaction - no cardholder authorization",
    "code": 4853,
    "initial_status": "CRIADO",
    "initial_status_pci": "EFETUADO"
  }
}