Overview

Dispute is a type of financial records representing disagreements between customers and merchants on a particular payment. It is also referred to as "chargeback".

Though each payment service provider (PSP) has its specific dispute policies, a common dispute workflow includes following stages:

• Inquiry: Customers or issuers request detailed information for the transaction at question. At this point, the dispute has not been officially initiated yet.
• Initiation: A dispute is officially initiated by the customers or issuers for the transaction at question. At this point, the PSP will withdraw the disputed amount from merchant's wallet.
• Investigation: A series of investigative steps are taken to determine the party at fault. The steps includes acquiring evidence, arbitration, etc.
• Resolution: A final decision is made on the dispute and the dispute is closed. There are 2 possible outcomes. If the merchant wins, the disputed amount will be deposited back to merchant's wallet. If the merchant loses, the disputed amount will be returned to the customer or issuer.

Disputes (or Chargebacks) are commonly initiated against a particular payment. In some cases (not always), the dispute can be attributed towards one or more particular line items, taxes or discounts. When such attribution is available, Leapfin recommends to include a link from the Dispute record to each associated record, so that accounting schedules on those records can be adjusted accordingly.

Create a Dispute

The following fields are required :

• objectType: type of financial record. For Dispute, the value is "dispute".
• id: unique identifier of this record. This is external id received by Leapfin.
• amount: amount of money impacted by this record. The value should be non-negative. This is the primary amount of this record.
• currencyCode: 3-digit ISO code of amount field, e.g. “USD”, "GBP", etc. This is the primary currency of this record
• date: the date-time of when this dispute is created by payment processor.
• status: the status of the dispute. Acceptable values are
  • "pending": the dispute has been initiated and under investigation.
  • "lost": the dispute is closed in favor of the customer or issuer.
  • "won": the dispute is closed in favor of the merchant.

The following fields are optional but are commonly need for creating journal entries:

• description: description of the dispute. Use this field to explain the reason of dispute.
• initiatedDate: the date-time when this dispute is formally initiated (excluding the informational inquiry stage). This is also the date when funds are withdrawn by payment processors from merchant's account.
• resolvedDate: the date-time when this dispute is closed. If the dispute decision is in favor of the merchant, this is also the date when funds are returned to merchant's account.
• exchangeRates: a list of exchange rates used to calculate currency conversions
  • currencyCode: 3-digit ISO code, e.g. “USD”, "GBP", etc. This is the target currency of this record
  • rate: conversion rate from primary currency to target currency. i.e. amount in primary currency * rate = converted amount in target currency.
• links: directional relationships pointing from this record to other financial records. Dispute is commonly linked to Line Item.
  • objectType: type of the target financial record, e.g. "line-item"
  • id: unique identifier of the target financial record
• customFields: additional fields (i.e. key-value pairs) related to this record

Sample Data

{
    "objectType": "dispute",
    "id": "dispute_001",
    "amount": 870.70,
    "currencyCode": "USD",
    "date": "2021-02-16T12:09:52",
 	  "status": "won",
    "description": "a sample dispute object",
    "initatedDate": "2021-02-17T20:00:01",
    "resolvedDate": "2021-04-01T08:08:37",
    "exchangeRates": [
      {
        "currencyCode": "EUR",
        "rate": 0.84
      },
      {
        "currencyCode": "GBP",
        "rate": 0.73
      }
    ],
    "links": [
      {
        "objectType": "line-item",
        "id": "lineitem_001"
      },
      {
        "objectType": "line-item",
        "id": "lineitem_002"
      }
    ],
    "customFields": {
      "field1": "value1",
      "field2": "value2"
    }
}

Query a Dispute

Dispute records are stored in VW_FT_DISPUTE table. It can be accessed via Snowflake Data Sharing and Access.