Skip to main content
Each delivery is a JSON object. The platform injects:
where the value is Type.Action from the internal event enum.

Event types (Type)

Event actions (Action)

Common actions: Exact action availability depends on the resource.

Common merchant events

Plan

Subscription

Payment

Payments may include nested customer, plan, currency, and crypto_transaction (hash, chain_id) when relevant.

Partial proxy-wallet deposits

A wallet-transfer (ProxyWallet) payment can arrive as more than one on-chain transfer. BoomFi does not change status until the payment is accepted in full. paid_amount is on the webhook body and on GET /payments and GET /payments/{id} (same document):
  • Decimal string in major units, same currency as amount
  • Equal to min(on-chain received, amount) — overpayment is not included
  • Omitted until a deposit is observed
  • A later delivery with the same paid_amount is a retry; a larger paid_amount is a new partial
proxy_wallet is on that same document when the payment uses a proxy wallet, including each partial Payment.Updated. It is omitted otherwise. The asset symbol is the payment currency. Match a partial deposit to proxy_wallet.address, proxy_wallet.chain_id, and proxy_wallet.token_address. Those fields are stable across Payment.Created, later partial Payment.Updated deliveries, and the Succeeded delivery. You can also read them from GET /payments/{id} if a webhook was missed. Outstanding due:
Use decimal arithmetic, not floating point. Do not fulfil on a partial Payment.Updated.

Binance Connect

An ExchangePay payment collected at Binance Connect sends Payment.Created after the order exists, then Payment.Updated when the payer claims it. status stays RequiresAction on that update. Fulfil only on a later Payment.Updated with status: Succeeded. exchange_provider is BinanceConnect. The order is binance_connect on the same payment document as GET /payments/{id}: The payer identity ciphertext is never on the webhook or on GET /payments/{id}. Payment.Created already includes the order. The claim sends one Payment.Updated with user_initiated: true. A later poll does not send that event again.

Account

Account.Created, Account.Updated, and Account.Disabled fire when an external account changes. An external account is one the merchant owns: a self-custody wallet (no provider), a whitelisted paylink settlement address (CryptoPayIn), a whitelisted crypto payout address, or a whitelisted bank account. Custody accounts the platform holds do not send these three events. Account.LowBalanceDetected and Account.VirtualAccountAlert are unchanged. They are balance alerts, not registration changes. Use the registration events to monitor where money can be sent. A change you did not just make is a reason to alert and to hold payouts to that account until a person confirms it. Verify the webhook signature before you trust address.
currencies, reference, provider, created_by, bank account numbers, sort codes, and stored properties are not on this payload. A wallet address is. When the account is enabled and holds a positive balance, the same delivery also includes balances and sub_accounts:
balances here is the total per currency. account_id on that total is 0. sub_accounts is this account and its own balances. Both are omitted when there is no positive balance. One account change sends one delivery. A save that inserts, edits, and disables several accounts sends one delivery per account. List them with GET https://mapi.boomfi.xyz/v1/events?event_type=Account. GET https://mapi.boomfi.xyz/v1/orgs settlement_accounts is a different list. It is only the paylink settlement addresses. This webhook is every external account, including payout addresses and bank accounts.

Invoice

Payload conventions

Typical fields (vary by type):

Filtering noise

Some organisations configure notification properties so certain zero-amount proxy-wallet updates are not delivered until paid. Treat the event log as the source of truth for what was attempted.

Full field reference

For exhaustive schemas, use the event document models in the API reference and test against sandbox deliveries.

Next steps