---
updatedAt: 2026-02-16T08:50:28.000Z
agentTools:
  projectIndex: https://docs.myfatoorah.com/llms.txt
---

# 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 MyFatoorah.                                      |
| 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 MyFatoorah 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 MyFatoorah |
| 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 MyFatoorah to your endpoint.

```json
{
  "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.