# 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](https://developers.pismo.io/pismo-docs/reference/post-v1-disputes-disputeid-event) 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 Disputes state machine.
This endpoint generates a Dispute installment created 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 401 Unauthorized message.
# OpenAPI definition
```json
{
"openapi": "3.0.1",
"info": {
"title": "Card issuing - Disputes",
"version": "1.0.0",
"description": "Disputes API endpoints",
"contact": {
"name": "API Support",
"url": "https://developers.pismo.io/support/"
},
"license": {
"name": "Copyright Pismo"
}
},
"servers": [
{
"url": "https://sandbox.pismolabs.io/disputes",
"description": "Sandbox API server for testing"
}
],
"security": [
{
"BearerAuth": []
}
],
"tags": [
{
"name": "Disputes",
"description": "Endpoints to create and manage disputes"
}
],
"components": {
"parameters": {
"AuthHeader": {
"in": "header",
"name": "Authorization",
"required": true,
"description": "Account token - an access token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a 401 Unauthorized message.",
"schema": {
"type": "string",
"example": "Bearer eyJhbGci...IUzUx"
}
}
},
"schemas": {
"AccountID": {
"type": "number",
"description": "Pismo account ID",
"example": 577830
},
"AuthorizationCode": {
"type": "string",
"description": "Authorization code",
"example": "F0JR9H"
},
"TransactionAmount": {
"type": "number",
"description": "Transaction amount",
"example": 86753.09
},
"disputeDueTo": {
"type": "string",
"description": "**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.
\n\n`NR` = Merchandise/services not receive
\n`CR` = Cancelled recurring transaction
\n`ND` = Not as described
\n`DM` = Damaged or defective merchandise
\n`Q` = Quality
\n`CM` = Counterfeit merchandise
\n`M` = Misrepresentation
\n`CN` = Credit not processed
\n`CS` = Cancelled merchandise/services
\n`OC` = Original credit not accepted
\n`CL` = Non-receipt of cash
\n`TC` = Terms of contract (virtual account)
\n`D` = Duplicate
\n`IAN` = Incorrect account number
\n`IA` = Incorrect amount
\n`IC` = Incorrect currency
\n`IT` = Incorrect transaction code
\n`ID` = Invalid data
\n`LP` = Late presentment
\n`P` = Paid by other means
\n\nFor VISA, you need to fill out the `collaborationQuestionnaire` form object in the [Create dispute form](https://developers.pismo.io/pismo-docs/reference/post-v1-disputes-disputeid-forms) endpoint.\n",
"enum": [
"NR",
"CR",
"ND",
"DM",
"Q",
"CM",
"M",
"CN",
"CS",
"OC",
"CL",
"TC",
"D",
"IAN",
"IA",
"IC",
"IT",
"ID",
"LP",
"P"
],
"example": "NR"
},
"reasonCode": {
"type": "number",
"description": "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](https://www.chargebackgurus.com/blog/a-definitive-guide-to-chargeback-reason-codes-by-card-network#chargback-reason-code-quick-reference-guide) for the major credit card networks.\n\nFor Visa, this would be either `10` (fraud - card present), `11` (authorization), `12` (processing error), or `13` (consumer dispute).\n\nFor more infomation, refer to the [Visa](https://usa.visa.com/dam/VCOM/global/support-legal/documents/chargeback-management-guidelines-for-visa-merchants-vbs-19-may-16-%20v2.pdf) or [Mastercard](https://www.mastercard.us/content/dam/public/mastercardcom/na/global-site/documents/chargeback-guide.pdf) chargeback quides.\n\nFor example - `4853` (Mastercard - cardholder dispute), `12` (Visa - processing error) or `72` (ELO - denied authorization)\n",
"example": 4853
},
"DisputeInstallmentId": {
"type": "integer",
"description": "Dispute installment ID.",
"example": 8675309
},
"DisputeRequestNetwork": {
"title": "DisputeRequest Network",
"type": "object",
"description": "Request used to file a Dispute over a network authorization.",
"x-examples": {},
"required": [
"disputed_amount",
"modality",
"is_partial",
"network_brand_type"
],
"properties": {
"modality": {
"$ref": "#/components/schemas/reasonCode"
},
"disputed_amount": {
"type": "number",
"example": 10,
"description": "Disputed value"
},
"is_partial": {
"type": "boolean",
"description": "Open partial dispute? Default is `false`.",
"default": false
},
"network_brand_type": {
"type": "string",
"description": "Network brand",
"enum": [
"Visa",
"Mastercard",
"Elo"
],
"example": "Visa"
},
"authorization_id": {
"type": "number",
"example": 123,
"description": "Related authorization ID. **REQUIRED** when disputed in a Full balance program or the network brand is Elo."
},
"comment": {
"type": "string",
"example": "Custom comment",
"description": "Client custom dispute comment. **REQUIRED** for Visa partial dispute to explain why partial.",
"maxLength": 5000
},
"protocol": {
"type": "string",
"example": "client-custom-protocol-identifier",
"description": "Client custom protocol identifier. ID for customer's internal record-keeping.",
"maxLength": 500
},
"metadata": {
"type": "object",
"description": "Can be used for caller's dispute information and process. Objects and name-value pairs."
},
"first_installment_amount": {
"type": "number",
"example": 5,
"description": "Amount to be disputed on first Installment chargeback."
},
"arn": {
"type": "string",
"example": "0000000000539598",
"description": "Acquirer reference number. **REQUIRED** when disputed in a Zero balance program.",
"maxLength": 255
},
"transaction_date": {
"type": "string",
"format": "Date",
"description": "**REQUIRED** when disputed in a Zero balance program. Format = yyyy-mm-dd"
},
"dispute_due_to": {
"$ref": "#/components/schemas/disputeDueTo"
},
"currency_code": {
"type": "string",
"description": "Dispute ISO4217 currency code. Default is 986 - Brazilian real.\n\nThis is **REQUIRED** if you are creating a dispute in a Zero balance program.\n",
"example": "986"
},
"fraud_type": {
"type": "string",
"description": "Fraud type:
\n`0` - Lost
\n`1` - Stolen
\n`2` - Card not received as issued (NRI)
\n`3` - Fraudulent application (cardholder never applied for the card)
\n`4` - Issuer-reported counterfeit
\n`5` - Miscellaneous
\n`6` - Fraudulent use of account number
\n`A` = Incorrect processing
\n`B` = Account or credentials takeover
\n`C` = Merchant misrepresentation
\n`D` = Manipulation of account holder
\n",
"enum": [
"0",
"1",
"2",
"3",
"4",
"5",
"6",
"A",
"B",
"C",
"D"
]
},
"document_indicator": {
"type": "boolean",
"description": "Document submission indicator (ELO). Default is `true`.",
"default": true,
"example": true
},
"airport_tax": {
"type": "boolean",
"description": "For ELO network, should dispute for airport tax be created? Default is `true` for ELO.",
"example": false
},
"airport_tax_partial": {
"type": "boolean",
"description": "For ELO network, should airport tax be partially disputed? Default is `false`.",
"default": false,
"example": false
},
"airport_tax_amount": {
"type": "number",
"description": "Airport tax amount to be disputed. **REQUIRED** if `airport_tax_partial` is `true`.",
"example": 25
},
"card_hash": {
"type": "string",
"description": "Card number hash.",
"example": "XYZdd887tt"
},
"authorization_code": {
"$ref": "#/components/schemas/AuthorizationCode"
},
"transaction_amount": {
"$ref": "#/components/schemas/TransactionAmount"
}
}
},
"DisputeNetworkResponse": {
"title": "DisputeNetworkResponse",
"description": "Dispute respnse from Network",
"type": "object",
"properties": {
"id": {
"type": "number",
"example": 42,
"description": "Dispute ID."
},
"authorization_id": {
"type": "number",
"example": 1001,
"description": "Network authorization ID"
},
"account_id": {
"$ref": "#/components/schemas/AccountID"
},
"airport_tax": {
"type": "boolean",
"description": "Should dispute for airport tax be created? Default is `true` for the ELO card network.",
"example": false
},
"airport_tax_partial": {
"type": "boolean",
"description": "Should airport tax be partially disputed? Default is `false`.",
"default": false,
"example": false
},
"airport_tax_amount": {
"type": "number",
"description": "Airport tax amount to be disputed. **REQUIRED** if `airport_tax_partial` is `true`.",
"example": 25
},
"comment": {
"type": "string",
"example": "Dispute comment.",
"description": "Custom dispute comment."
},
"dispute_installment_id": {
"$ref": "#/components/schemas/DisputeInstallmentId"
},
"reason": {
"type": "object",
"description": "Pismo's reason object.",
"properties": {
"dispute_reason_id": {
"type": "number",
"example": 1,
"description": "Reason ID."
},
"description": {
"type": "string",
"example": "Fraudulent transaction - no cardholder authorization",
"description": "Reason description."
},
"code": {
"$ref": "#/components/schemas/reasonCode"
},
"initial_status": {
"type": "string",
"example": "CRIADO"
},
"initial_status_pci": {
"type": "string",
"example": "EFETUADO"
},
"is_fraud": {
"type": "boolean",
"description": "Is fraud?"
}
}
}
},
"x-examples": {
"Dispute created": {
"id": 42,
"authorization_id": 1001,
"account_id": 1000101,
"comment": "Dispute comment",
"reason": {
"dispute_reason_id": 1,
"description": "Fraudulent transaction - no cardholder authorization.",
"code": 4837,
"initial_status": "CRIADO",
"initial_status_pci": "EFETUADO",
"is_fraud": true
}
}
}
}
},
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Account access token. Tokens can expire quickly, which can result in an \"Unauthorized\" error.",
"bearerFormat": "JWT"
}
},
"responses": {
"400BadRequest": {
"description": "Bad Request"
},
"401Unauthorized": {
"description": "Unauthorized. Invalid or missing access token."
},
"422UnprocessableEntity": {
"description": "Unprocessable entity"
},
"500InternalServerError": {
"description": "Internal server error"
}
}
},
"paths": {
"/v1/networkauthorization-disputes": {
"post": {
"summary": "Create dispute",
"operationId": "post-v1-networkauthorization-disputes",
"description": "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.\n\nDisputes are initially created with a `PENDING` status. After you've uploaded all your supporting forms and evidence files, call [Update dispute status](https://developers.pismo.io/pismo-docs/reference/post-v1-disputes-disputeid-event) and use the `OPEN` event to change the status to `OPENED` and begin the dispute process with the network.\n\nFor more information on events and statuses, refer to the Disputes state machine.\n\nThis endpoint generates a Dispute installment created event.\n\n**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 401 Unauthorized message.\n",
"tags": [
"Disputes"
],
"parameters": [
{
"$ref": "#/components/parameters/AuthHeader"
}
],
"requestBody": {
"description": "Dispute data",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DisputeRequestNetwork"
},
"examples": {
"Create a dispute over a multiple Installment authorization with success": {
"value": {
"authorization_id": 123,
"modality": 123,
"comment": "Custom comment",
"protocol": "client-custom-protocol-identifier",
"disputed_amount": 10,
"metadata": {},
"is_partial": true,
"first_installment_amount": 5,
"arn": "0000000000539598",
"network_brand_type": "Mastercard",
"currency_code": "986",
"fraud_type": "1"
}
},
"Create a dispute without network authorization": {
"value": {
"modality": 123,
"comment": "Custom comment",
"protocol": "client-custom-protocol-identifier",
"disputed_amount": 10,
"metadata": {},
"is_partial": true,
"first_installment_amount": 5,
"arn": "0000000000539598",
"network_brand_type": "Mastercard",
"transaction_date": "yyyy-MM-dd",
"currency_code": "986",
"fraud_type": "2"
}
},
"Create a dispute in Visa Collaboration flux": {
"value": {
"authorization_id": 123,
"modality": 13,
"comment": "Custom comment",
"protocol": "client-custom-protocol-identifier",
"disputed_amount": 10,
"metadata": {},
"is_network": true,
"is_partial": false,
"network_brand_type": "Visa",
"dispute_due_to": "NR",
"currency_code": "986",
"fraud_type": "2"
}
},
"Create a dispute in Elo with card invalid": {
"value": {
"modality": 77,
"disputed_amount": 86753.09,
"comment": "Custom comment",
"protocol": "client-custom-protocol-identifier",
"is_network": true,
"is_partial": false,
"network_brand_type": "Elo",
"arn": "0000000000539598",
"transaction_date": "2023-09-05",
"transaction_amount": 210,
"authorization_code": "123456",
"card_hash": "XYZ"
}
}
}
},
"application/xml": {
"schema": {
"type": "object",
"properties": {}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DisputeNetworkResponse"
},
"examples": {
"Dispute created": {
"value": {
"id": 42,
"authorization_id": 1001,
"account_id": 1000101,
"comment": "Dispute comment",
"reason": {
"dispute_reason_id": 1,
"description": "Fraudulent transaction - no cardholder authorization",
"code": 4837,
"initial_status": "CRIADO",
"initial_status_pci": "EFETUADO",
"is_fraud": true
}
}
},
"Dispute created without authorization": {
"value": {
"id": 1,
"account_id": 4,
"comment": "Simulação para Abertuda de Disputa - Sem Authotization",
"reason": {
"dispute_reason_id": 10,
"description": "Fraudulent transaction - no cardholder authorization",
"code": 4837,
"initial_status": "CRIADO",
"initial_status_pci": "EFETUADO",
"is_fraud": false
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"422": {
"$ref": "#/components/responses/422UnprocessableEntity"
},
"500": {
"$ref": "#/components/responses/500InternalServerError"
}
}
}
}
}
}
```