Refund Data Model

Data Model

Overview

The "Refund Status Changed" webhook is triggered whenever there is an update to the status of a refund transaction. This webhook ensures that your system is notified of any changes in the refund status, allowing for real-time updates and appropriate actions.

Your webhook endpoint will receive a POST request containing an event with a Code of 2 and Name of REFUND_STATUS_CHANGED. This event is particularly useful for keeping track of refunded transactions, ensuring that your system updates the refund status accurately.

Request Model

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

Event Object

Input Parameter	Type	Description
Event.Code	number	2 - REFUND_STATUS_CHANGED
Event.Name	string	REFUND_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. Time zone is in UTC.
Event.Reference	string	Unique reference ID for the webhook event.

Data Object

The Data Object contains several nested objects inside of it as below.

Refund Object

Input Parameter	Type	Description
Refund.Id	number	Unique identifier for the refund transaction.
Refund.Reference	string	A unique reference number assigned to the refund transaction.
Refund.Status	string	The current status of the refund (REFUNDED - CANCELED).
Refund.InvoiceId	string	The invoice ID associated with the refund.
Refund.CreationDate	datetime	The date and time when the refund request was created, formatted in ISO 8601.
Refund.RefundDate	datetime	The date and time when the refund was processed, formatted in ISO 8601.
Refund.RRN	string	Retrieval Reference Number (RRN) for tracking the refund transaction.
Refund.Comment	string	Optional comments provided by nstFi during the refund process
Refund.VendorComment	string	Optional comment sent by the vendor to issue the refund.

Amount Object

Input Parameter	Type	Description
Amount.BaseCurrency	string	The base currency of your account with nstFi
Amount.ValueInBaseCurrency	string	The refunded amount in the base currency.

Amount Distribution

Input Parameter	Type	Description
Amount.Distribution.Vendor	string	The portion of the refund amount allocated to the vendor.
Amount.Distribution.Suppliers	array	The portion of the refund amount allocated to suppliers. (if any).

Suppliers Array

Input Parameter	Type	Description
Amount.Distribution.Suppliers[].Code	number	Unique identifier for the supplier.
Amount.Distribution.Suppliers[].Name	string	The name of the supplier.
Amount.Distribution.Suppliers[].Amount	string	The amount deducted from the supplier.

Referenced Invoice Object

Input Parameter	Type	Description
ReferencedInvoice.Id	string	The InvoiceId of the original invoice associated with the refund.
ReferencedInvoice.Reference	string	The reference number of the original invoice.
ReferencedInvoice.PaymentMethod	string	The payment method used for the original transaction (e.g., VISA/MASTER).
ReferencedInvoice.BaseCurrency	string	The base currency of your account (e.g., KWD).
ReferencedInvoice.ValueInBaseCurrency	string	The total value of the original invoice in base currency.
ReferencedInvoice.RemainingValueInBaseCurrency	string	The remaining amount in base currency after the refund.

Sample Event

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

{
  "Event": {
    "Code": 2,
    "Name": "REFUND_STATUS_CHANGED",
    "CountryIsoCode": "KWT",
    "CreationDate": "2025-05-13T06:06:20.4000000Z",
    "Reference": "WH-128044"
  },
  "Data": {
    "Refund": {
      "Id": "111147",
      "Reference": "2025000058",
      "Status": "REFUNDED",
      "InvoiceId": "5620292",
      "CreationDate": "2025-05-13T06:06:19.247Z",
      "RefundDate": "2025-05-13T06:06:20.2019805Z",
      "RRN": "513306098825",
      "Comment": "",
      "VendorComment": "Supplier Refund"
    },
    "Amount": {
      "BaseCurrency": "KWD",
      "ValueInBaseCurrency": "30",
      "Distribution": {
        "Vendor": "10",
        "Suppliers": [
          {
            "Code": 1,
            "Name": "Hinds Hall",
            "Amount": "20"
          }
        ]
      }
    },
    "ReferencedInvoice": {
      "Id": "5620277",
      "Reference": "2025042457",
      "ExternalIdentifier": "1Q3bpLfxwqnTd3NtP3LELbCNi5oi4fZBU",
      "PaymentMethod": "VISA/MASTER",
      "BaseCurrency": "KWD",
      "ValueInBaseCurrency": "64.32",
      "RemainingValueInBaseCurrency": "34.32"
    }
  }
}

Webhook Signature

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

Refund.Id=111147,Refund.Status=REFUNDED,Amount.ValueInBaseCurrency=30,ReferencedInvoice.Id=5620277

This webhook allows real-time tracking of refund transactions, ensuring accurate reconciliation and financial updates in your system.