Dispute Data Model

Data Model

Overview

The "Dispute Status Changed" webhook is triggered whenever there is a dispute triggered for a payment on your account. This webhook ensures that your system is notified of the disputes taking place and their updates, allowing for real-time updates and appropriate actions.

Your webhook endpoint will receive a POST request containing an event with a Code of 6 and Name of DISPUTE_STATUS_CHANGED. This event is particularly useful for tracking the type of chargeback and its status.

Request Model

The webhook payload consists of multiple nested objects containing essential recurring payment details.

Event Object

Input Parameter	Type	Description
Event.Code	number	6 - DISPUTE_STATUS_CHANGED
Event.Name	string	DISPUTE_STATUS_CHANGED
Event.CountryIsoCode	string	The country of your account with nstFi.
Event.CreationDate	datetime	The timestamp when the event was created in ISO 8601 format.
Event.Reference	string	Unique reference ID for the webhook event.

Data Object

The Data Object contains multiple nested objects as below.

Dispute Object

Input Parameter	Type	Description
Dispute.Type	string	The type of dispute raised (e.g., `CHARGEBACK - DOCUMENTREQUEST - FRAUDALERT - UNVERIFY`).
Dispute.Status	string	The current status of the dispute (e.g., `PENDING - RESOLVED - LOST`).
Dispute.CreatedDate	datetime	The date and time when the dispute was created, formatted in ISO 8601 UTC.
Dispute.ChargeBackType	string	The chargeback classification (e.g., `General - Trading - Airways`). Has value only if type is CHARGEBACK
Dispute.Reason	string	The reason provided for the dispute. Has value only if type is CHARGEBACK
Dispute.DisputeTransactionId	integer	Unique identifier for the dispute transaction.
Dispute.InvoiceTransactionId	integer	Identifier of the invoice transaction associated with the dispute.

Invoice Object

Input Parameter	Type	Description
Invoice.Id	string	Unique identifier for the invoice.
Invoice.Status	string	The current status of the invoice (e.g., `PAID`).
Invoice.Reference	string	A unique reference number assigned to the invoice.
Invoice.CreationDate	datetime	The date and time when the invoice was created, formatted in ISO 8601 UTC.
Invoice.ExternalIdentifier	string	The value sent in the CustomerIdentifier field in the request.

Transaction Object

Input Parameter	Type	Description
Transaction.Id	string	Unique identifier for the transaction.
Transaction.Status	string	The status of the transaction (e.g., `SUCCESS`).
Transaction.PaymentMethod	string	The payment method used (e.g., `VISA/MASTER`).
Transaction.PaymentId	string	The unique payment ID associated with the transaction.
Transaction.ReferenceId	string	A unique identifier assigned to the transaction for tracking purposes.
Transaction.TrackId	string	The tracking ID for the payment transaction.
Transaction.AuthorizationId	string	A unique ID associated with the authorization of the payment.
Transaction.TransactionDate	datetime	The date and time when the transaction was processed.
Transaction.ECI	string	The Electronic Commerce Indicator (ECI) code, representing security level.

Card Object

Input Parameter	Type	Description
Transaction.Card.NameOnCard	string	Name printed on the card used for the transaction.
Transaction.Card.Number	string	The masked credit/debit card number used for the transaction.
Transaction.Card.Token	string	Tokenized representation of the card, if available.
Transaction.Card.ExpiryMonth	string	Expiry month of the card.
Transaction.Card.ExpiryYear	string	Expiry year of the card.
Transaction.Card.Brand	string	The brand of the payment card, such as Visa or MasterCard.
Transaction.Card.Issuer	string	The issuing bank or financial institution of the card, if available.
Transaction.Card.IssuerCountry	string	The country of the card issuer.
Transaction.Card.FundingMethod	string	The funding method of the card (e.g., `credit`, `debit`).

Customer Object

Input Parameter	Type	Description
Customer.Name	string	Name of the customer.
Customer.Mobile	string	Customer's mobile number.
Customer.Email	string	Customer's email address.

Amount Object

Input Parameter	Type	Description
Amount.BaseCurrency	string	The base currency of your nstFi account (e.g., KWD).
Amount.ValueInBaseCurrency	string	The amount in the base currency.
Amount.ServiceCharge	string	The service charge applied in base currency.
Amount.ServiceChargeVAT	string	The VAT applied to the service charge.
Amount.ReceivableAmount	string	The amount the vendor receives in base currency.
Amount.DisplayCurrency	string	The currency used for display.
Amount.ValueInDisplayCurrency	string	The amount in display currency.
Amount.PayCurrency	string	The currency used for payment (e.g., USD).
Amount.ValueInPayCurrency	string	The transaction value in payment currency.

Sample Event

The below sample JSON message is sent by nstFi to your endpoint.

{
  "Event": {
    "Code": 6,
    "Name": "DISPUTE_STATUS_CHANGED",
    "CountryIsoCode": "KWT",
    "CreationDate": "2025-07-08T11:48:50.4330000Z",
    "Reference": "WH-290725"
  },
  "Data": {
    "Dispute": {
      "Type": "CHARGEBACK",
      "Status": "PENDING",
      "CreatedDate": "2025-07-08T11:48:50.4005403Z",
      "ChargeBackType": "General",
      "Reason": "CreditNotProcessed",
      "DisputeTransactionId": 112,
      "InvoiceTransactionId": 2825348
    },
    "Invoice": {
      "Id": "5897264",
      "Status": "PAID",
      "Reference": "2025059298",
      "CreationDate": "2025-07-08T11:46:12.12Z",
      "ExternalIdentifier": "1hGonC7bf2vNuJWuTgCGURYzi6Yu"
    },
    "Transaction": {
      "Id": "203009",
      "Status": "SUCCESS",
      "PaymentMethod": "VISA/MASTER",
      "PaymentId": "07075897264282534874",
      "ReferenceId": "518911203009",
      "TrackId": "08-07-2025_2825348",
      "AuthorizationId": "993730",
      "TransactionDate": "2025-07-08T11:46:29.853Z",
      "ECI": "02",
      "Card": {
        "NameOnCard": "fa",
        "Number": "545454xxxxxx5454",
        "Token": "",
        "ExpiryMonth": "12",
        "ExpiryYear": "34",
        "Brand": "Mastercard",
        "Issuer": "Test Bank",
        "IssuerCountry": "KWT",
        "FundingMethod": "credit"
      }
    },
    "Customer": {
      "Name": "Rhianna",
      "Mobile": "+9715555555",
      "Email": "[email protected]"
    },
    "Amount": {
      "BaseCurrency": "KWD",
      "ValueInBaseCurrency": "0.1",
      "ServiceCharge": "0.002",
      "ServiceChargeVAT": "0",
      "ReceivableAmount": "0.098",
      "DisplayCurrency": "KWD",
      "ValueInDisplayCurrency": "0.1",
      "PayCurrency": "KWD",
      "ValueInPayCurrency": "0.1"
    }
  }
}

Webhook Signature

You will use the parameters mentioned below to generate the webhook signature for the DISPUTE_STATUS_CHANGED event.

Dispute.DisputeTransactionId=112,Dispute.Status=PENDING,Invoice.Id=5897264,Invoice.Status=PAID,Transaction.Status=SUCCESS,Transaction.PaymentId=07075897264282534874,Invoice.ExternalIdentifier=1hGonC7bf2vNuJWuTgCGURYzi6Yu

This webhook allows real-time tracking of disputes, ensuring accurate financial management and automated processing in your system.