Managing API 3.0 Disputes

This guide explains how to manage disputes after they have passed through the entire intake flow, as described in Creating an API 3.0 Dispute. The /claim/intake/submit endpoint must have been called for a claim before you can manage it with the processes in this guide.

📘

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.

Manage claims

Follow these steps to manage the claims.

Attach required documents

If you did not retrieve and submit the required PDF during the intake flow (/claim/intake/retrieveDocRequirements and /claim/intake/addDocuments), you can call two other endpoints after the claim has been submitted.

1. Call /claim/documents/retrieveRequirements.
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/documents/add to send the completed form to Galileo.
   • Send only one document at a time with /claim/documents/add. If you need to send multiple documents at this stage, call /claim/documents/add once for each document to return.

View claims

To view all claims for a cardholder, call /claim/list with these parameters:

• DaysToLookBack — Input an integer to specify the number of days in the past to retrieve claims.
• Pass only one of the following:
  • accountNo — Format: P{prog_id}|{prn}
  • ClaimId — As returned by /claim/intake/create
  • CustomerId — Format: P{prog_id}|{prn}

If you did not pass ClaimId for /claim/list, call /claim/details/retrieve with the ClaimId. This endpoint returns:

{
  "claimListResponse": [
	{
  	"accountHolder": "William James Murray",
  	"requiredDocumentCount": 0,
  	"customerContactDate": "20271005T000000.000 GMT",
  	"claimId": "2110050013C",
  	"externalCaseId": "123456789",
  	"accountNumber": "4447111111117413",
  	"claimStatus": "Open-Execute",
  	"createName": "creat or",
  	"accountType": "Credit",
  	"customerId": "123456789",
  	"isClaimSubmitted": "true",
  	"totalClaimAmount": 150.23
	}
  ],
  "StatusList": [
	{
  	"Type": "Success",
  	"Message": "Success",
  	"Code": "200"
	}
  ],
  "rtoken": "984513-395483653-4483483478",
  "StatusCode": "200"
}

Checking on claim status

To provide your account holders with an up-to-date claim status, call /claim/retrieve with the ClaimId. You can display the ClaimStatus along with any TalkingPoints

To notify clients when the status changes, set up a cron job to poll the endpoint periodically, and then when ClaimStatus changes, you can send a notification.

Withdraw a claim

If the account holder wants to withdraw (cancel) a dispute, follow these steps:

1. Follow the steps in View Claims to retrieve a list of claims.
2. Locate the ClaimId of the claim to cancel.
3. Call /claim/withdrawRequest and pass these required values:
   • ClaimId — The ClaimId from /claim/list.
   • WithdrawalReason — Freeform explanation of why the claim is being withdrawn.
   • TransactionList — A list of one or more TransactionIds to be withdrawn. These transaction IDs take the same form as in all other dispute-related endpoints: P[prog_id]|[prn]|[auth_id]|[network_code]|[trans_code], as returned by /claim/transactions/list.

Keep these facts in mind when withdrawing a claim:

• Withdrawing a claim using /claim/withdrawRequest is an asynchronous process. The response returned by the endpoint indicates whether the endpoint request/response sequence was successful.
  • A successful withdrawal request is queued for review, and then the claim withdrawal is attempted on the back end.
  • You can check the status of the withdrawal using these methods:
    • See Checking on claim status.
    • Identify the disputed transaction in the Reg E RDF with RESOLUTION: CH_CANCELED.
    • Wait for one of two event messages that contain dispute_resolution: CH_CANCELED:
      • DSFN: dispute_final_no_pc
      • DSFP: dispute_final_pc
• You can withdraw a claim after provisional credit has been issued, when the merchant has issued a partial refund, and if a chargeback has been filed with the card network.
  • In the case of a chargeback (partial or whole), the chargeback must be resolved prior to withdrawing the claim.
    • If a claim is in active recovery at the time of the endpoint request, an error will indicate that the claim cannot be withdrawn. For example, if a chargeback is open, it must be addressed or resolved before the claim can be withdrawn.
• If a dispute is withdrawn after a partial network process has occurred (such as provisional credit granted), the credit can be reversed. The recovery would need to be cancelled or recalled prior to processing the withdrawal of funds in the case that credit was provided to the account holder.
  • Recovery can be recalled or canceled only when DisputeStatus is Pending-DisputeResponse or Pending-AcquirerResponse.

Reopen a claim

You can reopen a claim when it has at least one transaction that has been resolved but denied. The account holder must provide new information to justify reopening the claim.

• When a claim is reopened, it is the same claim number as before, the prior case history is still available, and the claim will route to the stage where it left off before the initial denial.
• Because only denied claims can be reopened, any provisional credit that was previously granted would have been withdrawn when the claim was denied. You can grant provisional credit again, there is no regulatory requirement for a reopened claim.

Call /claim/list to get the claim ID, and then call /claim/reopenRequest with these required parameters:

• ClaimId — Identifier for the claim to reopen.
• ReopenReason — The account holder briefly describes the reason for reopening the claim.
• ReopenNewInformation — The account holder provides new information regarding the transaction(s), such as a description of a new event or circumstance.
• TransactionList — Transaction(s) to be reopened. These transactions must be in DisputeStatus: Resolved-Denied, as returned by /claim/transactions/list.

Keep these facts in mind when reopening a claim:

• Reopening a claim using /claim/reopenRequest is an asynchronous process. The response returned by the endpoint indicates whether the endpoint request/response sequence was successful.
  • A successful reopen request is queued for review, and then the claim is reopened on the back end.
  • To see whether the claim was successfully reopened, check the claim status for a DisputeStatus that does NOT begin with Resolved-.

Manage transactions

Follow these instructions to manage disputed transactions.

View the transactions in a claim

To view all of the transactions that are included in an existing claim, call /claim/transactions/list with the ClaimId. The endpoint returns:

{
  "TransactionList": [
	{
  	"TransactionAmount": "100.000000000",
  	"CardLastFourDigits": "8557",
  	"DisputedAmount": "100.000000000",
  	"DisputeId": "2307190009D",
  	"Description": "Galileo Bank BRANCH #2145",
  	"PostingDate": "20270727",
  	"PostingDateTime": "202707272T020235.184 GMT",
  	"CurrentStage": "Analyze",
  	"LastCommitDate": "20270728T020235.184 GMT",
  	"TransactionId": "2",
  	"DisputeStatus": "Open-Disposition"
	}
  ],
  "StatusList": [
	{
  	"Type": "Success",
  	"Message": "Success",
  	"Code": "200"
	}
  ],
  "rtoken": "984513-395483653-4483483478",
  "StatusCode": "200"
}

Add attachments

To add an attachment to an existing claim, first convert the document into a base-64 encoded string and then call /claim/attachments/add to add it to the claim. You can use this endpoint to attach multiple documents with one call.