To enable events, configure your webhook categories in the portal under Settings > App.

Account

account_opened

Sent when a new account has been opened.

Field	Type	Description
`account_id`	uuid	The account identifier in the Lorum system
`account_type`	enum	Type of account - `primary`, `payment`, or `virtual`
`account_name`	string	The name set on the account
`customer_id`	uuid	The ID of the customer
`external_id`	string	External ID set when the account request was made
`currency`	string	ISO currency code for the account

{
  "type": "account_opened",
  "event_id": "018c35aa-4279-83e7-a90f-4b2901246c51",
  "event_version": 1,
  "account_opened": {
    "account_id": "018c35aa-4279-83e7-a90f-4b2901246c51",
    "account_name": "Contractors Inc.",
    "customer_id": null,
    "external_id": "01H2ZZV055MFPM8FD9RCJWM6R0",
    "currency": "AED",
    "account_type": "payment"
  }
}

account_updated

Sent when an account has been updated.

Field	Type	Description
`account_id`	uuid	The account identifier in the Lorum system
`account_name`	string	The name set on the account
`account_owner`	string	The owner name set on the account
`external_id`	string	External ID set when the account request was made

{
  "type": "account_updated",
  "event_id": "018c35ab-98bf-4390-bd51-858e61a87859",
  "event_version": 3,
  "account_updated": {
    "account_id": "018c35aa-4279-83e7-a90f-4b2901246c51",
    "account_name": "Contractors Ltd.",
    "account_owner": "John Contractor",
    "external_id": "01H2ZZV055MFPM8FD9RCJWM6R0"
  }
}

Payment

outbound_local_payment_created

A local payment has been initiated.

Field	Type	Description
`account_id`	uuid	The account from which the payment was made
`transaction_id`	uuid	The Lorum transaction identifier
`amount_with_fee`	integer	Transaction amount including fee in minor currency (e.g. 100 = 1.00)
`instructed_amount`	integer	Transaction amount excluding fee in minor currency
`fee_amount`	integer	Fee amount in minor currency
`remitter`	RemitterDetails	Details of the payment remitter
`beneficiary`	BeneficiaryDetails	Details of the payment beneficiary
`purpose`	PurposeCode	Purpose of the transaction
`currency`	string	ISO currency code
`external_reference`	string	Reference set by the customer when initiating the payment
`external_id`	string	External ID set on the create payment request
`timestamp`	ISO8601 datetime	Timestamp of when the event took place
`fee_source`	FeeSourceAccount	Optional fee source account details

{
  "type": "outbound_local_payment_created",
  "event_id": "018c35b3-def3-a3bb-792d-f79534562555",
  "event_version": 4,
  "outbound_local_payment_created": {
    "account_id": "018c355c-2413-16df-509f-40e71b142eb3",
    "transaction_id": "018c35b3-def2-e645-1d5b-86be6746537b",
    "instructed_amount": 51239,
    "amount_with_fee": 51239,
    "fee_amount": 0,
    "remitter": {
      "name": "Monday Inc.",
      "identifier": { "iban": "AE220910000000808720471" }
    },
    "beneficiary": {
      "name": "Fulan AlFulani",
      "identifier": { "iban": "AE120266712486572167372" }
    },
    "external_reference": "local*1701708016",
    "external_id": "01JDHZK7QKF0WWQG43WNFQ3YCX",
    "timestamp": "2023-12-04T16:40:29.683099191Z",
    "purpose": "goods_bought",
    "currency": "AED"
  }
}

outbound_local_payment_submitted

A local payment has been submitted for processing.

Field	Type	Description
`account_id`	uuid	The account from which the payment was made
`transaction_id`	uuid	The Lorum transaction identifier
`external_id`	string	External ID set on the create payment request
`timestamp`	ISO8601 datetime	Timestamp of when the event took place

{
  "type": "outbound_local_payment_submitted",
  "event_id": "018c35b3-e005-fd7b-ea42-aec8c20e521f",
  "event_version": 6,
  "outbound_local_payment_submitted": {
    "account_id": "018c355c-2413-16df-509f-40e71b142eb3",
    "transaction_id": "018c35b3-def2-e645-1d5b-86be6746537b",
    "external_id": "01JDHZK7QKF0WWQG43WNFQ3YCX",
    "timestamp": "2023-12-04T16:40:29.957851510Z"
  }
}

outbound_local_payment_executed

The local payment has been successfully processed.

Field	Type	Description
`account_id`	uuid	The account from which the payment was made
`transaction_id`	uuid	The Lorum transaction identifier
`external_id`	string	External ID set on the create payment request
`timestamp`	ISO8601 datetime	Timestamp of when the event took place

{
  "type": "outbound_local_payment_executed",
  "event_id": "018c35b4-030f-a403-dfe2-7c757e94f00b",
  "event_version": 7,
  "outbound_local_payment_executed": {
    "account_id": "018c355c-2413-16df-509f-40e71b142eb3",
    "transaction_id": "018c35b3-def2-e645-1d5b-86be6746537b",
    "external_id": "01JDHZK7QKF0WWQG43WNFQ3YCX",
    "timestamp": "2023-12-04T16:40:38.927642874Z"
  }
}

outbound_local_payment_failed

The local payment attempt was unsuccessful.

Field	Type	Description
`account_id`	uuid	The account from which the payment was made
`transaction_id`	uuid	The Lorum transaction identifier
`external_id`	string	External ID set on the create payment request
`timestamp`	ISO8601 datetime	Timestamp of when the event took place
`failure_reason`	FailureReason	Cause of the payment failure

{
  "type": "outbound_local_payment_failed",
  "event_id": "018c35b9-fbdc-8081-969a-bc591888d2e6",
  "event_version": 12,
  "outbound_local_payment_failed": {
    "account_id": "018c0027-a9b0-1f65-54ea-fe723844940f",
    "transaction_id": "018c35b9-8f58-9b36-370d-b5e3f00705ff",
    "failure_reason": { "bank_error": "Manual failure in Portal" },
    "external_id": "01JDHZK7QKF0WWQG43WNFQ3YCX",
    "timestamp": "2023-12-04T16:47:10.300679370Z"
  }
}

outbound_local_payment_returned

A previously executed local payment has been returned by the beneficiary's bank.

Field	Type	Description
`account_id`	uuid	The account from which the payment was made
`transaction_id`	uuid	The Lorum transaction identifier for the original payment
`returned_transaction_id`	uuid	The Lorum transaction identifier for the return
`amount`	integer	Amount in minor currency (e.g. 100 = 1.00)
`remitter`	RemitterDetails	Details of the payment remitter
`beneficiary`	BeneficiaryDetails	Details of the payment beneficiary
`external_reference`	string	Reference set by the customer when initiating the payment
`timestamp`	ISO8601 datetime	Timestamp of the return event
`currency`	string	ISO currency code
`returned_reason`	string	Reason provided by the beneficiary's bank for the return

{
  "type": "outbound_local_payment_returned",
  "event_id": "018c35ba-1234-5678-9abc-def012345678",
  "event_version": 1,
  "outbound_local_payment_returned": {
    "account_id": "018c355c-2413-16df-509f-40e71b142eb3",
    "transaction_id": "018c35b3-def2-e645-1d5b-86be6746537b",
    "returned_transaction_id": "018c35ba-9876-5432-10fe-dcba98765432",
    "amount": 51239,
    "remitter": {
      "name": "Monday Inc.",
      "identifier": { "iban": "AE220910000000808720471" }
    },
    "beneficiary": {
      "name": "Fulan AlFulani",
      "identifier": { "iban": "AE120266712486572167372" }
    },
    "external_reference": "local*1701708016",
    "timestamp": "2023-12-05T10:15:30.123456789Z",
    "currency": "AED",
    "returned_reason": "Account closed"
  }
}

inbound_local_payment_settled

An inbound local payment has settled into the account.

Field	Type	Description
`account_id`	uuid	The account the payment settled into
`transaction_id`	uuid	The Lorum transaction identifier
`amount_with_fee`	integer	Transaction amount including fee in minor currency
`instructed_amount`	integer	Transaction amount excluding fee in minor currency
`fee_amount`	integer	Fee amount in minor currency
`remitter`	RemitterDetails	Details of the payment remitter
`beneficiary`	BeneficiaryDetails	Details of the payment beneficiary
`purpose`	PurposeCode	Purpose of the transaction
`currency`	string	ISO currency code
`external_reference`	string	Reference set by the customer when initiating the payment
`timestamp`	ISO8601 datetime	Timestamp of when the event took place
`fee_source`	FeeSourceAccount	Optional fee source account details

{
  "type": "inbound_local_payment_settled",
  "event_id": "018c35bc-9019-34b2-5210-ff9900d349bd",
  "event_version": 40,
  "inbound_local_payment_settled": {
    "account_id": "018bfd91-ea86-a787-9d72-754cddfbc294",
    "transaction_id": "018c35bc-9086-638d-0e9a-f1f46ea6146a",
    "instructed_amount": 100000000,
    "amount_with_fee": 100000000,
    "fee_amount": 0,
    "remitter": {
      "name": "Topup",
      "identifier": { "iban": "AE080070000000785666509" }
    },
    "beneficiary": {
      "name": "AED Merchant Account",
      "identifier": { "iban": "AE460266386228195554412" }
    },
    "external_reference": "funding*1701708590",
    "timestamp": "2023-12-04T16:49:59.325104057Z",
    "purpose": "none",
    "currency": "AED"
  }
}

fee_debited

A fee has been debited from an account. Triggered when fees are collected separately from the main transaction.

Field	Type	Description
`transaction_id`	uuid	Unique identifier of the fee debit transaction
`account_id`	uuid	The account from which the fee was debited
`amount`	integer	Fee amount in minor currency (e.g. 100 = 1.00)
`timestamp`	ISO8601 datetime	Timestamp of when the fee was debited
`fee_target.type`	enum	The type of entity the fee was applied to (e.g. `transaction`)
`fee_target.reference`	uuid	Identifier of the entity the fee was charged against
`currency`	string	Currency in which the fee was debited

{
  "type": "fee_debited",
  "event_id": "49cd3525-bb13-4e85-8df0-a85741c2bc51",
  "event_version": 268,
  "fee_debited": {
    "transaction_id": "019c2978-2271-7bc1-8fd9-c2c183e1f354",
    "account_id": "0196b31a-bbd8-7d14-b333-a1465359b52d",
    "amount": 918,
    "timestamp": "2026-02-04T16:25:31.870483469Z",
    "fee_target": {
      "type": "Transaction",
      "reference": "019c2978-0714-7e93-8f4f-b2c3030e6831"
    },
    "currency": "AED"
  }
}

Transfer

internal_transfer_created

An internal transfer between two accounts has been initiated.

Field	Type	Description
`account_id`	uuid	The account from which the transfer is made
`transaction_id`	uuid	The Lorum transaction identifier
`amount`	integer	Amount in minor currency (e.g. 100 = 1.00)
`to_account_id`	uuid	The destination account
`reference`	string	Reference set by the customer when initiating the transfer
`external_id`	string	External ID set on the create transfer request
`timestamp`	ISO8601 datetime	Timestamp of when the event took place

{
  "type": "internal_transfer_created",
  "event_id": "018c35ad-e939-11e1-b8ac-0896580ef2f6",
  "event_version": 38,
  "internal_transfer_created": {
    "account_id": "018bfd91-ea86-a787-9d72-754cddfbc294",
    "transaction_id": "018c35ad-e939-eea5-d179-495d3fe1a783",
    "amount": 1000000,
    "to_account_id": "018c355c-2413-16df-509f-40e71b142eb3",
    "reference": "transfer-1701707629",
    "external_id": "01JDHZK7QKF0WWQG43WNFQ3YCX",
    "timestamp": "2023-12-04T16:33:59.155913761Z"
  }
}

inbound_internal_transfer_settled

An internal transfer into the account has completed and settled.

Field	Type	Description
`account_id`	uuid	The account the transfer settled into
`from_account_id`	uuid	The source account
`transaction_id`	uuid	The Lorum transaction identifier
`amount`	integer	Amount in minor currency (e.g. 100 = 1.00)
`reference`	string	Reference set by the customer when initiating the transfer
`external_id`	string	External ID set on the create transfer request
`timestamp`	ISO8601 datetime	Timestamp of when the event took place

{
  "type": "inbound_internal_transfer_settled",
  "event_id": "018c35ad-e9ab-ae02-28a0-ebc9d3b70a89",
  "event_version": 3,
  "inbound_internal_transfer_settled": {
    "account_id": "018c355c-2413-16df-509f-40e71b142eb3",
    "from_account_id": "018bfd91-ea86-a787-9d72-754cddfbc294",
    "transaction_id": "018c35ad-e9ab-ae02-28a0-ebc9d3b70a89",
    "amount": 1000000,
    "timestamp": "2023-12-04T16:33:59.211640Z",
    "reference": "transfer-1701707629",
    "external_id": "01JDHZK7QKF0WWQG43WNFQ3YCX"
  }
}

internal_transfer_settled

A transfer from the account has completed.

Field	Type	Description
`account_id`	uuid	The account from which the transfer settled
`transaction_id`	uuid	The Lorum transaction identifier
`external_id`	string	External ID set on the create transfer request
`timestamp`	ISO8601 datetime	Timestamp of when the event took place

{
  "type": "internal_transfer_settled",
  "event_id": "018c35ad-ea8e-031c-55ec-86af02893c79",
  "event_version": 39,
  "internal_transfer_settled": {
    "account_id": "018bfd91-ea86-a787-9d72-754cddfbc294",
    "transaction_id": "018c35ad-e939-eea5-d179-495d3fe1a783",
    "external_id": "01JDHZK7QKF0WWQG43WNFQ3YCX",
    "timestamp": "2023-12-04T16:33:59.211640Z"
  }
}

internal_transfer_failed

An internal transfer between two accounts was unsuccessful.

Field	Type	Description
`account_id`	uuid	The account from which the transfer was attempted
`transaction_id`	uuid	The Lorum transaction identifier
`external_id`	string	External ID set on the create transfer request
`timestamp`	ISO8601 datetime	Timestamp of when the event took place
`failure_reason`	FailureReason	Cause of the transfer failure

{
  "type": "internal_transfer_failed",
  "event_id": "697cc542-aa22-4ee3-a278-949d59f24b15",
  "event_version": 44,
  "internal_transfer_failed": {
    "account_id": "018bfd91-ea86-a787-9d72-754cddfbc294",
    "transaction_id": "018c35ad-e939-eea5-d179-495d3fe1a783",
    "timestamp": "2023-12-04T16:33:59.211640Z",
    "failure_reason": "insufficient_funds",
    "external_id": "01JDHZK7QKF0WWQG43WNFQ3YCX"
  }
}

Exchange Transfer

outbound_exchange_transfer_created

A currency exchange from one account to another has been initiated.

Field	Type	Description
`account_id`	uuid	The source account
`counterpart_account_id`	uuid	The destination account
`transaction_id`	uuid	The Lorum transaction identifier
`currency`	string	Source currency
`amount`	integer	Source amount in minor currency (e.g. 100 = 1.00)
`counterpart_currency`	string	Destination currency
`counterpart_amount`	integer	Destination amount in minor currency
`external_reference`	string	Reference set by the customer when initiating the exchange
`rate`	decimal	Exchange rate used for the conversion
`timestamp`	ISO8601 datetime	Timestamp of when the event took place

{
  "type": "outbound_exchange_transfer_created",
  "event_id": "019482b0-57d7-765c-bd23-2235f5d5aaab",
  "event_version": 29,
  "outbound_exchange_transfer_created": {
    "account_id": "01917542-1b7a-7c0c-a39b-17c96d0c7b53",
    "counterpart_account_id": "019342ec-af92-7470-9af9-7543cc6daf71",
    "transaction_id": "019482b0-57d7-765c-bd23-2235f5d5aaab",
    "amount": 10000,
    "counterpart_amount": 36615,
    "external_reference": "reference-123",
    "timestamp": "2024-10-10T07:49:42.487717774Z",
    "currency": "USD",
    "counterpart_currency": "AED",
    "rate": 3.6615
  }
}

outbound_exchange_transfer_submitted

A currency exchange has been submitted for processing.

Field	Type	Description
`account_id`	uuid	The source account
`transaction_id`	uuid	The Lorum transaction identifier
`timestamp`	ISO8601 datetime	Timestamp of when the event took place

{
  "type": "outbound_exchange_transfer_submitted",
  "event_id": "019482b0-871d-7d54-8346-a066ecc69221",
  "event_version": 30,
  "outbound_exchange_transfer_submitted": {
    "account_id": "01917542-1b7a-7c0c-a39b-17c96d0c7b53",
    "transaction_id": "019482b0-57d7-765c-bd23-2235f5d5aaab",
    "timestamp": "2024-10-10T07:49:54.649511283Z"
  }
}

outbound_exchange_transfer_executed

The currency exchange has been completed successfully.

Field	Type	Description
`account_id`	uuid	The source account
`transaction_id`	uuid	The Lorum transaction identifier
`timestamp`	ISO8601 datetime	Timestamp of when the event took place

{
  "type": "outbound_exchange_transfer_executed",
  "event_id": "019482b0-871d-7d54-8346-a066ecc69221",
  "event_version": 31,
  "outbound_exchange_transfer_executed": {
    "account_id": "01917542-1b7a-7c0c-a39b-17c96d0c7b53",
    "transaction_id": "019482b0-57d7-765c-bd23-2235f5d5aaab",
    "timestamp": "2024-10-10T07:49:54.649511283Z"
  }
}

inbound_exchange_transfer_settled

The converted funds have settled into the destination account.

Field	Type	Description
`account_id`	uuid	The destination account
`counterpart_account_id`	uuid	The source account
`transaction_id`	uuid	The Lorum transaction identifier
`currency`	string	Destination currency
`amount`	integer	Destination amount in minor currency
`counterpart_currency`	string	Source currency
`counterpart_amount`	integer	Source amount in minor currency
`external_reference`	string	Reference set by the customer when initiating the exchange
`rate`	decimal	Exchange rate used for the conversion
`timestamp`	ISO8601 datetime	Timestamp of when the event took place

{
  "type": "inbound_exchange_transfer_settled",
  "event_id": "019482b0-8772-7a46-8792-73d9990dabd1",
  "event_version": 20,
  "inbound_exchange_transfer_settled": {
    "account_id": "019342ec-af92-7470-9af9-7543cc6daf71",
    "counterpart_account_id": "01917542-1b7a-7c0c-a39b-17c96d0c7b53",
    "transaction_id": "019482b0-873e-7f40-9ffe-1e3e298cbb10",
    "amount": 36615,
    "counterpart_amount": 10000,
    "external_reference": "reference-123",
    "timestamp": "2024-10-10T07:49:54.747094304Z",
    "currency": "AED",
    "counterpart_currency": "USD",
    "rate": 3.6615
  }
}

outbound_exchange_transfer_failed

The currency exchange was unsuccessful.

Field	Type	Description
`account_id`	uuid	The source account
`transaction_id`	uuid	The Lorum transaction identifier
`timestamp`	ISO8601 datetime	Timestamp of when the event took place
`failure_reason`	FailureReason	Cause of the exchange failure

{
  "type": "outbound_exchange_transfer_failed",
  "event_id": "019482c7-c58d-7240-9850-9c76883b54cf",
  "event_version": 35,
  "outbound_exchange_transfer_failed": {
    "account_id": "01917542-1b7a-7c0c-a39b-17c96d0c7b53",
    "transaction_id": "019482c7-b534-7e55-a2f8-37ddb441866f",
    "failure_reason": { "bank_error": "Manual failure in Portal" },
    "timestamp": "2024-10-10T08:15:17.983389023Z"
  }
}

Onboarding

onboarding_completed

Customer onboarding for a currency has been successfully completed.

Field	Type	Description
`customer_id`	uuid	The unique identifier for the customer
`currency`	string	ISO currency code for the onboarded currency

{
  "type": "onboarding_completed",
  "event_id": "018c35aa-4279-83e7-a90f-4b2901246c51",
  "event_version": 0,
  "onboarding_completed": {
    "customer_id": "018c35aa-4279-83e7-a90f-4b2901246c51",
    "currency": "AED"
  }
}

onboarding_failed

Customer onboarding for a currency has failed.

Field	Type	Description
`customer_id`	uuid	The unique identifier for the customer
`currency`	string	ISO currency code for the onboarded currency
`failure_reason.msg`	string	Human-readable description of the failure
`failure_reason.code`	ErrorCode	Machine-readable error code

ErrorCode values:

Code	Description
`missing_document`	A required document is missing
`missing_currency_data`	Currency-specific data is missing from the customer record
`no_shareholders`	Business customer has no shareholders linked
`insufficient_majority_ownership`	Linked shareholders do not meet the 51% ownership threshold
`shareholder_not_onboarded`	A shareholder is not onboarded to the specified currency
`business_registration_date_missing`	Business registration date is missing
`individual_missing_proof_of_address_document`	Individual is missing a proof of address document
`business_missing_proof_of_address_document`	Business is missing a proof of address document

{
  "type": "onboarding_failed",
  "event_id": "018c35aa-4279-83e7-a90f-4b2901246c51",
  "event_version": 0,
  "onboarding_failed": {
    "customer_id": "018c35aa-4279-83e7-a90f-4b2901246c51",
    "currency": "AED",
    "failure_reason": {
      "msg": "Individual `018c35aa-4279-83e7-a90f-4b2901246c51` does not have document `passport`",
      "code": "missing_document"
    }
  }
}