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.

ColumnDescription
LEAPFIN_IDunique identifier created by Leapfin.
DECODED_LEAPFIN_ID_VTdecoded version of LEAPFIN_ID in json format. It contains following values:

- external_code: unique identifier of this record. This is external id received by Leapfin.
- integration_id: unique identifier of the data source. This is internal id created by Leapfin.
- leapfin_data_type: type of financial record, i.e. "LeapfinDispute"
- leapfin_suffix: additional string to distinguish different financial records when the same external_code is received from the data source.
- raw_data_type: type of raw data record received from the data source.
ORGANIZATION_IDunique identifier of the account. This is internal id created by Leapfin.
DATE_DTthe date of when this dispute is created by payment processor.
DESCRIPTIONdescription of the dispute. Use this field to explain the reason of dispute.
CURRENCY_CODE3-digit ISO code of amount field, e.g. “USD”, "GBP", etc. This is the primary currency of this record.
AMOUNTamount of money impacted by this record. The value should be non-negative. This is the primary amount of this record.
INITIATED_DATE_DTthe date 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.
RESOLVED_DATE_DTthe date 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.
EXCHANGE_RATES_VTa list of exchange rates used to calculate currency conversions. Each rate contains following values:

- 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.
STATUSthe 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.
CUSTOM_FIELDS_VTadditional fields (i.e. key-value pairs) about the financial record in json format
ACCOUNTING_TRANSACTIONS_VTa list of journal entries associated with this financial record. Each item contains following values:

- date: the date of the journal entry
- entries: a list of journal lines within the journal entry. Each line contains following values:
--- account: unique identifier of the financial account. This is an internal id created by Leapfin (refer to VW_LK_ACCOUNT).
--- amount: amount of money booked towards the account.
--- accountingSide: an indicator of whether the amount is a debt ("dr") or credit ("cr") to the acount.
- comments: additional fields (i.e. key-value pairs) on the journal entry in json format.
CREATED_AT_DTthe date-time when the financial record is created by Leapfin. Value format: "2022-07-14 23:01:26.400"
UPDATED_AT_DTthe date-time when the financial record is last updated by Leapfin. Value format: "2022-09-01 06:09:57.379"