Wallet Events

Sakneen Wallets reflect installment schedules, physical cheques, and collection information. They are operational views of payment obligations and collections; they are not accounting ledgers.

One Wallet mutation can emit several events. Subscribe only to the resource families your integration needs.

All Wallet events use eventVersion: 1. Their resource.version is the Wallet revision after the mutation.

Shared Wallet context

Every Wallet-family event includes:

Field	Type	Required	Description
walletId	string	Yes	Sakneen Wallet identifier
clientId	string	Yes	Client who owns the Wallet
unitId	string	Yes	Unit associated with the Wallet
currency	string	Yes	Wallet currency, such as EGP
reservationId	string	No	Related reservation
contractRequestId	string	No	Related contract request

Optional fields are omitted when unavailable.

Wallet

Event types

Event	Emitted when
wallet.created	A Wallet and its initial schedule are created
wallet.updated	Wallet-level state or its schedule changes
wallet.archived	The Wallet is archived

Additional data fields

Field	Type	Description
paymentPlanId	string, optional	Current payment plan
confirmationStatus	enum	pending or confirmed
currentScheduleVersion	positive integer	Active installment schedule version
revision	positive integer	Current Wallet revision

{
  "eventId": "019c0f01-96b6-7ef5-aa43-e7a82659ec8d",
  "eventType": "wallet.updated",
  "eventVersion": 1,
  "occurredAt": "2026-07-30T11:00:00.000Z",
  "source": "sakneen",
  "organizationId": "64f1a0d6d5d0a14a5c0e8a10",
  "correlationId": "019c0f01-96b6-7945-aa0a-9b70a0c582f9",
  "resource": {
    "type": "wallet",
    "id": "66a000000000000000000010",
    "version": 4
  },
  "data": {
    "walletId": "66a000000000000000000010",
    "clientId": "66a000000000000000000011",
    "unitId": "66a000000000000000000019",
    "reservationId": "66a000000000000000000018",
    "contractRequestId": "66a000000000000000000016",
    "currency": "EGP",
    "paymentPlanId": "66a000000000000000000017",
    "confirmationStatus": "confirmed",
    "currentScheduleVersion": 2,
    "revision": 4
  }
}

Wallet installment

Event types

Event	Emitted when
wallet_installment.created	An expected payment obligation is added
wallet_installment.updated	An installment's current state changes
wallet_installment.superseded	A newer schedule replaces the installment

Additional data fields

Field	Type	Description
installmentId	string	Installment identifier
scheduleVersion	positive integer	Schedule version that owns the installment
sourcePaymentPlanId	string, optional	Payment plan that produced it
sourceInstallmentKey	string, optional	Stable installment key from its schedule
sequence	positive integer	Position within the schedule
title	string	Display title
category	enum	club_membership, down_payment, finishing, installment, maintenance, other, or parking
expectedAmount	non-negative number	Expected amount in the Wallet currency
percentage	non-negative number, optional	Schedule percentage
dueDate	ISO 8601 string	Installment due date
lifecycleStatus	enum	active, cancelled, or superseded

{
  "walletId": "66a000000000000000000010",
  "clientId": "66a000000000000000000011",
  "unitId": "66a000000000000000000019",
  "currency": "EGP",
  "installmentId": "66a000000000000000000012",
  "scheduleVersion": 2,
  "sourcePaymentPlanId": "66a000000000000000000017",
  "sourceInstallmentKey": "installment-1",
  "sequence": 1,
  "title": "Quarterly installment",
  "category": "installment",
  "expectedAmount": 100000,
  "percentage": 10,
  "dueDate": "2026-08-15T00:00:00.000Z",
  "lifecycleStatus": "active"
}

The example above is the event's data object.

Wallet cheque

Event types

Event	Emitted when
wallet_cheque.created	A physical cheque is recorded against an installment
wallet_cheque.updated	Cheque details or status change

Additional data fields

Field	Type	Description
installmentId	string	Installment receiving the cheque
chequeId	string	Cheque identifier
number	string	Cheque number
amount	positive number	Cheque amount in the Wallet currency
bank	enum, optional	Issuing bank
dueDate	ISO 8601 string, optional	Cheque due date
status	enum	held, deposited, cleared, bounced, returned_to_client, replaced, or cancelled
replacesChequeId	string, optional	Cheque replaced by this cheque

{
  "walletId": "66a000000000000000000010",
  "clientId": "66a000000000000000000011",
  "unitId": "66a000000000000000000019",
  "currency": "EGP",
  "installmentId": "66a000000000000000000012",
  "chequeId": "66a000000000000000000013",
  "number": "CHK-10001",
  "amount": 25000,
  "bank": "National Bank of Egypt",
  "dueDate": "2026-08-15T00:00:00.000Z",
  "status": "held"
}

The bank value is one of the following strings. Preserve the exact value and accept Other.

Allowed bank values	Allowed bank values
Abu Dhabi Commercial Bank Egypt	Abu Dhabi Islamic Bank
Agricultural Bank of Egypt	Ahli United Bank
Al Ahli Bank of Kuwait	Al Baraka Bank
ALEXBANK	Arab African International Bank
Arab Bank	Arab International Bank
Attijariwafa Bank	Bank NXT
Banque du Caire	Banque Misr
Citibank	Commercial International Bank (CIB)
Credit Agricole Egypt	EG Bank
Egyptian Arab Land Bank	Emirates NBD Egypt
Export Development Bank of Egypt	Faisal Islamic Bank of Egypt
First Abu Dhabi Bank Misr	Housing and Development Bank
HSBC Bank Egypt	Industrial Development Bank
Mashreq Bank Egypt	MIDBank
National Bank of Egypt	National Bank of Kuwait Egypt
QNB Egypt	SAIB
Suez Canal Bank	The United Bank
Other

Wallet collection

Collections reflect received or attempted payment information and can allocate partial amounts to an installment.

Event types

Event	Emitted when
wallet_collection.created	Collection information is recorded
wallet_collection.updated	Collection information or status changes
wallet_collection.reversed	A recorded collection is reversed

Additional data fields

Field	Type	Description
collectionId	string	Collection identifier
installmentId	string	Installment receiving the allocation
chequeId	string, optional	Related cheque when the method is cheque
method	enum	bank_transfer, card, cash, cheque, other, or unknown
amount	positive number	Amount allocated to the installment
status	enum	pending, received, settled, failed, reversed, or unapplied
occurredAt	ISO 8601 string	Business time of the collection
source	enum	integration, migration, system, or user

{
  "walletId": "66a000000000000000000010",
  "clientId": "66a000000000000000000011",
  "unitId": "66a000000000000000000019",
  "currency": "EGP",
  "collectionId": "66a000000000000000000014",
  "installmentId": "66a000000000000000000012",
  "chequeId": "66a000000000000000000013",
  "method": "cheque",
  "amount": 25000,
  "status": "received",
  "occurredAt": "2026-08-15T10:30:00.000Z",
  "source": "integration"
}

The nested data.source identifies who recorded the collection. The top-level event envelope source remains sakneen.

Processing recommendations

• Deduplicate every event by eventId.
• Track resource.version independently for each resource.id.
• Use correlationId to trace multi-event Wallet mutations.
• Do not calculate accounting balances from delivery order.
• Treat collection events as reflected operational information, not financial settlement authority.