Creating an API 3.0 Dispute

This guide explains how to use the Dispute API 3.0 endpoints to initiate and submit a dispute.

You might want to read these guides along with this one:

• About Disputes — General explanation of the dispute process from inception to verdict.
• Disputes at Galileo — What Galileo offers with its dispute service.
• Managing API 3.0 Disputes — Instructions for managing dispute claims after they complete the intake flow.
• Dispute API 3.0 Workflows — Instructions for managing dispute claims after they complete the intake flow.

With Galileo's Dispute API 3.0 endpoints, you can integrate the dispute process into your mobile app, website, or customer service tool to provide users—cardholders, account holders, and customer service representatives—with a seamless dispute experience. The user's experience might be as simple as this:

1. Click a "dispute transaction" button or link.
2. Select one or more transactions to dispute.
3. Answer a series of questions about the transactions.
4. Fill out additional documents, if required.
5. Fill out contact information and submit the dispute.
6. If later adjustments need to be made to the dispute, such as attaching more documents, edit the dispute.
7. Track the status of the dispute until completion.

Using the Dispute API 3.0 endpoints also ensures that disputes are made in compliance with card network requirements and regulations such as Regulation E and Regulation Z. Any updates to the requirements are accounted for on the backend, without disrupting your workflow.

Dispute API 3.0 is a "conversational" API, which is a series of calls that are made in a certain order, with the response from one call providing the data for the next call. By using a conversational API, you can tailor the user experience according to the nature of a given dispute and also to conform to regulations governing disputes. For example, if a user indicates that a disputed transaction is a duplicate, you can provide follow-up questions that are specific to duplicate charges, whereas an user who indicates suspected fraud will get questions that are related to fraud.

Result of following this procedure

When the full dispute-intake procedure has been successfully completed, a dispute claim is entered into the dispute system. The information gathered and submitted for the claim conforms to either Reg E or Reg Z, depending on the characteristics of the account and user.

📘

Note

Most of the request and response field names are in PascalCase, but a few are in camelCase. This is intended. Make sure you follow the same case conventions as shown in the reference.

UI requirements

For your mobile app, web site, or customer-service app, create a user interface that permits users to initiate and submit a dispute claim.

• The claim-creation process involves multiple steps that must be performed in the order shown in the numbered steps below.
• The UI must be flexible enough to display dynamic responses from the endpoints, which are returned depending on the characteristics of the dispute that were indicated in earlier endpoints calls. Some responses from the user will trigger further displays, and so on.
• You should include an interface for uploading files.
• Populate the profile-type field in the endpoint header according to your use case. Some endpoints return different data depending on the value of profile-type. See Profile Type Differences for details.
  • agent — A customer-service agent inputs values provided by the account holder into an application that calls the Dispute API.
  • cardholder — The account holder interacts directly with the mobile app or web page that calls the Dispute API.

Endpoint workflows

All of the endpoint sequences are on the Dispute API 3.0 Workflows page. Use the links below to get to the specific sequence that you want, according to the type of dispute.

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."

Claim-creation workflow

❗️

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.

This section shows all possible steps as one continuous flow. Be sure that you follow the specific endpoint workflow for your use case.

1. Initiate the claim and obtain the claim reason
2. Select transactions
3. Get follow-up questionnaire answers
4. Attach documents
5. Finalize the claim

1. Initiate the claim and obtain the claim reason

Initiate the claim, obtain the claim reason from the user, and send it back to Galileo.

1. The user initiates a dispute claim by clicking an "initiate dispute" control.
2. You call the /claim/intake/create endpoint with the CustomerId and AccountNumber.
   • For both the CustomerId and AccountNumber values, combine your Galileo-provided prog_id with the cardholder's PRN in this way: P[prog_id]|[PRN]. For example, if your prog_id is 222 and the PRN is 999101324039, then input P222|999101324039.
3. Galileo returns the ClaimId. You pass ClaimId for all subsequent calls for the claim.
4. You call /claim/intake/retrieveReasons with the ClaimId.
5. Galileo returns a JSON containing the claim reason types and claim reasons. The response varies depending on the account and user type. For example, a consumer debit account might get a different response than a business credit account.
6. You present the claim reasons to the user. See Presenting the claim reasons for instructions.
7. The user selects the category and reason.
8. You pass the category and reason back to Galileo in the /claim/intake/addClaimReasons call. See Returning the claim reasons for more information.
9. The endpoint returns 200: Success.

Presenting the claim reasons

Use the response from the /claim/intake/retrieveReasons endpoint to populate a screen that prompts two interactions with the user. First, the user selects a claim reason type (ClaimReasonType) and then selects a claim reason (ClaimReason).

The JSON in the response is structured as answerList levels nested inside questionList levels. The first level contains the claim reason type in the top level, and then when the user selects one of the types, you present the corresponding claim reasons in the next level down.

This is an example of the first screen to present. The values in parentheses are identifier values in the /claim/intake/retrieveReasons response. You may get a different set of fields in the response depending on the account and user types.

Which of the following would you like to report? (ClaimReasonType)

• I made this purchase, but there is a problem and I need to dispute it. (NonFraud)
• I did not authorize this transaction. I suspect fraud. (Fraud)
• I had an issue while using my card at an ATM. (NonFraudATM)

When the user selects a claim reason type, present the claim reasons that are nested in the corresponding answerList. The claim reasons should have radio-button controls so that the user can select only one claim reason. For example, if the user selects NonFraud, present these options:

Which of the following best describes the reason for your dispute? (ClaimReason)

• I was charged or credited incorrectly. (ChargedCreditedIncorrect)
• I am dissatisfied with the merchandise or a service I received. (MerchandiseServiceIssue)
• I continue to be charged for a recurring transaction after I canceled. (MerchantRecurring)
• I canceled or returned the merchandise or service and have not received the expected credit. (MerchantCreditNotIssued)
• I haven't received merchandise or a service I purchased. (MerchantNotProvided)
• I was charged more than once. (MerchantDuplicate)

Returning the claim reasons

When the user selects the claim reason type, claim reason and other information, pass it back to Galileo by calling the /claim/intake/addClaimReasons call. The Questionnaire parameter accepts a JSON list (questionList) that contains Identifier/AnswerValue pairs: Identifier contains the Identifier for the question in the RetrieveReasons response and AnswerValue contains the response that the user selected or entered.

At minimum, you will include the ClaimReasonType and a ClaimReason. These are the valid combinations for the example shown above.

For example, you would populate Questionnaire like this:

  "Questionnaire": {
    "QuestionList": [
      {
            "Identifier": "ClaimTransType",
            "AnswerValue": "true"
      },
      {
            "Identifier": "ClaimReasonType",
            "AnswerValue": "Fraud"
      },
      {
            "Identifier": "ClaimReason",
            "AnswerValue": "CardSecure"
      }
      ]
  }

👍

Tip

Use the nested fields in the Reference interface to construct a sample endpoint call.

2. Select transactions

Present a list of eligible transactions for the user to select and pass the transactions back to Galileo.

1. You call /claim/intake/retrieveTransactions with the ClaimId. You pass start and end dates and optionally the amount and merchant name as filters.
2. Galileo returns a list of transactions that are eligible for dispute and that fit the filter criteria.
3. You present the list of transactions to the user. The list should have check-box controls to select multiple transactions. See Transaction entries for more information.
4. You submit the transaction IDs of the selected transaction(s) in the /claim/intake/addTransactions call. See Submitting the transactions for the restrictions on this call.
5. The endpoint returns 200: Success.

Transaction entries

Each entry that is returned by /claim/intake/retrieveTransactions contains these metadata fields:

• AuthorizationStatus — The only valid value is Posted.
• DebitCredit — Whether the transaction debits or credits the account:
  • Debit
  • Credit
• TransactionType — The type of transaction. Possible values:
  • ACH — ACH transaction
  • ATMWD — ATM withdrawal
  • CardPinless — Card transaction without PIN (signature)
  • CardPinned — Card transaction with PIN
  • P2P — Peer-to-peer transfer
• Description — The description of the transaction
• Amount — Transaction amount; unsigned
• AmountInfo — Object containing more information about the amount:
  • Exponent — Number of decimal places
  • ISOCodeNumeric — Numeric currency code
  • Amount — Amount in the specified currency
  • ISOCurrencyName — Spelled-out version of the currency name
  • ISOCodeAlpha — Alphabetic currency code
• CardNumberEndingIn — Last 4 digits of the PAN
• Date — Date of the transaction. Format: YYYYMMDD
• TransactionDateTime — Authorization timestamp. Format yyyyMMddTHHmmss.SSS z
• PostingDateTime — Posted timestamp. Format yyyyMMddTHHmmss.SSS z
• SelectMode — The selection mode for the transaction:
  • Multi — Multiple transactions can be selected for this claim type.
  • Single — Only one transaction can be selected for this claim type.
• TransactionId — Identifier assigned by the disputes platform

You may need to record each disputed transaction with its metadata so that you can make the correct decision if you are awarding provisional credit. See Provisional credit in About Disputes for more information.

Submitting the transactions

When submitting the transactions using the /claim/intake/addTransactions endpoint, you must follow these rules, depending on the ClaimReasonType that you submitted with the /claim/intake/addClaimReasons call:

• If ClaimReasonType != Fraud, all transactions submitted in a /claim/intake/addTransactions call must be from the same merchant. If the user has selected transactions from multiple merchants, send multiple /claim/intake/addTransactions calls with the transactions from the same merchant bundled together.
• If ClaimReasonType = Fraud, the transactions in the same call can be from different merchants.

{
  "TransactionList": [
    {
      "TransactionId": 460268821703314
    },
    {
      "TransactionId": 460268821703433
    }
  ]
}

👍

Tip

Use the nested fields in the Reference interface to construct a sample endpoint call.

Every time you call /claim/intake/addTransactions, you create a "dispute." Every claim contains one or more disputes. This distinction between a claim and a dispute will be important when you receive the event message via webhook after you finalize the claim.

If you send /claim/intake/addTransactions multiple times with different but overlapping values, the last request is honored. For example, if you send transactions 1111 and 2222, and then soon after send 2222 and 3333, transactions 2222 and 3333 are submitted—1111 is not.

3. Get follow-up questionnaire answers

According to the claimReason that the user returned, present the follow-up questions.

1. You call /claim/intake/retrieveQuestionnaire with the ClaimId.
2. Galileo returns a JSON of the questionnaire.
3. You present the questionnaire to the user, according to the contents of the response. See Presenting the questionnaire for instructions.
4. The user answers the questions.
5. You pass the answers back to Galileo with the /claim/intake/addQuestionnaire call. See Returning the answers to the questionnaire for instructions.
6. The endpoint returns 200: Success.

Presenting the questionnaire

The questions that you receive in the response to RetrieveQuestionnaire will vary according to the claimReason that you passed in the /claim/intake/addClaimReasons call as well as the network. The response may contain many dozens of lines of JSON formatting.

📘

Note

Every questionnaire is subject to change over time as network requirements change, so you should not cache the questionnaires. Your interface must be able to handle truly dynamic responses. See Questionnaires for examples of questionnaire structures.

As with the JSON in the /claim/intake/retrieveReasons response, there are answerList levels nested inside questionList levels. However, instead of only two levels of questions, the number of levels that you will use depends on the answers that the user provides in each level.

For example, if you submitted ClaimReasonType: Fraud and ClaimReason: CardSecure ("I didn't make the purchase, but I still have my card.") in the /claim/intake/addClaimReasons call, the questionnaire that /claim/intake/retrieveQuestionnaire returns is called FraudCardSecure. See Dispute Questionnaire: FraudCardSecure for an example response, keeping in mind that this is an example only, and your response may be different.

The next level down is a questionList called EverDoneBusiness that contains one question:

{
    "type": "Section",
    "Identifier": "EverDoneBusiness",
    "displayText": "Have you ever done business with any of these disputed merchants?",
    "dataType": "String"
}

Nested inside that questionList level is the answerList with two possible answers, Yes and No, and nested inside the Yes answer are follow-up questions that you display depending on which answer the user selects. If the user selects No then there are no further questions to display for that answer. If the user selects Yes, then you display the next question:

{
    "type": "YesNo",
    "Identifier": "RecognizeDisputedMerchant",
    "displayText": "Is it possible that this is a planned, recurring transaction, such as a monthly or yearly subscription?",
    "dataType": "String"
}

There are no more questions nested in that level, so you move to the next set of questions, which begins with this one:

{
    "type": "YesNo",
    "Identifier": "CardPossessionInd",
    "displayText": "Do you always have possession of the card?",
    "dataType": "String"
}

If the user answers No, present the next set of questions, starting with:

{
    "type": "Text",
    "Identifier": "CardNoPossession",
    "displayText": "In what circumstances do you not have the card in your possession?",
    "dataType": "String"
}

As the user answers the questions, present any follow-up questions that are nested inside the answers until you reach the end of the node, and then go to the next question in that level. Capture the identifier and the answer for each question answered to return in /claim/intake/addQuestionnaire, as described in the next step.

📘

Note

If you returned ClaimReason: MerchantDuplicate or ClaimReason: MerchantCreditNotIssued in the /claim/intake/addClaimReasons call in Step 1, go to Calling endpoints in the questionnaire for additional instructions.

This is one possible sequence of answers for the FraudCardSecure questionnaire. The identifier for the question is shown in parentheses. See Fraud Questionnaire for more examples of questionnaire structures:

• Have you ever done business with any of these disputed merchants? (EverDoneBusiness)
  • Yes
  • Is it possible that this is a planned, recurring transaction, such as a monthly or yearly subscription? (RecognizeDisputedMerchant)
    • No
  • Do you always have possession of the card? (CardPossessionInd)
  • No
    • Where is the card usually kept? (CardLocation)
      • "In my purse"
    • In what circumstances do you not have the card in your possession? (CardNoPossession)
      • "When I go to the gym"
    • Have you ever authorized another person to use your card? (HasAuthorizedOthers)
      • No
    • Have you ever shared your Personal Identification Number (PIN)? (HasSharedPIN)
      • No
    • Where do you keep your PIN? (WherePinKept)
      • In memory (InMemory)

After presenting the main parts of the questionnaire, you display the Questionnaire questions, which permit the user to add information such as comments or to attach further documents.

• Do you have any additional information to provide about this dispute? (AddlInfo)
  • No

Questionnaire attributes

Questions may include one or more of these attributes:

The DataType fields in the questionnaires have these possible values. Each data type accepts the answer formats shown in the answerValue type column.

Returning the answers to the questionnaire

The Questionnaire parameter in the /claim/intake/addQuestionnaire endpoint accepts a JSON list (QuestionList) that contains Identifier/AnswerValue pairs. Identifier contains the Identifier for the question in the /claim/intake/retrieveQuestionnaire response and AnswerValue contains the response that the user selected or entered.

👍

Tip

Use the nested fields in the Reference interface to construct a sample endpoint call.

This example shows what you would return for the questions in the example section, above:

{
  "Questionnaire": {
    "QuestionList": [
      {
                "Identifier": "EverDoneBusiness",
                "AnswerValue": "No"
        },
        {
                "Identifier": "RecognizeDisputedMerchant",
                "AnswerValue": "No"
        },
        {
                "Identifier": "CardPossessionInd",
                "AnswerValue": "No"
        },
        {
                "Identifier": "CardLocation",
                "AnswerValue": "In my purse"
        },
        {
                "Identifier": "CardNoPossession",
                "AnswerValue": "When I go to the gym"
        },
        {
                "Identifier": "HasAuthorizedOthers",
                "AnswerValue": "No"
        },
        {
               "Identifier": "HasSharedPIN",
               "AnswerValue": "No"
        },
        {
               "Identifier": "WherePinKept",
               "AnswerValue": "InMemory"
        },
        {
               "Identifier": "AddlInfo",
               "AnswerValue": "No"
        },
        {
               "Identifier": "HasVisaComments",
               "AnswerValue": "No"
         }
    ]
  }
}

Adding List answers

When the questionnaire includes an item that has "DataType":"List", you can return two or more items that have the same Identifier value. For example:

{
    "Identifier": "ContactMethodMerchant",
    "AnswerValue": "ContactMethodMerchantEmailInd"
},
{
    "Identifier": "ContactMethodMerchant",
    "AnswerValue": "ContactMethodMerchantPhoneInd"
}

Calling endpoints in the questionnaire

Some of the questionnaires include endpoint calls to make depending on how a user answers the questions. This type of questionnaire is returned when ClaimReason is:

• MerchantDuplicate (I was charged more than once)
• MerchantCreditNotIssued (I canceled or returned the merchandise or service and have not received the expected credit.)

The questions with endpoints are Type: Section and include ApiDocumentationList. This example shows how you are instructed to call /claim/intake/retrieveSimilarTransactions and /claim/intake/addSimilarTransactions.

{
  'type': 'Section',
  'AnswerList': [
    {'Identifier': 'Selected',
     'DisplayText': ''
    }],
  'Identifier': 'SelectedValidTransaction',
  'DisplayText': 'Please select a valid transaction.',
  'DataType': 'String',
  'ApiDocumentationList':
    [
      {
        'ImplementationNotes': 'Get list of similar transactions within search criteria',
        'Endpoint': '/claim/intake/retrieveSimilarTransactions',
        'Method': 'post'
      },
      {
        'ImplementationNotes': 'Add selected duplicate transaction to claim',
        'Endpoint': '/claim/intake/addSimilarTransactions',
        'Method': 'post'
      }
    ]
}

In this case, the payload of /claim/intake/addQuestionnaire for the above question should be Identifier = SelectedValidTransaction (what was returned in the Identifier key of /claim/intake/retrieveQuestionnaire, above) and AnswerValue = AnswerList.identifier (Selected).

{
    "Identifier": "SelectedValidTransaction",
    "AnswerValue": "Selected"
}

Consult these sections for details on calling endpoints within the questionnaire.

• Merchant duplicate
• Merchant credit not issued

MerchantDuplicate sequence

This flowchart shows the sequence of events when the disputed transaction is a duplicate.

Question: "Is the valid transaction on this same account?" (BothTransactionsOnSameAcctNumberInd)

• Yes — Call /claim/intake/retrieveSimilarTransactions with search criteria such as amount or merchant name. You can also present a "change search criteria" control.
  • The endpoint returns similar transaction(s), which you can present on the interface with "Please select a valid transaction." (SelectedValidTransaction)
  • When the user selects the transaction, call /claim/intake/addSimilarTransactions to add the transaction(s) to the claim.
• No — Present the question "Is the other transaction on a [your brand] Card?" (IssuerOrCardholderOtherAcctWithDiff[MC|Visa]CardInd)
  • Yes — Call /claim/intake/retrieveOtherAccounts.
    • The endpoint returns other accounts belonging to the user, each with its AccountNumber.
    • You present the list with "Select the account the charge(s) appear on." (SelectedValidAccount)
    • The user selects the account.
    • You call /claim/intake/retrieveSimilarTransactions, passing the selected account number for SearchAccountNumber.
    • The endpoint returns the other account's transaction(s), which you present on the interface with "Select the duplicate charge" (SelectedValidTransaction).
    • When the user selects the valid transaction(s), call /claim/intake/addSimilarTransactions to add the transaction(s) to the claim.
    • When Galileo returns success, return to the next question in the questionnaire.
  • No — Present the question "What was the other form of payment?" (OtherMeansPaymentForm)
    • The user chooses from among the options: Another [Mastercard | Visa], Other Card, Check, Cash, or Other.

MerchantCreditNotIssued sequence

Question: Were you issued a partial credit? (IssuedPartialCredit)

• No — Return to the next question in the questionnaire.
• Yes — Call /claim/intake/retrieveCreditTransactions. Populate SearchAccountNumber if the credit transactions are on a different account than the current account.
  • The endpoint returns transaction(s) that credit the account, which you can present on the interface with "Please select a valid transaction." (SelectedValidTransaction)
  • When the user selects the transaction, call /claim/intake/addSimilarTransactions to add the transaction(s) to the claim.

4. Attach documents

Depending on the claim reasons and the transactions selected, the user may need to fill out a form.

📘

Note

This step is optional. However, if you call these endpoints (/claim/intake/retrieveDocRequirements and /claim/intake/addDocuments), you must call them during the intake flow. To retrieve and submit any required documents after completing the intake flow, you can use two similar endpoints: /claim/documents/retrieveRequirements and /claim/documents/add.

1. You call /claim/intake/retrieveDocRequirements.
2. Galileo returns one of two options:
   • A message saying that no further documents are required.
   • A base64-encoded PDF (templateDocumentationStream) that the user must fill out and return. When the user has filled out the form, you call /claim/intake/addDocuments to send the completed form to Galileo.
   • Send only one document at a time with /claim/intake/addDocuments. If you need to send multiple documents at this stage, call /claim/intake/addDocuments once for each document to return.

👍

Tip

Use the nested fields in the Reference interface to construct a sample endpoint call.

5. Finalize the claim

The user reviews the claim details, and then clicks "Submit" at the end of the process.

1. At the end of the intake flow, you can call /claim/intake/retrieveSummary to display the claim details to the user for review.
   • This endpoint also returns questions for the user or the dispute agent to fill out regarding contact information for this claim only (if it is different from the user's current information).
   • If the endpoint returns the CustomerContactOverrideDate section, do not display the questions to users in your interface. The customer contact date should be changed only by an agent, and only if the contact date is in error.
2. If applicable, the user reviews the claim, fills out the contact information, and clicks a "submit" control to signal that they have finished inputting information for the claim.
3. You call /claim/intake/submit. The Requirements for submission must be fulfilled.
   • The Questionnaire parameter accepts a JSON list (QuestionList) that contains Identifier/AnswerValue pairs. Identifier contains the Identifier for the question in the RetrieveClaimIntakeSummary response, and AnswerValue contains the response that the user selected or entered. Use the same format that you used for /claim/intake/addQuestionnaire.
4. Galileo returns success and then sends the following event messages:
   • CSCT: case_created — The message contains the case_no and specifies which disputed transactionIds (ids) are included in the claim.
   • DSCT: created — One for each time that you called /claim/intake/addTransactions. The message indicates the case_no that the disputed transaction belongs to.

Requirements for submission

Before you can call /claim/intake/submit, these minimum requirements must be fulfilled:

1. The claim number was created. (/claim/intake/create)
2. The claim-reason category and reason were submitted. (/claim/intake/addClaimReasons)
3. One or more transactions were submitted. (/claim/intake/addTransactions)
4. The questionnaire answers were submitted. (/claim/intake/addQuestionnaire)

📘

Note

If the user begins the dispute process but does not complete it, the claim that was created remains in the dispute system for eight hours and then times out. If the user decides to return to a claim that has timed out, you have to start over with /claim/intake/create to create a new ClaimId.

After submitting the dispute

After you have successfully called /claim/intake/submit, you can optionally call /claim/intake/retrieveConfirmation to retrieve a confirmation number and PDF that you can present to the user.

📘

Note

/claim/intake/retrieveConfirmation is the only endpoint that you can call immediately after successfully calling /claim/intake/submit. For all of the other dispute-management endpoints, you must wait several seconds until after the claim has been processed. If a dispute-management endpoint returns a "claim not found" status message, call the endpoint again after several more seconds.

Before the verdict arrives, if the user wants to add more documents to the claim, or if the user needs to return the required PDF form, call /claim/attachments/add with the claim ID to attach the documents.

• Supported file types: JPG, JPEG, TIFF, PNG and PDF
• File size maximum:
  • Mastercard — 20 MB
  • Visa — 10 MB

For more information on what happens to a dispute claim after it is submitted, begin with Post-intake processing in Disputes at Galileo or consult the Card-transaction dispute lifecycle in About Disputes.

👍

Tip

Use the nested fields in the Reference interface to construct a sample endpoint call.

To manage dispute claims after they have been submitted, go to Managing API 3.0 Disputes.