Log into Sandbox

Dispute API Workflows

👍

Availability

The Dispute API is under development and will be generally available in 2025.

The Creating a Dispute guide gives general instructions for creating a dispute case. This page shows the endpoint workflows for specific combinations of ClaimReasonType and ClaimReason, which you submit with the Add Case Reasons endpoint (third endpoint in every sequence).

❗️

Warning

You must call the endpoints in the order shown for each dispute type. Failure to follow the sequence will prevent you from completing the intake flow.

ClaimReasonTypeClaimReason
Fraud

"I did not authorize this transaction. I suspect fraud."
  • CardLost — "I lost my card."
  • CardStolen — "My card was stolen."
  • CardNotReceived — "I did not receive my card."
  • CardSecure — "I didn't make the purchase, but I still have my card."
    • NonFraud

    "I made this purchase, but there is a problem and I need to dispute it."
  • MerchantDuplicate — "I was charged more than once."
  • MerchantCreditNotIssued — Mastercard only. "I canceled or returned the merchandise or service and have not received the expected credit."
  • MerchantNotProvided — "I haven't received merchandise or a service I purchased."
  • MerchantRecurring — "I have an issue with a recurring transaction on my account."
  • MerchandiseServiceIssue — "I am dissatisfied with merchandise or a service I received."
  • ChargedCreditedIncorrect — "I was charged or credited incorrectly."

    • Fraud workflow

    When ClaimReasonType is Fraud, call these endpoints in this order.

    Initiate the case and obtain the case reason

    1. Create Case
    2. Get Case Reasons
    3. Add Case Reasons

    Select transactions

    1. Get Transactions
    2. Add Transactions

    Get follow-up questionnaire answers

    1. Get Questionnaire
    2. Add Questionnaire

    Attach a required document

    1. Optional. Get Doc Requirements
    2. Optional. Add Required Docs

    Finalize the case

    1. Optional. Get Case Summary
    2. Submit Case
    — Back to top —

    Non-fraud workflows

    When ClaimReasonType is NonFraud, follow one of these sequences:

    Merchant duplicate

    Follow this sequence when ClaimReason is MerchantDuplicate.

    Initiate the case and obtain the case reason

    1. Create Case
    2. Get Case Reasons
    3. Add Case Reasons

    Select transactions

    1. Get Transactions
    2. Add Transactions

    Get follow-up questionnaire answers

    1. Get Questionnaire
    2. Get Other Account
    3. Get Similar Transactions
    4. Add Similar Transactions
    5. Add Questionnaire

    Attach a required document

    1. Optional. Get Doc Requirements
    2. Optional. Add Required Docs

    Finalize the case

    1. Optional. Get Case Summary
    2. Submit Case
    — Back to top —

    Merchant credit not issued

    Mastercard only

    Follow this sequence when ClaimReason is MerchantNotProvided, MerchantRecurring, MerchandiseServiceIssue or ChargedCreditedIncorrect.

    Initiate the case and obtain the case reason

    1. Create Case
    2. Get Case Reasons
    3. Add Case Reasons

    Select transactions

    1. Get Transactions
    2. Add Transactions

    Get follow-up questionnaire answers

    1. Get Questionnaire
    2. Optional. Get Credit Transactions
    3. Optional. Add Similar Transactions
    4. Add Questionnaire

    Attach a required document

    1. Optional. Get Doc Requirements
    2. Optional. Add Required Docs

    Finalize the case

    1. Optional. Get Case Summary
    2. Submit Case
    — Back to top —

    Other reasons

    Follow this sequence when ClaimReason is MerchantNotProvided, MerchantRecurring, or MerchandiseServiceIssue, ChargedCreditedIncorrect.

    Initiate the case and obtain the case reason

    1. Create Case
    2. Get Case Reasons
    3. Add Case Reasons

    Select transactions

    1. Get Transactions
    2. Add Transactions

    Get follow-up questionnaire answers

    1. Get Questionnaire
    2. Add Questionnaire

    Attach a required document

    1. Optional. Get Doc Requirements
    2. Optional. Add Required Docs

    Finalize the case

    1. Optional. Get Case Summary
    2. Submit Case