Transaction Dispute Management Use Case

Transaction dispute management uses a dedicated data model with entities such as Dispute, mapping base attributes to fields in Dispute data model entities.

Configure Objects, Permissions, and Mulesoft Integration

Before you can create transaction disputes using the Service Process connect API resource, you must create or modify objects, set user permissions, and connect to Mulesoft. Perform these tasks described in the Financial Services Cloud Administration Guide:

• Configure the Dispute Object
• Assign Transaction Dispute Management Permissions to User
• Connect to MuleSoft and Enable Integration
• Create an Integration Definition
• Add the Picklist Values Required for a Dispute Request
• Create a Transaction Dispute Service Process Definition with the Default Template
• Activate the Transaction Dispute Service Process (skip steps 3 and 4)

These tasks are optional but helpful for viewing Case records in your Salesforce org:

• Add Related Lists to the Page Layout
• Add the Case Details Lightning Component to the Case Record Page

Review the Dispute Management Objects and Fields

Transaction dispute management uses Dispute and Dispute Item records in addition to the Case and Document Checklist Item records common to all service processes. Setting values for the following fields is required. You can include additional fields.

• Dispute object — AccountId, ActualAmount, ApprovedAmount, AssessmentId, Description, DisputeSubtype, DisputeType, DisputedAmount, FinancialAccountId, ReceivedDate, Status
• Dispute Item object, one record for each disputed transaction — TransactionAmount, TransactionDate, TransactionDescription, TransactionIdentifier
• Case object — Subject, Origin, AccountId
• Document Checklist Item object — No requirements specific to transaction disputes

The TransactionIdentifier value typically references an ID in an external banking system. If you include the Case record’s Type field, setting its value to Dispute is recommended. You can use Document Checklist Item fields to specify documentation such as bank statements or receipts.

Set Up the Service Process Request Payload

The Service Process POST payload has four top-level properties: attributes, caseInfo, documentInfo, and svcCatalogItemDefApiName. For the transaction dispute management process, certain attributes are mapped to specific objects:

• Under the attributes property, configure a dispute_info property for the Dispute record and a disputed_transactions_info property for the list of Dispute Item records.
• Configure caseInfo and documentInfo as you do for any service process.
• Set svcCatalogItemDefApiName to Dispute_Management.

Arrange the properties in JSON format as shown in the following example. Within this structure, all attributes are of type Text except for these fields:

• Amount Fields (type Number)
  • disputed_amount
  • transaction_amount
  • actual_amount
  • approved_amount
• Date Fields (type Date)
  • received_date
  • transaction_date

{
  "attributes": {
    "data": {
      "dispute_info": {
        "data": {
          "dispute_type": {
            "value": "Consumer Dispute"
          },
          "dispute_subtype": {
            "value": "Undelivered Product or Service"
          },
          "description": {
            "value": "Order from acmemerchant.com not delivered but credit card charged."
          },
          "received_date": {
            "value": "2023-07-14"
          },
          "account_id": {
            "value": "001DI000001o10QYAQ"
          },
          "assessment_id": {
            "value": "0U3DI000000018m0AA"
          },
          "financial_account_id": {
            "value": "a0EDI000000Ce6W2AS"
          },
          "actual_amount": {
            "value": 593.63
          },
          "disputed_amount": {
            "value": 400
          },
          "approved_amount": {
            "value": 100
          },
          "status": {
            "value": "Submitted"
          }
        }
      },
      "disputed_transactions_info": {
        "value": [
          {
            "transaction_date": "2023-01-01",
            "transaction_identifier": "1",
            "transaction_amount": 213.1,
            "transaction_description": "t1"
          },
          {
            "transaction_date": "2023-01-01",
            "transaction_identifier": "2",
            "transaction_amount": 150.94,
            "transaction_description": "t2"
          },
          {
            "transaction_date": "2023-01-01",
            "transaction_identifier": "3",
            "transaction_amount": 199.0,
            "transaction_description": "t3"
          },
          {
            "transaction_date": "2023-01-01",
            "transaction_identifier": "4",
            "transaction_amount": 30.59,
            "transaction_description": "t4"
          }
        ]
      }
    }
  },
  "caseInfo": {
    "data": {
      "Subject": {
        "value": "Julia Green Transaction Dispute Request"
      },
      "Origin": {
        "value": "Phone"
      },
      "AccountId": {
        "value": "001DI000001o10QYAQ"
      }
    }
  },
  "documentInfo": {
    "data": [
      {
        "id": "content document id-1",
        "name": "Julia Green credit card statement"
      },
      {
        "id": "content document id-2",
        "name": "acmemerchant.com receipt"
      }
    ]
  },
  "svcCatalogItemDefApiName": "Dispute_Management"
}

Invoke the Service Process Resource

After you assemble the payload, you’re ready to invoke the Service Process resource using your favorite REST client. This resource creates all the object records related to a transaction dispute record and returns a response like this:

{
  "caseId": "500SM000000ecOLYAY",
  "caseNumber": "00001035",
  "svcCatalogRequestId": "946SM00000000CvYAI"
}

All records related to the transaction dispute directly or indirectly reference the Case record or the SvcCatalogRequest record.