Guides

Submit Dispute Response

Suggest Edits

This guide shows you how to use the Dispute Management API resource to submit a dispute response. See Submit Dispute Response in API Reference for field definitions.

Please note:

  • You can only use API to respond to the following disputes:
    • First-time disputes for Visa, Mastercard, Discover, and American Express
    • Retrieval disputes for Visa, Mastercard, Discover, and American Express
  • You are expected to manage subsequent dispute types through the Maast Manager portal.
  • To accept a first-time or pre-arbitration dispute via API, see the Accept Dispute guide.
  • See the Dispute Types table in Dispute Conventions for more information on dispute types.
  • Before submitting a response, you should understand the time frame and supporting documentation requirements.

See the Dispute Management Guide in Additional Features for information on how to handle disputes. If you wish to use API to manage disputes, please contact Maast Support first.


Prerequisites

  1. Do the following to get your ID for disputes:
    • If you are an individual merchant: Follow the steps in Get Started to create a sandbox account and get a sandbox security key and merchant ID. Use the Authentication guide to generate your API token.
    • If you are a dispute vendor: Email [email protected] and provide either your Maast merchant ID (MID) or your dispute vendor name.
  2. Follow the steps in Create Dispute Data to create a test dispute case and save its control number (rec_id).

Implement

Write a POST request. For the request endpoint, include the dispute's control number (the rec_id value) between dispute/ and /respond. The resulting endpoint is /platform/dispute/{rec_id}/respond, where {rec_id} is replaced with the control number. See the sample code below:

curl --request POST \
     --url https://api-test.maast.com/platform/dispute/393435800000003/respond \
     --header 'accept: application/json' \
     --header 'authorization: Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz' \
     --header 'content-type: multipart/form-data'

For Retrieval Requests

If you are responding to a retrieval request, you must include the following fields in this POST request:

  • file - A PDF of supporting documentation
  • disputeResponse - A JSON message body containing the message field.
  • message - A string of no more than 5,000 characters describing the response.

Your configured request will resemble the sample code below:

curl --request POST \
     --url https://api-test.maast.com/platform/dispute/393435800000003/respond \
     --header 'accept: application/json' \
     --header 'authorization: Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz' \
     --header 'content-type: multipart/form-data' \
     --form file=@sample_file.pdf \
     --form 'disputeResponse={"message": "Test message"}'

For First-Time Disputes: Mastercard, American Express, or Discover

Mastercard, American Express, and Discover responses have the same reason responses, so they are discussed together here.

Refer to tables in Dispute Conventions for the required and optional fields in a POST request that responds to first-time disputes involving Mastercard, American Express, or Discover.

Your configured request will resemble one of the code samples below.

Example response for 'Cardholder No Longer Disputes' (Mastercard, American Express, or Discover):

curl --request POST \
     --url https://api-test.maast.com/platform/dispute/393435800000003/respond \
     --header 'accept: application/json' \
     --header 'authorization: Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz' \
     --header 'content-type: multipart/form-data' \
     --form file=@sample_file.pdf \
     --form 'disputeResponse=
{
"message":"Test Response for cardholder no longer disputes",
"cbr_response_type":"ND",
"amt_tran":58.6
}
'

Example response for 'Credit Processed' (Mastercard, American Express, or Discover):

curl --request POST \
     --url https://api-test.maast.com/platform/dispute/393435800000003/respond \
     --header 'accept: application/json' \
     --header 'authorization: Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz' \
     --header 'content-type: multipart/form-data' \
     --form file=@sample_file.pdf \
     --form 'disputeResponse=
{
"message": "Test Response for credit processed",
"cbr_response_type": "CP",
"batch_date": "2022-12-03",
"amt_tran": 1.90,
"reference_number": "20116789098767656789876"
}
'

Example response for 'Compelling Evidence' (Mastercard, American Express, or Discover):

curl --request POST \
     --url https://api-test.maast.com/platform/dispute/393435800000003/respond \
     --header 'accept: application/json' \
     --header 'authorization: Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz' \
     --header 'content-type: multipart/form-data' \
     --form file=@sample_file.pdf \
     --form 'disputeResponse=
{
"message": "Test Response description for compelling evidence",
"cbr_response_type": "CE",
"cbr_ce_type":"CE14",
"amt_tran": 1.90
}
'

Example response for 'Other' (Mastercard, American Express, or Discover):

curl --request POST \
     --url https://api-test.maast.com/platform/dispute/393435800000003/respond \
     --header 'accept: application/json' \
     --header 'authorization: Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz' \
     --header 'content-type: multipart/form-data' \
     --form file=@sample_file.pdf \
     --form 'disputeResponse=
{
"message": "Test Response description for other",
"cbr_response_type": "OT",
"amt_tran": 1.90
}
'

For First-Time Disputes: Visa

Visa supports two workflows: Allocation and Collaboration. As part of VCR (Visa Claims Resolution), Visa requires a respondent to select a path based on a reason code. See the Maast Knowledge Base for Visa dispute workflows.

See the Response Conventions: VISA for the required and optional fields for a POST request that responds to first-time disputes involving Visa.

Your configured request will resemble the sample code below:

curl --request POST \
     --url https://api-test.maast.com/platform/dispute/393435800000003/respond \
     --header 'accept: application/json' \
     --header 'authorization: Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz' \
     --header 'content-type: multipart/form-data' \
     --form file=@sample_file.pdf \
     --form 'disputeResponse=
{
"message": "Test Response Description",
"cbr_response_type": "ID",
"amt_tran": 1.90,
"cbr_id_type":"IDRC25",
"reason_desc":"reason"
}
'

Integrate

Once you have written and sent your request, you will receive a response like this from the Maast server:

{
  "code": 0,
  "message": "Success"
}

Check the code field in the request response: 0 confirms success. If the value is something other than 0, check Platform API Response Codes in Reference.

See Submit Dispute Response in API Reference for response field definitions.


Test and Go Live

See our Test and Go Live guide to test your API integration and to start transacting with an active production account.


Updated 12 months ago