Respond to a dispute
How to respond to a dispute
After you have searched for your disputes with GET /disputes (you can include the status query parameter to filter to only disputes requiring action). You can then retrieve the individual Dispute details with GET /disputes/{id} using the id found in the search results.
Inside the dispute object you will find an events array. This shows you the different events that can be actioned and presents you with a set of allowedActions for you to respond to the dispute in the appropriate way.
Example events array on a single dispute
"events": [
{
"id": "T-20210720610032",
"type": "DISPUTE",
"reversal": false,
"partial": false,
"received": "2019-08-24",
"networkSettlementAmount": 20.99,
"networkSettlementCurrency": "EUR",
"merchantFundingAmount": 20.99,
"merchantFundingCurrency": "EUR",
"visaIssuerResponse": "FULL",
"visaIssuerReason": "The cardholder MR D HOLLIDAY reaffirms that he did not participate and he did not authorise the transaction",
"visaPreArbResponse": "FULL",
"allowedActions": [
{
"code": "086",
"description": "Accept",
"extendedDescription": "Merchant accepts the dispute at the Visa Allocation Pre-Arbitration stage",
"status": "AVAILABLE",
"requiredDataFields": [
{
"name": "evidence",
"description": "Evidence such as photographs or emails, to prove a link between the person receiving the merchandise or services and the cardholder, or to prove that the cardholder disputing the transaction is in possession of the merchandise and/or is using the services. We support files formatted as TIFF, PDF, DOCX and DOC",
"notes": "This is a string with a minimum length of 0 and a maximum length of 10000",
"type": "string",
"format": "binary",
"example": "I am declining this dispute because i have already refunded the cardholder",
"minLength": 0,
"maxLength": 0,
"pattern": "string"
}
]
}
],
"previousActions": [
{
"id": "20210720610032",
"code": "086",
"description": "Accept",
"extendedDescription": "Merchant accepts the dispute at the Visa Allocation Pre-Arbitration stage",
"status": "AVAILABLE",
"modified": "2019-08-24T14:15:22Z",
"modifiedBy": "Bob"
}
],
"reasonCode": "10",
"reasonDescription": "CBK: Fraud",
"visaConditionCode": "1",
"visaConditionDescription": "EMV Liability Shift Counterfeit Fraud"
}
]
Each action that can be performed will have:
- Code
- Description & Extended Description
- Status
- Required Data Fields to perform this Action
By using the required data fields, tcn and code in the Execute an Action endpoint as part of a multipart/form-data request you can perform this particular action.
Each required data field has metadata to allow you to build your own processing and parsing as you collect this information and form the request. This follows the data formatting standards defined in OpenAPI specifications by providing type, format, example, minLength, maxLength and pattern fields.
Let's look at exactly how this will work in practice:
- Search for disputes
- Retrieve a single dispute by ID
- Make note of the
tcnvalue and theidfor the dispute. You will need these both later - Look through the
eventsarray to see which events haveallowedActions - Make a note of the
codein the action you wish to perform. This code is required when using the Execute an Action endpoint - Decide on the action you wish to perform and using the required data fields against that action create and send your Execute an Action endpoint request including the
tcnandcodeyou found earlier
curl --location --request POST '/disputes/{disputeId}/events/{eventId}/actions' \
--header 'Api-Key: ' \
--header 'Content-Type: multipart/form-data' \
--form 'code="086"' \
--form 'tcn="2345678"' \
--form 'evidence=@"evidence1.pdf"' \
Action Examples
Let's look at a more complicated example now.
A merchant declining a Visa allocation dispute in pre-arbitration with reason "Proof of Transaction"
When responding to this type of dispute, "Proof of Transaction" means to provide compelling evidence back to Visa to defend the dispute. Compelling evidence is the act of providing proof the cardholder participated in the transaction, received the goods or services, or benefited from the transaction. The allowedActions would look like this:
"allowedActions": [
{
"code": "086",
"description": "Decline with proof of transaction and proof of delivery",
"extendedDescription": "Proof of delivery can be provided where Address Validation Service (AVS) was used to identify cardholder's address",
"status": "AVAILABLE",
"requiredDataFields": [
{
"name": "evidence",
"description": "Evidence such as photographs or emails, to prove a link between the person receiving the merchandise or services and the cardholder, or to prove that the cardholder disputing the transaction is in possession of the merchandise and/or is using the services. We support files formatted as TIFF, PDF, DOCX and DOC",
"notes": "This is a document used in evidence as part of the dispute. Maximum supported file size is 5MB",
"type": "string",
"format": "binary",
"example": "",
"minLength": 0,
"maxLength": 0,
"pattern": ""
},
{
"name": "name",
"description": "Customer Delivery Name",
"notes": "This is the name the customer used for delivery",
"type": "string",
"format": "",
"example": "Mr Dave Holliday",
"minLength": 1,
"maxLength": 50,
"pattern": ""
},
{
"name": "address1",
"description": "Address Line 1",
"notes": "This is the address the customer used for delivery",
"type": "string",
"format": "",
"example": "123 API Street",
"minLength": 1,
"maxLength": 50,
"pattern": ""
},
{
"name": "address2",
"description": "Address Line 2",
"notes": "This is the address the customer used for delivery",
"type": "string",
"format": "",
"example": "ABC Precinct",
"minLength": 1,
"maxLength": 50,
"pattern": ""
},
{
"name": "city",
"description": "City",
"notes": "This is the city the customer used for delivery",
"type": "string",
"format": "",
"example": "Oxford",
"minLength": 1,
"maxLength": 50,
"pattern": ""
},
{
"name": "postalCode",
"description": "Postal Code",
"notes": "This is the postal code the customer used for delivery",
"type": "string",
"format": "",
"example": "GL4 8DL",
"minLength": 1,
"maxLength": 9,
"pattern": ""
},
{
"name": "state",
"description": "State or Region",
"notes": "This is the state or region the customer used for delivery",
"type": "string",
"format": "",
"example": "ox",
"minLength": 2,
"maxLength": 2,
"pattern": ""
},
{
"name": "country",
"description": "Country",
"notes": "This is the country the customer used for delivery in ISO 3166 format",
"type": "string",
"format": "",
"example": "GBR",
"minLength": 3,
"maxLength": 3,
"pattern": ""
},
{
"name": "shippingCompanyName",
"description": "Shipping Company Name",
"notes": "This is the name of the shipping company used for delivery. Examples such as Fedex, DHL, Royal Mail etc",
"type": "string",
"format": "",
"example": "DHL",
"minLength": 1,
"maxLength": 50,
"pattern": ""
},
{
"name": "trackingNumber",
"description": "Tracking Number",
"notes": "This is the tracking number for this delivery",
"type": "string",
"format": "",
"example": "1234567",
"minLength": 1,
"maxLength": 50,
"pattern": ""
}
]
}
]
You would then use the Execute an Action endpoint to perform this action with the relevant data.
curl --location --request POST '/disputes/{disputeId}/events/{eventId}/actions' \
--header 'Api-Key: ' \
--header 'Content-Type: multipart/form-data' \
--form 'code="086"' \
--form 'tcn="2345678"' \
--form 'evidence=@"evidence1.pdf"' \
--form 'name="Dave Holliday"' \
--form 'address1="123 API Street"' \
--form 'address2="ABC Lane"' \
--form 'city="Oxford"' \
--form 'postalCode="GL4 8DL"' \
--form 'state="OX"' \
--form 'shippingCompanyName="Royal Mail"' \
--form 'trackingNumber="12345678"'
Updated about 1 year ago
