Transaction Dispute Management Use Case

Transaction dispute management provides a streamlined process for users to capture and submit customer disputes related to financial transactions. You can use the Service Process connect API resource to create all the records related to a transaction dispute.

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

The optional Assessment Questions portion of transaction dispute management isn’t included in this use case.

Note

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:

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

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

1{
2  "attributes": {
3    "data": {
4      "dispute_info": {
5        "data": {
6          "dispute_type": {
7            "value": "Consumer Dispute"
8          },
9          "dispute_subtype": {
10            "value": "Undelivered Product or Service"
11          },
12          "description": {
13            "value": "Order from acmemerchant.com not delivered but credit card charged."
14          },
15          "received_date": {
16            "value": "2023-07-14"
17          },
18          "account_id": {
19            "value": "001DI000001o10QYAQ"
20          },
21          "assessment_id": {
22            "value": "0U3DI000000018m0AA"
23          },
24          "financial_account_id": {
25            "value": "a0EDI000000Ce6W2AS"
26          },
27          "actual_amount": {
28            "value": 593.63
29          },
30          "disputed_amount": {
31            "value": 400
32          },
33          "approved_amount": {
34            "value": 100
35          },
36          "status": {
37            "value": "Submitted"
38          }
39        }
40      },
41      "disputed_transactions_info": {
42        "value": [
43          {
44            "transaction_date": "2023-01-01",
45            "transaction_identifier": "1",
46            "transaction_amount": 213.1,
47            "transaction_description": "t1"
48          },
49          {
50            "transaction_date": "2023-01-01",
51            "transaction_identifier": "2",
52            "transaction_amount": 150.94,
53            "transaction_description": "t2"
54          },
55          {
56            "transaction_date": "2023-01-01",
57            "transaction_identifier": "3",
58            "transaction_amount": 199.0,
59            "transaction_description": "t3"
60          },
61          {
62            "transaction_date": "2023-01-01",
63            "transaction_identifier": "4",
64            "transaction_amount": 30.59,
65            "transaction_description": "t4"
66          }
67        ]
68      }
69    }
70  },
71  "caseInfo": {
72    "data": {
73      "Subject": {
74        "value": "Julia Green Transaction Dispute Request"
75      },
76      "Origin": {
77        "value": "Phone"
78      },
79      "AccountId": {
80        "value": "001DI000001o10QYAQ"
81      }
82    }
83  },
84  "documentInfo": {
85    "data": [
86      {
87        "id": "content document id-1",
88        "name": "Julia Green credit card statement"
89      },
90      {
91        "id": "content document id-2",
92        "name": "acmemerchant.com receipt"
93      }
94    ]
95  },
96  "svcCatalogItemDefApiName": "Dispute_Management"
97}

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:

1{
2  "caseId": "500SM000000ecOLYAY",
3  "caseNumber": "00001035",
4  "svcCatalogRequestId": "946SM00000000CvYAI"
5}

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