Merchant account webhooks

Merchant account notifications are sent to your webhook URI registered in Console when certain merchant account-related events happen.


The balance_notification webhook is an optional webhook that informs you when a merchant account's balance is approaching a threshold you've specified. This webhook is optional, and you can contact us to enable it, also specifying the threshold that you want the webhook to inform you of.

Learn more about low balance notifications .

typestringThe type of the event ("balance_notification")
event_idstringThe unique UUID for that specific event.
event_versionnumberThe version of the event schema.
merchant_account_idstringThe ID of the merchant account this notification is about.
current_balance_in_minornumberThe current balance of the merchant account this notification is about.
available_balance_in_minornumberThe available balance of the merchant account this notification is about.
threshold_in_minornumberThe threshold specified for this merchant account by contacting TrueLayer.

The threshold should be an amount in minor.
statusanyThe status for a balance notification can be one of three values:

- approaching_threshold: Returned when the merchant account balance is goes below 150% of the threshold_in_minor.
- below_threshold: Returned when the merchant account balance goes below the threshold_in_minor.
- recovered: Returned when the new merchant account balance exceeds 200% of the specified threshold after you top up your account.
  "type": "balance_notification",
  "event_version": 1,
  "event_id": "b8d4dda0-ff2c-4d77-a6da-4615e4bad941",
  "merchant_account_id": "b8d4dda0-ff2c-4d77-a6da-4615e4bad941",
	"current_balance_in_minor": 1500,
	"available_balance_in_minor": 1500,
	"threshold_in_minor": 1000,
	"status": "approaching_threshold"



Although this webhook is a merchant account webhook, it's essential to most integrations so it's also explained within our payment webhook section .

You'll get the external_payment_received notification when a payment, made using a payment method not offered by TrueLayer, to a merchant account has settled in that merchant account. The following table includes the fields that appear in the notification body:

typestringNoType of the event ("external_payment_received")
event_idstringNoA UUID for the event
event_versionstringNoThe version of the event schema
transaction_idstringNoThe unique ID for the transaction
currencystringNoThe currency of the payment
amount_in_minorstringNoThe amount of the payment
settled_atdatetimeNoAn RFC-3339 timestamp of when the payment was settled
merchant_account_idstringNoThe unique ID for the Merchant Account
remitter.account_holder_namestringNoThe remitter information of the payment
remitter.account_identifiersarrayNoThe remitter account identifiers of the payment. We support the following identifiers: sort_code_account_number, iban, bban, nrb
remitter.referencestringNoThe reference for the payment you received from an external source.
  "type": "external_payment_received",
  "event_version": 1,
  "event_id": "b8d4dda0-ff2c-4d77-a6da-4615e4bad941",
  "transaction_id": "7806739d-1944-44d9-a1b8-5d2cd079676b",
  "currency": "GBP",
  "amount_in_minor": 1,
  "settled_at": "2021-12-25T15:00:00.000Z",
  "merchant_account_id": "200552da-13da-43c5-a9ba-04ee1502ac57",
  "remitter": {
    "account_holder_name": "Example remitter name",
    "account_identifiers": [{
      "type": "sort_code_account_number",
      "sort_code": "12-34-56",
      "account_number": "12345678"
      "type": "iban",
      "iban": "GB29NWBK60161331926819"
    "reference":"Example payment reference"

external_payment_received webhook behaviour

There are two different behaviours for the external_payment_received webhook. The behaviour depends on whether you have enabled automatic refunds for payments from external sources or not.

A external payment in the context of this webhook usally refers to the following three scenarios:

  • When an existing user pays into your merchant account again using saved SCAN/IBAN details.
    For example, through a Send again button in their banking app.
  • When you fund your merchant account from a corporate bank account through your SCAN/IBAN details.
  • When a new and unknown user pays into your account using your merchant account's SCAN/IBAN details.

Out of the above scenarios, you likely only want to keep funds from an existing user or your corporate bank account, not an unknown user. Automatic refunds solve this problem, but you can also implement various measures to mitigate the risk of payments from external sources.


Note that any payments that return the external_payment_received webhook have a Type of External Deposit in the Console payments view.

Behaviour with automatic refunds enabled

If automatic refunds are enabled, you usually receive no external_payment_received webhook when you receive an external payment. The reason for this is that the payment is automatically received and then refunded, so the webhook isn't surfaced.

You do however see two payments in the Console payments view:

  • An external deposit.
  • An open-loop payout, which is sent 1 hour after the initial external deposit.

However, in some cases, the payout to refund a payment is blocked or rejected by the remitter bank (for example, if the account was closed). In this case you receive the external_payment_received webhook, and another external deposit displays in Console.

Default behaviour without automatic refunds enabled

By default, without automatic refunds enabled, you receive the external_payment_received webhook for each payment from an external source. Each of these payments have a Type of External Deposit in the Console payments view.

If you're receiving external_payment_received payments, there are a number of approaches you can take to handle these:

  • Enable automatic refunds for your integration.
  • Create an allow list of bank details you want to accept payments from.
  • Flag them for manual review.
  • Develop your own logic to automatically return external payments as a payout, by either using the information in the external_payment_received webhook, or from the /v3/merchant-accounts/{id}/transactions endpoint.