Balance Transferred Data Model

Overview

The "Balance Transferred" webhook is triggered whenever a balance transfer is completed. This webhook ensures that your system is notified of bank deposits for suppliers or vendors, allowing for real-time updates and appropriate financial reconciliation.

Your webhook endpoint will receive a POST request containing an event with a Code of 3 and Name of BALANCE_TRANSFERRED. This event is particularly useful for tracking deposits made to vendors or suppliers.

Request Model

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

Event Object

Input Parameter	Type	Description
Event.Code	number	3 - BALANCE_TRANSFERRED
Event.Name	string	BALANCE_TRANSFERRED
Event.CountryIsoCode	string	The country of your account with MyFatoorah.
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.

Deposit Object

Input Parameter	Type	Description
Deposit.Reference	string	A unique reference number assigned to the deposit.
Deposit.BaseCurrency	string	The base currency of your MyFatoorah account (e.g., KWD).
Deposit.ValueInBaseCurrency	string	The transferred balance amount in the base currency.
Deposit.NumberOfTransactions	string	The number of transactions included in the deposit.
Deposit.DepositDate	datetime	The date and time when the deposit was made, formatted in ISO 8601.

Supplier Object (If applicable)

Input Parameter	Type	Description
Supplier.Code	string	Unique identifier for the supplier who received the deposit.
Supplier.Name	string	The name of the supplier.

Note: The Supplier object will be null for vendor deposits.

Bank Object

Input Parameter	Type	Description
Bank.Name	string	The name of the bank where the deposit was made.
Bank.IBAN	string	The IBAN (International Bank Account Number).
Bank.AccountNumber	string	The account number associated with the deposit.

Sample Event

Supplier Balance Transferred

{
  "Event": {
    "Code": 3,
    "Name": "BALANCE_TRANSFERRED",
    "CountryIsoCode": "KWT",
    "CreationDate": "2025-05-13T06:12:24.8570000Z",
    "Reference": "WH-128055"
  },
  "Data": {
    "Deposit": {
      "Reference": "2025000006",
      "BaseCurrency": "KWD",
      "ValueInBaseCurrency": "15968.333",
      "NumberOfTransactions": "511",
      "DepositDate": "2025-05-13T06:12:00Z"
    },
    "Supplier": null,
    "Bank": {
      "Name": "Test NBK",
      "IBAN": "SA2405000068200013262001",
      "AccountNumber": "12345678"
    }
  }
}

{
  "Event": {
    "Code": 3,
    "Name": "BALANCE_TRANSFERRED",
    "CountryIsoCode": "KWT",
    "CreationDate": "2025-05-13T06:14:35.8600000Z",
    "Reference": "WH-128058"
  },
  "Data": {
    "Deposit": {
      "Reference": "2025000302",
      "BaseCurrency": "KWD",
      "ValueInBaseCurrency": "28732.467",
      "NumberOfTransactions": "221",
      "DepositDate": "2025-05-13T06:14:00Z"
    },
    "Supplier": {
      "Code": "1",
      "Name": "Hinds Hall"
    },
    "Bank": {
      "Name": "Riyad Bank",
      "IBAN": "SA0330100827000000050061",
      "AccountNumber": "123456789"
    }
  }
}

Webhook Signature

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

Deposit.Reference=2025000006,Deposit.ValueInBaseCurrency=15968.333,Deposit.NumberOfTransactions=511

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