Event catalogue

62 event types across 16 areas: a selection of what the platform sends. The API serves the full catalogue from GET /webhook/event-type; read it from there in your tooling rather than from this page.

Customers and KYC · 2

holder.tier_changed A holder's KYC tier moved up or down. Limits and permitted operations follow from the tier, so refetch them on this event rather than assuming what the new tier allows.

Subject: account_holder · apiVersion 1.0

upgrade is derived, not a status. Refetch the tier's limits on this event rather than assuming what tier 2 allows.

{
  "id": "74503979-9bd4-4545-9844-c7d6915bab41",
  "type": "holder.tier_changed",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "account_holder",
    "reference": "b7e2d1c0-3f4a-4b5c-9d8e-7f6a5b4c3d2e"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "holderReference": "b7e2d1c0-3f4a-4b5c-9d8e-7f6a5b4c3d2e",
    "previousTier": 1,
    "currentTier": 2,
    "upgrade": true
  }
}

account_holder.registered A new account holder completed registration.

Subject: account_holder · apiVersion 1.0

Two references and nothing else. tier and registeredAt exist on the payload type but are not populated on this path, so they are absent from the delivered body.

{
  "id": "bfd6b7e1-7929-446c-9857-133f422e9c1e",
  "type": "account_holder.registered",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "account_holder",
    "reference": "b7e2d1c0-3f4a-4b5c-9d8e-7f6a5b4c3d2e"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "holderReference": "b7e2d1c0-3f4a-4b5c-9d8e-7f6a5b4c3d2e",
    "userReference": "d4c3b2a1-9f8e-4d7c-6b5a-4f3e2d1c0b9a"
  }
}

Accounts · 4

account.opened A financial account was opened and is immediately usable. Until this event there is no way for an integrator to learn that an account they asked for is ready.

Subject: financial_account · apiVersion 1.0

The event integrators were previously polling GET /account in a loop to discover.

{
  "id": "8a16768c-c73d-4be8-9dc7-3fb17b2120c3",
  "type": "account.opened",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "financial_account",
    "reference": "a3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "a3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "accountNumber": "0123456789",
    "type": "savings",
    "status": "active",
    "currency": "NGN",
    "holderReference": "b7e2d1c0-3f4a-4b5c-9d8e-7f6a5b4c3d2e",
    "organizationReference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  }
}

account.frozen An account was frozen. Debits and credits are both refused while it stays this way.

Subject: financial_account · apiVersion 1.0

{
  "id": "c6436ef3-6912-4a90-93d9-0f36b677e507",
  "type": "account.frozen",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "financial_account",
    "reference": "a3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "a3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "accountNumber": "0123456789",
    "type": "savings",
    "status": "frozen",
    "currency": "NGN",
    "holderReference": "b7e2d1c0-3f4a-4b5c-9d8e-7f6a5b4c3d2e",
    "organizationReference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  }
}

account.unfrozen A frozen account was returned to active. Paired with account.frozen so a subscriber that paused a customer has something to resume on.

Subject: financial_account · apiVersion 1.0

Same shape as account.frozen; only status differs. Route on type, not on the body.

{
  "id": "02c1619c-d828-4fd2-935f-fb09768ca7a2",
  "type": "account.unfrozen",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "financial_account",
    "reference": "a3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "a3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "accountNumber": "0123456789",
    "type": "savings",
    "status": "active",
    "currency": "NGN",
    "holderReference": "b7e2d1c0-3f4a-4b5c-9d8e-7f6a5b4c3d2e",
    "organizationReference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  }
}

account.closed An account was closed. This is terminal: it will not reopen, and a new account is the way forward.

Subject: financial_account · apiVersion 1.0

{
  "id": "5528f933-25b5-4c29-91c5-589add0c8549",
  "type": "account.closed",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "financial_account",
    "reference": "a3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "a3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "accountNumber": "0123456789",
    "type": "savings",
    "status": "closed",
    "currency": "NGN",
    "holderReference": "b7e2d1c0-3f4a-4b5c-9d8e-7f6a5b4c3d2e",
    "organizationReference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  }
}

Money movement · 5

transfer.completed A peer-to-peer transfer posted successfully to both legs.

Subject: transfer · apiVersion 1.0

The destination account number is masked and the source is not. You own the source; the destination is a counterparty.

{
  "id": "a6d10d7c-83a1-4164-9e37-73ca95fce9b1",
  "type": "transfer.completed",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "financial_transaction",
    "reference": "3f1c6a2e-8b47-4d19-9a0e-15d2c7b8e441"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "3f1c6a2e-8b47-4d19-9a0e-15d2c7b8e441",
    "type": "PEER_TRANSFER",
    "status": "COMPLETED",
    "amount": {
      "amount": "5000.00",
      "currency": "NGN"
    },
    "fee": {
      "amount": "26.88",
      "currency": "NGN"
    },
    "narration": "October rent",
    "postedAt": "2026-08-21T10:14:22.101",
    "source": {
      "accountNumber": "0123456789"
    },
    "destination": {
      "accountNumber": "987*****210",
      "beneficiaryReference": "5c3a08f1-7b62-4e94-a10d-8f2b6c05d739"
    }
  }
}

withdrawal.completed A withdrawal to an external account settled with the provider.

Subject: withdrawal · apiVersion 1.0

{
  "id": "4f7dbc29-6c67-4e9c-9205-c69084c4bcd5",
  "type": "withdrawal.completed",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "financial_transaction",
    "reference": "3f1c6a2e-8b47-4d19-9a0e-15d2c7b8e441"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "3f1c6a2e-8b47-4d19-9a0e-15d2c7b8e441",
    "type": "WITHDRAWAL",
    "status": "COMPLETED",
    "amount": {
      "amount": "120000.00",
      "currency": "NGN"
    },
    "fee": {
      "amount": "53.75",
      "currency": "NGN"
    },
    "narration": "Payout to settlement account",
    "postedAt": "2026-08-21T10:14:22.101",
    "source": {
      "accountNumber": "0123456789"
    },
    "destination": {
      "beneficiaryReference": "5c3a08f1-7b62-4e94-a10d-8f2b6c05d739"
    }
  }
}

withdrawal.failed Failure A withdrawal did not settle and the debit has been reversed. Subscribe to this alongside withdrawal.completed: a payout that fails is otherwise indistinguishable from one still in flight, and the funds are already back.

Subject: withdrawal · apiVersion 1.0

The debit has been reversed. failureReason is the provider's words: display it, do not branch on it. The machine-readable half is failureKind on the delivery record.

{
  "id": "2aeabc01-e487-4bb4-9d87-ccf652bfca02",
  "type": "withdrawal.failed",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "financial_transaction",
    "reference": "3f1c6a2e-8b47-4d19-9a0e-15d2c7b8e441"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "3f1c6a2e-8b47-4d19-9a0e-15d2c7b8e441",
    "type": "WITHDRAWAL",
    "status": "FAILED",
    "amount": {
      "amount": "120000.00",
      "currency": "NGN"
    },
    "fee": {
      "amount": "53.75",
      "currency": "NGN"
    },
    "narration": "Payout to settlement account",
    "postedAt": "2026-08-21T10:14:22.101",
    "failureReason": "Beneficiary account is dormant at the receiving institution",
    "source": {
      "accountNumber": "0123456789"
    },
    "destination": {
      "beneficiaryReference": "5c3a08f1-7b62-4e94-a10d-8f2b6c05d739"
    }
  }
}

deposit.completed A deposit was credited to an account.

Subject: deposit · apiVersion 1.0

fee is absent when there was no fee, not zero. Only the destination side is populated.

{
  "id": "8faf7810-feb7-47df-934a-b68e4886f417",
  "type": "deposit.completed",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "financial_transaction",
    "reference": "3f1c6a2e-8b47-4d19-9a0e-15d2c7b8e441"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "3f1c6a2e-8b47-4d19-9a0e-15d2c7b8e441",
    "type": "DEPOSIT",
    "status": "COMPLETED",
    "amount": {
      "amount": "75000.00",
      "currency": "NGN"
    },
    "narration": "Funding",
    "postedAt": "2026-08-21T10:14:22.101",
    "destination": {
      "accountNumber": "0123456789"
    }
  }
}

transaction.posted High volume Any ledger posting. ⚠ High volume, and restricted. Fires for every posting, which means twice per transfer, once per leg. Subscribe only if you are reconciling the ledger itself; for order fulfilment the specific completion events are cheaper and easier to reason about.

Subject: transaction · apiVersion 1.0

High volume and restricted. Fires for every ledger posting: twice per transfer, once per leg. The counterparties carry holder references rather than account numbers, because this is the ledger view.

Restricted: subscribing to this needs a permission outside the ordinary grant.

{
  "id": "8d651274-d378-4979-97ca-0b3b6d9705d2",
  "type": "transaction.posted",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "financial_transaction",
    "reference": "3f1c6a2e-8b47-4d19-9a0e-15d2c7b8e441"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "3f1c6a2e-8b47-4d19-9a0e-15d2c7b8e441",
    "type": "PEER_TRANSFER",
    "status": "COMPLETED",
    "amount": {
      "amount": "5000.00",
      "currency": "NGN"
    },
    "fee": {
      "amount": "26.88",
      "currency": "NGN"
    },
    "narration": "October rent",
    "postedAt": "2026-08-21T10:14:22.101",
    "source": {
      "holderReference": "1b7f0c94-3e28-4a15-9d60-2f8c41b7e093"
    },
    "destination": {
      "holderReference": "b7e2d1c0-3f4a-4b5c-9d8e-7f6a5b4c3d2e"
    }
  }
}

Bills · 3

bill_payment.settled A bill payment settled with the biller and produced a receipt or token.

Subject: bill_payment · apiVersion 1.0

{
  "id": "8845e9e0-7898-408d-9a71-2abedc632662",
  "type": "bill_payment.settled",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "bill_payment",
    "reference": "6b1d9f04-3a72-4c58-9e16-8d0f27b4a5c3"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "6b1d9f04-3a72-4c58-9e16-8d0f27b4a5c3",
    "status": "SUCCESSFUL",
    "amount": {
      "amount": "2000.00",
      "currency": "NGN"
    },
    "financialTransactionReference": "a6c30b91-4e7f-42d5-9b08-3f1e6a2c8d74",
    "beneficiaryReference": "5c3a08f1-7b62-4e94-a10d-8f2b6c05d739"
  }
}

bill_payment.failed Failure A bill payment did not go through and the debit has been reversed. No value was ever delivered by the biller.

Subject: bill_payment · apiVersion 1.0

The payment never went through. Nothing was delivered and nothing needs clawing back.

{
  "id": "4e7b4bef-ad0f-457b-9cc5-d90eec7b2486",
  "type": "bill_payment.failed",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "bill_payment",
    "reference": "6b1d9f04-3a72-4c58-9e16-8d0f27b4a5c3"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "6b1d9f04-3a72-4c58-9e16-8d0f27b4a5c3",
    "status": "FAILED",
    "amount": {
      "amount": "2000.00",
      "currency": "NGN"
    },
    "financialTransactionReference": "a6c30b91-4e7f-42d5-9b08-3f1e6a2c8d74",
    "beneficiaryReference": "5c3a08f1-7b62-4e94-a10d-8f2b6c05d739"
  }
}

bill_payment.reversed Failure A bill payment that had already succeeded was unwound after a requery. This is not the same as bill_payment.failed: the biller did deliver, so anything you released against the original settlement has to be clawed back.

Subject: bill_payment · apiVersion 1.0

Read this one twice. It succeeded, you were told so, and a later requery unwound it. The biller delivered, so whatever value you released against the original settlement now has to be clawed back. Treating this as an ordinary failure is how airtime gets given away against a payment that no longer exists.

{
  "id": "9d7d93f2-8d6b-41f0-98be-75e5714e912b",
  "type": "bill_payment.reversed",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "bill_payment",
    "reference": "6b1d9f04-3a72-4c58-9e16-8d0f27b4a5c3"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "6b1d9f04-3a72-4c58-9e16-8d0f27b4a5c3",
    "status": "REVERSED",
    "amount": {
      "amount": "2000.00",
      "currency": "NGN"
    },
    "financialTransactionReference": "a6c30b91-4e7f-42d5-9b08-3f1e6a2c8d74",
    "beneficiaryReference": "5c3a08f1-7b62-4e94-a10d-8f2b6c05d739"
  }
}

Collections · 2

virtual_account.credited Money arrived in a virtual account. The event most integrators adopt webhooks for, because it is the one that cannot be polled for cheaply.

Subject: virtual_account · apiVersion 1.0

The event that cannot be polled for cheaply. settledAmount is what reached the account after the collection fee. Reconcile against that, not amount. The payer's account number is not on this event.

{
  "id": "2d8ddf88-de10-44ed-9df6-f5d4057944de",
  "type": "virtual_account.credited",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "virtual_account_credit",
    "reference": "8d51f2b0-6c39-4a7e-b284-19c07f3ea5d6"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "creditReference": "8d51f2b0-6c39-4a7e-b284-19c07f3ea5d6",
    "virtualAccountNumber": "7012345678",
    "amount": {
      "amount": "250000.00",
      "currency": "NGN"
    },
    "settledAmount": {
      "amount": "249750.00",
      "currency": "NGN"
    },
    "payerName": "OLUWATOBI OKONKWO",
    "payerBankCode": "058",
    "narration": "INV-2026-0918",
    "creditedAt": "2026-08-21T10:31:06.980"
  }
}

virtual_account.credit_reversed A virtual-account credit was reversed. Handle this if you released goods on the original credit.

Subject: virtual_account · apiVersion 1.0

Money you were told about has been taken back. The subject reference is the reversal, not the original credit; match on virtualAccountNumber, amount and payerName to find what it undoes.

{
  "id": "556d3385-8e38-43aa-95bf-e9ed92cb0edd",
  "type": "virtual_account.credit_reversed",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "virtual_account_credit",
    "reference": "c2e94a70-1b38-4f65-8d09-5a7e3c1b6f42"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reversalReference": "c2e94a70-1b38-4f65-8d09-5a7e3c1b6f42",
    "virtualAccountNumber": "7012345678",
    "amount": {
      "amount": "250000.00",
      "currency": "NGN"
    },
    "settledAmount": {
      "amount": "249750.00",
      "currency": "NGN"
    },
    "payerName": "OLUWATOBI OKONKWO",
    "narration": "INV-2026-0918"
  }
}

Offline payments · 2

offline_settlement.completed An offline peer-to-peer payment settled once the device came back online.

Subject: offline_settlement · apiVersion 1.0

An offline payment reached the ledger once a device came back online. One failed item in a batch never voids the rest, and a replayed batch never moves money twice.

{
  "id": "2026e94a-84f5-45ef-95c0-30202a7ddf41",
  "type": "offline_settlement.completed",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "settlement",
    "reference": "4f8a2c61-7d39-4b05-a8e2-1c6b9d3f0e57"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "4f8a2c61-7d39-4b05-a8e2-1c6b9d3f0e57",
    "status": "COMPLETED",
    "amount": {
      "amount": "48500.00",
      "currency": "NGN"
    },
    "narration": "Terminal batch 2026-08-21",
    "senderReference": "b7e2d1c0-3f4a-4b5c-9d8e-7f6a5b4c3d2e",
    "receiverReference": "1b7f0c94-3e28-4a15-9d60-2f8c41b7e093"
  }
}

offline_topup.completed An offline wallet top-up completed.

Subject: offline_topup · apiVersion 1.0

Value was loaded onto a device wallet, which is what lets the terminal sell with no network.

{
  "id": "9a2b11b3-840e-4d72-9ae7-6547e2a783ab",
  "type": "offline_topup.completed",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "topup",
    "reference": "9c05e7b3-2f41-4a86-b7d0-6e3a1c85f294"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "9c05e7b3-2f41-4a86-b7d0-6e3a1c85f294",
    "status": "COMPLETED",
    "amount": {
      "amount": "50000.00",
      "currency": "NGN"
    },
    "settledAmount": {
      "amount": "49875.00",
      "currency": "NGN"
    },
    "financialTransactionReference": "a6c30b91-4e7f-42d5-9b08-3f1e6a2c8d74",
    "completedAt": "2026-08-21T09:02:44.318"
  }
}

Wallets and devices · 3

wallet.created A wallet was provisioned for a holder.

Subject: wallet · apiVersion 1.0

{
  "id": "54ffeb8f-4fa9-4148-9c7e-cd0235334e02",
  "type": "wallet.created",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "wallet",
    "reference": "2a7f6c81-5b09-4e34-9d62-8c1f0a5e7b43"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "walletReference": "2a7f6c81-5b09-4e34-9d62-8c1f0a5e7b43",
    "accountReference": "a3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "accountNumber": "0123456789",
    "walletType": "PRIMARY",
    "currency": "NGN",
    "holderReference": "b7e2d1c0-3f4a-4b5c-9d8e-7f6a5b4c3d2e",
    "createdAt": "2026-08-21T08:15:03.221"
  }
}

device.linked A holder linked a device.

Subject: device · apiVersion 1.0

Only one device is linked at a time, so a device.linked you did not expect means a customer moved handset.

{
  "id": "be475a50-5069-4972-91e0-b0059d6eb346",
  "type": "device.linked",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "device",
    "reference": "5e3b9d02-4c71-4a85-b6f9-0d2c7e1a8f36"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "deviceReference": "5e3b9d02-4c71-4a85-b6f9-0d2c7e1a8f36",
    "holderReference": "b7e2d1c0-3f4a-4b5c-9d8e-7f6a5b4c3d2e",
    "deviceType": "ANDROID",
    "status": "ACTIVE",
    "occurredAt": "2026-08-21T08:20:11.907"
  }
}

device.unlinked A holder's device was unlinked.

Subject: device · apiVersion 1.0

{
  "id": "3791079e-3cd0-466c-92fa-b82835b70ddd",
  "type": "device.unlinked",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "device",
    "reference": "5e3b9d02-4c71-4a85-b6f9-0d2c7e1a8f36"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "deviceReference": "5e3b9d02-4c71-4a85-b6f9-0d2c7e1a8f36",
    "holderReference": "b7e2d1c0-3f4a-4b5c-9d8e-7f6a5b4c3d2e",
    "deviceType": "ANDROID",
    "status": "UNLINKED",
    "occurredAt": "2026-08-21T08:20:11.907"
  }
}

Compliance · 1

document.verified An identity document finished verification. Carries the outcome and the document reference, never the identifier number, and never a document URL.

Subject: document · apiVersion 1.0

Covers both identification documents and business documents; subjectType says which. It says nothing about why a check passed; the documents and risk signals behind a KYC decision are not an integrator's to see.

{
  "id": "5f9fb064-fb91-46a4-93c3-9714a56507f8",
  "type": "document.verified",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "document",
    "reference": "8b40a1f7-6d29-4c53-9e08-2f7b5a3c1d69"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "subjectType": "IDENTIFICATION",
    "subjectReference": "8b40a1f7-6d29-4c53-9e08-2f7b5a3c1d69",
    "holderReference": "b7e2d1c0-3f4a-4b5c-9d8e-7f6a5b4c3d2e",
    "documentType": "PASSPORT",
    "countryCode": "NG",
    "levelOfAssurance": "3"
  }
}

Beneficiaries · 5

beneficiary.added A holder saved a counterparty they can pay again.

Subject: beneficiary · apiVersion 1.0

maskedIdentifier is the sole identifier on this payload. The counterparty's real account number never leaves Bridge on this path. coolingOffEndsAt is when the new payee stops being treated as new.

{
  "id": "4021f74c-f64d-456e-9162-367fdefe9cb7",
  "type": "beneficiary.added",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "beneficiary",
    "reference": "5c3a08f1-7b62-4e94-a10d-8f2b6c05d739"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "5c3a08f1-7b62-4e94-a10d-8f2b6c05d739",
    "kind": "EXTERNAL_ACCOUNT",
    "status": "ACTIVE",
    "trustLevel": "NEW",
    "alias": "Mum \u2014 school fees",
    "resolvedName": "JANE ADEYEMI",
    "maskedIdentifier": "004*****921",
    "providerName": "GTBank",
    "currency": "NGN",
    "coolingOffEndsAt": "2026-08-21T16:41:52.004",
    "occurredAt": "2026-08-20T16:41:52.004"
  }
}

beneficiary.archived A saved payee was removed.

Subject: beneficiary · apiVersion 1.0

{
  "id": "f58313fa-c10f-46bd-9304-0ade6c7779e4",
  "type": "beneficiary.archived",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "beneficiary",
    "reference": "5c3a08f1-7b62-4e94-a10d-8f2b6c05d739"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "5c3a08f1-7b62-4e94-a10d-8f2b6c05d739",
    "kind": "EXTERNAL_ACCOUNT",
    "status": "ARCHIVED",
    "trustLevel": "TRUSTED",
    "alias": "Mum \u2014 school fees",
    "resolvedName": "JANE ADEYEMI",
    "maskedIdentifier": "004*****921",
    "providerName": "GTBank",
    "currency": "NGN",
    "occurredAt": "2026-08-20T16:41:52.004"
  }
}

beneficiary.trusted A saved payee was marked trusted, which reduces friction on later payments.

Subject: beneficiary · apiVersion 1.0

{
  "id": "c61a2910-567f-484d-96fa-1e07f9bb4f09",
  "type": "beneficiary.trusted",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "beneficiary",
    "reference": "5c3a08f1-7b62-4e94-a10d-8f2b6c05d739"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "5c3a08f1-7b62-4e94-a10d-8f2b6c05d739",
    "kind": "EXTERNAL_ACCOUNT",
    "status": "ACTIVE",
    "trustLevel": "TRUSTED",
    "alias": "Mum \u2014 school fees",
    "resolvedName": "JANE ADEYEMI",
    "maskedIdentifier": "004*****921",
    "providerName": "GTBank",
    "currency": "NGN",
    "occurredAt": "2026-08-20T16:41:52.004"
  }
}

beneficiary.stale The name behind a saved destination changed, so it is no longer payable until it is re-verified.

Subject: beneficiary · apiVersion 1.0

The account name behind this payee has changed since it was saved. Re-confirm the name with the customer before the next payment.

{
  "id": "670f70d2-eb37-480e-9a8f-40491c68beb9",
  "type": "beneficiary.stale",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "beneficiary",
    "reference": "5c3a08f1-7b62-4e94-a10d-8f2b6c05d739"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "5c3a08f1-7b62-4e94-a10d-8f2b6c05d739",
    "kind": "EXTERNAL_ACCOUNT",
    "status": "ACTIVE",
    "trustLevel": "STALE",
    "alias": "Mum \u2014 school fees",
    "resolvedName": "JANE ADEYEMI",
    "maskedIdentifier": "004*****921",
    "providerName": "GTBank",
    "currency": "NGN",
    "occurredAt": "2026-08-20T16:41:52.004"
  }
}

beneficiary.restricted A saved payee was frozen, by the holder or following a compliance review.

Subject: beneficiary · apiVersion 1.0

restrictedBy is the field that matters here and it appears on no other beneficiary event. "You froze this payee" and "this payee was frozen following a review" need different sentences in front of a customer.

{
  "id": "7a7f6c74-94cb-498f-9339-6dde8cfe45a6",
  "type": "beneficiary.restricted",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "beneficiary",
    "reference": "5c3a08f1-7b62-4e94-a10d-8f2b6c05d739"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "5c3a08f1-7b62-4e94-a10d-8f2b6c05d739",
    "kind": "EXTERNAL_ACCOUNT",
    "status": "RESTRICTED",
    "trustLevel": "TRUSTED",
    "alias": "Mum \u2014 school fees",
    "resolvedName": "JANE ADEYEMI",
    "maskedIdentifier": "004*****921",
    "providerName": "GTBank",
    "currency": "NGN",
    "restrictedBy": "COMPLIANCE",
    "occurredAt": "2026-08-20T16:41:52.004"
  }
}

Vouchers · 6

voucher.created A voucher was issued.

Subject: voucher · apiVersion 1.0

{
  "id": "e4d1514c-4ac6-481f-9b2c-7110b4332767",
  "type": "voucher.created",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "voucher",
    "reference": "0a6d3f92-8b14-4e70-9c25-7f1e0b4a3d68"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "0a6d3f92-8b14-4e70-9c25-7f1e0b4a3d68",
    "status": "ACTIVE",
    "voucherType": "ONLINE",
    "faceValue": {
      "amount": "10000.00",
      "currency": "NGN"
    },
    "remainingAmount": {
      "amount": "10000.00",
      "currency": "NGN"
    },
    "redemptionsCount": 0,
    "maxRedemptions": 1,
    "issuerReference": "b7e2d1c0-3f4a-4b5c-9d8e-7f6a5b4c3d2e",
    "expiresAt": "2026-09-21T23:59:59.000",
    "occurredAt": "2026-08-21T11:12:38.550"
  }
}

voucher.redeemed A voucher was redeemed.

Subject: voucher · apiVersion 1.0

The one voucher event that concerns a second party. remainingAmount is what is left on a partially redeemable voucher. Check it rather than assuming a redemption exhausts the face value.

{
  "id": "7484c958-4996-4a52-95b7-54a58b3c2d72",
  "type": "voucher.redeemed",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "voucher",
    "reference": "0a6d3f92-8b14-4e70-9c25-7f1e0b4a3d68"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "0a6d3f92-8b14-4e70-9c25-7f1e0b4a3d68",
    "status": "REDEEMED",
    "voucherType": "ONLINE",
    "faceValue": {
      "amount": "10000.00",
      "currency": "NGN"
    },
    "remainingAmount": {
      "amount": "0.00",
      "currency": "NGN"
    },
    "redemptionsCount": 1,
    "maxRedemptions": 1,
    "issuerReference": "b7e2d1c0-3f4a-4b5c-9d8e-7f6a5b4c3d2e",
    "redeemerReference": "1b7f0c94-3e28-4a15-9d60-2f8c41b7e093",
    "expiresAt": "2026-09-21T23:59:59.000",
    "occurredAt": "2026-08-21T11:12:38.550"
  }
}

voucher.blocked A voucher was blocked.

Subject: voucher · apiVersion 1.0

{
  "id": "2c63d55b-d0c9-4ebd-9ede-f42c3a03912a",
  "type": "voucher.blocked",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "voucher",
    "reference": "0a6d3f92-8b14-4e70-9c25-7f1e0b4a3d68"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "0a6d3f92-8b14-4e70-9c25-7f1e0b4a3d68",
    "status": "BLOCKED",
    "voucherType": "ONLINE",
    "faceValue": {
      "amount": "10000.00",
      "currency": "NGN"
    },
    "remainingAmount": {
      "amount": "10000.00",
      "currency": "NGN"
    },
    "redemptionsCount": 0,
    "maxRedemptions": 1,
    "issuerReference": "b7e2d1c0-3f4a-4b5c-9d8e-7f6a5b4c3d2e",
    "expiresAt": "2026-09-21T23:59:59.000",
    "statusReason": "Reported lost by the issuer",
    "occurredAt": "2026-08-21T11:12:38.550"
  }
}

voucher.unblocked A blocked voucher was released.

Subject: voucher · apiVersion 1.0

{
  "id": "dcfcf159-bfa6-44ea-961f-238f8a2738c7",
  "type": "voucher.unblocked",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "voucher",
    "reference": "0a6d3f92-8b14-4e70-9c25-7f1e0b4a3d68"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "0a6d3f92-8b14-4e70-9c25-7f1e0b4a3d68",
    "status": "ACTIVE",
    "voucherType": "ONLINE",
    "faceValue": {
      "amount": "10000.00",
      "currency": "NGN"
    },
    "remainingAmount": {
      "amount": "10000.00",
      "currency": "NGN"
    },
    "redemptionsCount": 0,
    "maxRedemptions": 1,
    "issuerReference": "b7e2d1c0-3f4a-4b5c-9d8e-7f6a5b4c3d2e",
    "expiresAt": "2026-09-21T23:59:59.000",
    "occurredAt": "2026-08-21T11:12:38.550"
  }
}

voucher.closed A voucher was closed.

Subject: voucher · apiVersion 1.0

{
  "id": "84023132-06de-420c-92fc-d682dc1ebb87",
  "type": "voucher.closed",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "voucher",
    "reference": "0a6d3f92-8b14-4e70-9c25-7f1e0b4a3d68"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "0a6d3f92-8b14-4e70-9c25-7f1e0b4a3d68",
    "status": "CLOSED",
    "voucherType": "ONLINE",
    "faceValue": {
      "amount": "10000.00",
      "currency": "NGN"
    },
    "remainingAmount": {
      "amount": "10000.00",
      "currency": "NGN"
    },
    "redemptionsCount": 0,
    "maxRedemptions": 1,
    "issuerReference": "b7e2d1c0-3f4a-4b5c-9d8e-7f6a5b4c3d2e",
    "expiresAt": "2026-09-21T23:59:59.000",
    "statusReason": "Closed by the issuer; balance returned",
    "occurredAt": "2026-08-21T11:12:38.550"
  }
}

voucher.expired A voucher passed its expiry.

Subject: voucher · apiVersion 1.0

Fires from a scheduler rather than from anyone's request, so it can arrive at any hour.

{
  "id": "a4e6e84f-a7ae-434c-9696-4603acef5b76",
  "type": "voucher.expired",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "voucher",
    "reference": "0a6d3f92-8b14-4e70-9c25-7f1e0b4a3d68"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "0a6d3f92-8b14-4e70-9c25-7f1e0b4a3d68",
    "status": "EXPIRED",
    "voucherType": "ONLINE",
    "faceValue": {
      "amount": "10000.00",
      "currency": "NGN"
    },
    "remainingAmount": {
      "amount": "10000.00",
      "currency": "NGN"
    },
    "redemptionsCount": 0,
    "maxRedemptions": 1,
    "issuerReference": "b7e2d1c0-3f4a-4b5c-9d8e-7f6a5b4c3d2e",
    "expiresAt": "2026-09-21T23:59:59.000",
    "occurredAt": "2026-08-21T11:12:38.550"
  }
}

Escrow · 10

escrow.created An escrow agreement was created. No money is held yet: escrow.funded is the event that says it is.

Subject: escrow_agreement · apiVersion 1.0

No money is held yet: escrow.funded is the event that says it is.

{
  "id": "958430dd-4280-46b5-97ea-555f9415166a",
  "type": "escrow.created",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "escrow_agreement",
    "reference": "e1d2c3b4-a5f6-4789-9abc-def012345678"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "e1d2c3b4-a5f6-4789-9abc-def012345678",
    "status": "CREATED",
    "agreementAmount": {
      "amount": "450000.00",
      "currency": "NGN"
    },
    "payerReference": "b7e2d1c0-3f4a-4b5c-9d8e-7f6a5b4c3d2e",
    "payeeReference": "c8f3e2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f"
  }
}

escrow.funded The payer funded the agreement. The money is now held by Bridge and neither party can move it except through the gates.

Subject: escrow_agreement · apiVersion 1.0

The money is now held by Bridge and neither party can move it except through the gates.

{
  "id": "a68a1105-ea9b-4edd-9c12-ef5f6d1f604b",
  "type": "escrow.funded",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "escrow_agreement",
    "reference": "e1d2c3b4-a5f6-4789-9abc-def012345678"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "e1d2c3b4-a5f6-4789-9abc-def012345678",
    "status": "FUNDED",
    "agreementAmount": {
      "amount": "450000.00",
      "currency": "NGN"
    },
    "payerReference": "b7e2d1c0-3f4a-4b5c-9d8e-7f6a5b4c3d2e",
    "payeeReference": "c8f3e2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f"
  }
}

escrow.amended The terms of an agreement changed: gates, amounts or expiry.

Subject: escrow_agreement · apiVersion 1.0

{
  "id": "0f85afb5-3115-4dea-91f9-a51eee40f1ff",
  "type": "escrow.amended",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "escrow_agreement",
    "reference": "e1d2c3b4-a5f6-4789-9abc-def012345678"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "e1d2c3b4-a5f6-4789-9abc-def012345678",
    "status": "FUNDED",
    "agreementAmount": {
      "amount": "450000.00",
      "currency": "NGN"
    },
    "payerReference": "b7e2d1c0-3f4a-4b5c-9d8e-7f6a5b4c3d2e",
    "payeeReference": "c8f3e2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
    "reason": "Delivery window extended by 14 days"
  }
}

escrow.cancelled Failure An agreement was cancelled before completing. Any held funds return to the payer.

Subject: escrow_agreement · apiVersion 1.0

{
  "id": "9280c578-2fbf-4a43-9ec3-b73d4e17654f",
  "type": "escrow.cancelled",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "escrow_agreement",
    "reference": "e1d2c3b4-a5f6-4789-9abc-def012345678"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "e1d2c3b4-a5f6-4789-9abc-def012345678",
    "status": "CANCELLED",
    "agreementAmount": {
      "amount": "450000.00",
      "currency": "NGN"
    },
    "payerReference": "b7e2d1c0-3f4a-4b5c-9d8e-7f6a5b4c3d2e",
    "payeeReference": "c8f3e2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
    "reason": "Both parties withdrew"
  }
}

escrow.gate_passed A gate was approved. Its share of the funds is now releasable.

Subject: escrow_agreement · apiVersion 1.0

Gate-scoped: amount is this gate's share, agreementAmount is the whole agreement.

{
  "id": "73edfeb1-ec8f-4de4-908c-daaa679281d6",
  "type": "escrow.gate_passed",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "escrow_agreement",
    "reference": "e1d2c3b4-a5f6-4789-9abc-def012345678"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "e1d2c3b4-a5f6-4789-9abc-def012345678",
    "gateReference": "f2e3d4c5-b6a7-489a-bcde-f01234567890",
    "status": "FUNDED",
    "gateStatus": "PASSED",
    "amount": {
      "amount": "150000.00",
      "currency": "NGN"
    },
    "agreementAmount": {
      "amount": "450000.00",
      "currency": "NGN"
    },
    "payerReference": "b7e2d1c0-3f4a-4b5c-9d8e-7f6a5b4c3d2e",
    "payeeReference": "c8f3e2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f"
  }
}

escrow.gate_rejected Failure A gate was rejected. Its share will not be released on these terms.

Subject: escrow_agreement · apiVersion 1.0

{
  "id": "79727ee3-4f9d-4cc9-9ee2-dde7c6ace2f2",
  "type": "escrow.gate_rejected",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "escrow_agreement",
    "reference": "e1d2c3b4-a5f6-4789-9abc-def012345678"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "e1d2c3b4-a5f6-4789-9abc-def012345678",
    "gateReference": "f2e3d4c5-b6a7-489a-bcde-f01234567890",
    "status": "FUNDED",
    "gateStatus": "REJECTED",
    "amount": {
      "amount": "150000.00",
      "currency": "NGN"
    },
    "agreementAmount": {
      "amount": "450000.00",
      "currency": "NGN"
    },
    "payerReference": "b7e2d1c0-3f4a-4b5c-9d8e-7f6a5b4c3d2e",
    "payeeReference": "c8f3e2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
    "reason": "Goods did not match the description"
  }
}

escrow.disputed Failure A gate was disputed and is now with your back office. Neither party can move its funds until the case resolves. Expect escrow.released or escrow.refunded to follow.

Subject: escrow_agreement · apiVersion 1.0

The case is now with your back office. Neither party can move the funds until it resolves. Expect escrow.released or escrow.refunded to follow.

{
  "id": "35251733-a8b0-48bb-9aa4-8a07b461884e",
  "type": "escrow.disputed",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "escrow_agreement",
    "reference": "e1d2c3b4-a5f6-4789-9abc-def012345678"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "e1d2c3b4-a5f6-4789-9abc-def012345678",
    "gateReference": "f2e3d4c5-b6a7-489a-bcde-f01234567890",
    "status": "DISPUTED",
    "gateStatus": "DISPUTED",
    "amount": {
      "amount": "150000.00",
      "currency": "NGN"
    },
    "agreementAmount": {
      "amount": "450000.00",
      "currency": "NGN"
    },
    "payerReference": "b7e2d1c0-3f4a-4b5c-9d8e-7f6a5b4c3d2e",
    "payeeReference": "c8f3e2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
    "reason": "Goods did not match the description"
  }
}

escrow.released Funds were released to the payee. This is terminal for the gate.

Subject: escrow_agreement · apiVersion 1.0

Terminal for the gate. The payee has the money.

{
  "id": "37759f84-b9df-4d64-988d-5c1344f8313b",
  "type": "escrow.released",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "escrow_agreement",
    "reference": "e1d2c3b4-a5f6-4789-9abc-def012345678"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "e1d2c3b4-a5f6-4789-9abc-def012345678",
    "gateReference": "f2e3d4c5-b6a7-489a-bcde-f01234567890",
    "status": "RELEASED",
    "gateStatus": "RELEASED",
    "amount": {
      "amount": "150000.00",
      "currency": "NGN"
    },
    "agreementAmount": {
      "amount": "450000.00",
      "currency": "NGN"
    },
    "payerReference": "b7e2d1c0-3f4a-4b5c-9d8e-7f6a5b4c3d2e",
    "payeeReference": "c8f3e2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f"
  }
}

escrow.refunded Failure Funds were returned to the payer. This is terminal for the gate.

Subject: escrow_agreement · apiVersion 1.0

Terminal for the gate. The payer has the money back.

{
  "id": "2d7f1fd1-7169-4b65-9e3c-c59c4dd35534",
  "type": "escrow.refunded",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "escrow_agreement",
    "reference": "e1d2c3b4-a5f6-4789-9abc-def012345678"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "e1d2c3b4-a5f6-4789-9abc-def012345678",
    "gateReference": "f2e3d4c5-b6a7-489a-bcde-f01234567890",
    "status": "REFUNDED",
    "gateStatus": "REFUNDED",
    "amount": {
      "amount": "150000.00",
      "currency": "NGN"
    },
    "agreementAmount": {
      "amount": "450000.00",
      "currency": "NGN"
    },
    "payerReference": "b7e2d1c0-3f4a-4b5c-9d8e-7f6a5b4c3d2e",
    "payeeReference": "c8f3e2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
    "reason": "Dispute resolved in the payer's favour"
  }
}

escrow.release_failed Failure A release was attempted and the money did not move. Subscribe to this alongside escrow.released: without it a failed release is indistinguishable from one still in progress, and the funds are still held.

Subject: escrow_agreement · apiVersion 1.0

The funds are still held. Subscribe to this alongside escrow.released: without it, a failed release is indistinguishable from one still in progress.

{
  "id": "f569884e-8b00-4a69-9aa1-ac7a813d34fd",
  "type": "escrow.release_failed",
  "apiVersion": "1.0",
  "createdAt": "2026-08-21T10:14:22.183Z",
  "tenant": "acme",
  "subject": {
    "type": "escrow_agreement",
    "reference": "e1d2c3b4-a5f6-4789-9abc-def012345678"
  },
  "owner": {
    "type": "ORGANIZATION",
    "reference": "9b2e17a4-5c33-4f80-8de1-6a4f92c0b7d5"
  },
  "data": {
    "reference": "e1d2c3b4-a5f6-4789-9abc-def012345678",
    "gateReference": "f2e3d4c5-b6a7-489a-bcde-f01234567890",
    "status": "FUNDED",
    "gateStatus": "RELEASE_FAILED",
    "amount": {
      "amount": "150000.00",
      "currency": "NGN"
    },
    "agreementAmount": {
      "amount": "450000.00",
      "currency": "NGN"
    },
    "payerReference": "b7e2d1c0-3f4a-4b5c-9d8e-7f6a5b4c3d2e",
    "payeeReference": "c8f3e2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
    "reason": "Payee account is dormant at the receiving institution"
  }
}

Communities · 10

community.contribution_completed A member's contribution posted to a community's pot. A distinct transaction type from an ordinary transfer, and one that cannot be corrected afterwards.