Event Types

All webhook payloads follow the same envelope:

{
  "event": "<event-type>",
  "data": { ... }
}

The data object shape depends on the event type. Every field documented below is present in the data object.

accounts.created

Fired when a new account is created for an entity.

object

The newly created account.

Show account fields

string

Unique account identifier.

string

The ID of the entity that owns this account.

string

Account type. e.g. checking.

string

ISO 4217 currency code.

string

Human-readable account label.

object

Current account balance.

Show balance fields

number

Available balance in the smallest currency unit.

number

Current balance including pending transactions.

object

Key-value metadata attached to the account.

number

Creation timestamp in Unix milliseconds.

number

Last update timestamp in Unix milliseconds.

object

Summary of how this account creation affects the entity.

Show entity_impact fields

string

The entity ID.

number

Total number of accounts now held by this entity.

array

List of account types held by the entity.

boolean

Whether a default account has been set for this entity.

{
  "event": "accounts.created",
  "data": {
    "account": {
      "id": "01K6ZX7360026KPNA2SQ6NPNZY",
      "entity_id": "01K3P1JTKG133K4SKFH36F3FN6",
      "type": "checking",
      "currency": "USD",
      "display_name": "Primary USD Account",
      "balance": {
        "available": 0,
        "current": 0
      },
      "meta": {
        "external_ref": "ext_acc_12345",
        "purpose": "operational"
      },
      "created": 1759859936448,
      "updated": 1759859936448
    },
    "entity_impact": {
      "entity_id": "01K3P1JTKG133K4SKFH36F3FN6",
      "total_accounts": 1,
      "account_type": ["checking"],
      "default_account_set": true
    }
  }
}

account_details.created

Fired when bank account numbers or wallet details are generated for an account.

object

The newly created account details record.

Show account_details fields

string

Unique identifier for the account details record.

string

The ID of the entity that owns this account.

string

The ID of the account these details belong to.

string

The assigned account number.

string

The routing number (where applicable).

object

The issuing bank or institution.

Show issuer fields

string

Institution code.

string

Institution name.

string

Account details status. e.g. active.

number

Creation timestamp in Unix milliseconds.

number

Last update timestamp in Unix milliseconds.

{
  "event": "account_details.created",
  "data": {
    "account_details": {
      "id": "01K6ZX8CWXXGFR9MJGQVCYTQSM",
      "entity_id": "01K3P1JTKG133K4SKFH36F3FN6",
      "account_id": "01K6ZX7360026KPNA2SQ6NPNZY",
      "account_number": "000987654321",
      "routing_number": "021000021",
      "issuer": {
        "code": "CHASE",
        "name": "JPMorgan Chase"
      },
      "status": "active",
      "created": 1759859979165,
      "updated": 1759859979165
    }
  }
}

account_details.updated

Fired when account details are modified — for example, a status change or metadata update.

string

Unique identifier for the account details record.

string

The ID of the entity that owns this account.

string

The ID of the account these details belong to.

string

The account number.

object

The issuing bank or institution.

Show issuer fields

string

Institution code.

string

Institution name.

string

Updated status of the account details record.

number

Original creation timestamp in Unix milliseconds.

number

Timestamp of this update in Unix milliseconds.

{
  "event": "account_details.updated",
  "data": {
    "id": "01K748A4WV5Q9NWG4TT2V15V5X",
    "entity_id": "01K3HJAK85YJP13WJ41P3CWAVM",
    "account_id": "01K7489GQWRD48TV4XYP27ZVSC",
    "account_number": "12345678",
    "issuer": {
      "code": "HSBC",
      "name": "HSBC UK"
    },
    "status": "active",
    "created": 1760005788571,
    "updated": 1760005799179
  }
}

inflows.completed

Fired when a payment is received into an account.

string

Unique identifier for the inflow transaction.

number

Amount received in the smallest currency unit.

string

ISO 4217 currency code.

string

Unique reference for the transaction. Use this to deduplicate events.

string

Identifier of the sending counterparty.

string

The ID of the account that received the funds.

string

The ID of the entity that owns the receiving account.

string

Transaction status. successful for completed inflows.

string

Human-readable status description.

string

Payment reference or description from the sender.

string

inflow.

number

Fee applied to this transaction in the smallest currency unit.

object

Key-value metadata.

number

Creation timestamp in Unix milliseconds.

number

Last update timestamp in Unix milliseconds.

{
  "event": "inflows.completed",
  "data": {
    "id": "01K6ZXCNMVA04GM3WQRCKQNCMB",
    "amount": 10000,
    "currency": "USD",
    "unique_reference": "01K6ZX7360026KPNA2SQ6NPNZY-1759504425996",
    "counterparty_id": "acct-01K6ZX7360026KPNA2SQ6NPNZY",
    "account_id": "01K6ZX7360026KPNA2SQ6NPNZY",
    "entity_id": "01K3P1JTKG133K4SKFH36F3FN6",
    "status": "successful",
    "status_reason": "Successful.",
    "narration": "Invoice payment received",
    "type": "inflow",
    "applicable_fee": 0,
    "meta": {},
    "created": 1759860119195,
    "updated": 1759860119195
  }
}

outflows.created

Fired when a transfer request is received and queued for processing.

string

Unique identifier for the outflow transaction.

number

Transfer amount in the smallest currency unit.

string

ISO 4217 currency code.

string

The idempotency key passed when initiating the transfer.

string

The ID of the recipient counterparty.

string

The ID of the source account being debited.

string

The ID of the entity initiating the transfer.

string

pending — transfer is queued and awaiting processing.

string

awaiting_processing.

string

Transfer description.

string

outflow.

number

Fee applied to this transfer in the smallest currency unit.

object

Key-value metadata.

number

Creation timestamp in Unix milliseconds.

number

Last update timestamp in Unix milliseconds.

{
  "event": "outflows.created",
  "data": {
    "id": "01K7H0QM421E9CB5M24W5AK3Q3",
    "amount": 5000,
    "currency": "GBP",
    "unique_reference": "PAY-2025-001",
    "counterparty_id": "01K76NZW807BYPWACT2JX6B9J8",
    "account_id": "01K747KD7QW8KQS2GRD8MQBT55",
    "entity_id": "01K3HJAK85YJP13WJ41P3CWAVM",
    "status": "pending",
    "status_reason": "awaiting_processing",
    "narration": "Vendor payment",
    "type": "outflow",
    "applicable_fee": 75,
    "meta": {},
    "created": 1760434049154,
    "updated": 1760434050159
  }
}

outflows.completed

Fired when a transfer is delivered successfully to the recipient. The payload shape is identical to outflows.created. The status field will be successful and status_reason will be processing_complete.

{
  "event": "outflows.completed",
  "data": {
    "id": "01K7H0QM421E9CB5M24W5AK3Q3",
    "amount": 5000,
    "currency": "GBP",
    "unique_reference": "PAY-2025-001",
    "counterparty_id": "01K76NZW807BYPWACT2JX6B9J8",
    "account_id": "01K747KD7QW8KQS2GRD8MQBT55",
    "entity_id": "01K3HJAK85YJP13WJ41P3CWAVM",
    "status": "successful",
    "status_reason": "processing_complete",
    "narration": "Vendor payment",
    "type": "outflow",
    "applicable_fee": 75,
    "meta": {},
    "created": 1760434049154,
    "updated": 1760434050159
  }
}

outflows.failed

Fired when a transfer cannot be completed. Check status_reason for the failure cause. The payload shape is identical to outflows.created. The status field will be failed.

Common status_reason values include insufficient_funds, invalid_account_details, and compliance_hold. Use status_reason to determine whether to retry the transfer or surface an error to your user.

{
  "event": "outflows.failed",
  "data": {
    "id": "01K7H0QM421E9CB5M24W5AK3Q3",
    "amount": 10000,
    "currency": "USD",
    "unique_reference": "PAY-2025-002",
    "counterparty_id": "01K76NZW807BYPWACT2JX6B9J8",
    "account_id": "01K747KD7QW8KQS2GRD8MQBT55",
    "entity_id": "01K3HJAK85YJP13WJ41P3CWAVM",
    "status": "failed",
    "status_reason": "insufficient_funds",
    "narration": "Contractor payment",
    "type": "outflow",
    "applicable_fee": 150,
    "meta": {},
    "created": 1760434049154,
    "updated": 1760434050159
  }
}

outflows.cancelled

Fired when a transfer is cancelled before it is processed. The payload shape is identical to outflows.created. The status field will be failed and status_reason will be cancelled_by_user.

{
  "event": "outflows.cancelled",
  "data": {
    "id": "01K7H0QM421E9CB5M24W5AK3Q3",
    "amount": 25000,
    "currency": "USD",
    "unique_reference": "PAY-2025-003",
    "counterparty_id": "01K76NZW807BYPWACT2JX6B9J8",
    "account_id": "01K747KD7QW8KQS2GRD8MQBT55",
    "entity_id": "01K3HJAK85YJP13WJ41P3CWAVM",
    "status": "failed",
    "status_reason": "cancelled_by_user",
    "narration": "Office supplies order",
    "type": "outflow",
    "applicable_fee": 250,
    "meta": {},
    "created": 1760434049154,
    "updated": 1760434050159
  }
}

payment_intent.completed

Fired when a Payment Intent completes successfully. Use this event to fulfil the customer’s order or mark the payment as paid.

{
  "event": "payment_intent.completed",
  "data": {
    "id": "01HXYZ7K3M9PQRST4UVWXY2Z6",
    "currency": "USD",
    "amount": 5000,
    "reference": "order_abc123",
    "description": "Order #1042",
    "status": "completed",
    "entity_id": "ent_01HXYZ1234ABCD",
    "account_id": "acc_01HXYZ5678EFGH",
    "created": 1735725600000
  }
}

payment_intent.failed

Fired when a Payment Intent cannot be completed. Check status_reason when it is present.

{
  "event": "payment_intent.failed",
  "data": {
    "id": "01HXYZ7K3M9PQRST4UVWXY2Z6",
    "currency": "USD",
    "amount": 5000,
    "reference": "order_abc123",
    "description": "Order #1042",
    "status": "failed",
    "status_reason": "card_declined",
    "entity_id": "ent_01HXYZ1234ABCD",
    "account_id": "acc_01HXYZ5678EFGH",
    "created": 1735725600000
  }
}

payment_intent.cancelled

Fired when a Payment Intent is cancelled before it is confirmed.

{
  "event": "payment_intent.cancelled",
  "data": {
    "id": "01HXYZ7K3M9PQRST4UVWXY2Z6",
    "currency": "USD",
    "amount": 5000,
    "reference": "order_abc123",
    "description": "Order #1042",
    "status": "cancelled",
    "status_reason": "Customer abandoned checkout",
    "entity_id": "ent_01HXYZ1234ABCD",
    "account_id": "acc_01HXYZ5678EFGH",
    "created": 1735725600000
  }
}

payment_refund.completed

Fired when a refund request completes successfully.

{
  "event": "payment_refund.completed",
  "data": {
    "id": "refund_1234567890",
    "reference": "refund_001",
    "payment_intent_action_id": "pay_1234567890",
    "amount": 5000,
    "currency": "USD",
    "refund_reason": "Customer requested a refund",
    "status": "successful",
    "account_id": "acc_1234567890",
    "entity_id": "ent_1234567890",
    "created": 1700000000000
  }
}

payment_refund.failed

Fired when a refund request fails.

{
  "event": "payment_refund.failed",
  "data": {
    "id": "refund_1234567890",
    "reference": "refund_001",
    "payment_intent_action_id": "pay_1234567890",
    "amount": 6000,
    "currency": "USD",
    "refund_reason": "Customer requested a refund",
    "status": "failed",
    "status_reason": "The requested refund amount exceeds the amount collected for this payment.",
    "account_id": "acc_1234567890",
    "entity_id": "ent_1234567890",
    "created": 1700000000000
  }
}

funding_sessions_updated

Fired when a funding session is updated, such as when it is settled or failed.

{
  "event": "funding_sessions.updated",
  "data": {
    "id": "01KVWE0R84AZBXR3PD7V7CMQV0",
    "status": "settled",
    "previous_status": "awaiting_user",
    "amount": 10000,
    "currency": "GBP",
    "account_id": "01KH37RPG1SM7VHA3B9EQF3VEW",
    "unique_reference": "1782291912280",
    "narration": "Funding session",
    "settlement": {    
        "rail": "bacs", // this particular field exist for just open-banking
        "settled_at": 1782292167277
    }
  }
}

If the funding session failed, then the failure object is included.

{
  "event": "funding_sessions.updated",
  "data": {
    "id": "01KVWEM1WSN706RF3WJ7KF5ZQ4",
    "status": "failed",
    "previous_status": "awaiting_user",
    "amount": 1000,
    "currency": "GBP",
    "account_id": "01KH37RPG1SM7VHA3B9EQF3VEW",
    "unique_reference": "1782292544740",
    "narration": "Funding session",
    "failure": {
        "code": "INSUFFICIENT_FUNDS",
        "message": "There isn't enough money in this account to complete the payment. Try again, or select another account or bank.",
        "failed_at": 1782292572343
    }
  }
}

Failure Codes

The failure.code field identifies the reason for funding session failures. The codes are as follows:

Code	Description
`PAYMENT_BLOCKED`	Payment was blocked for violating compliance rules
`PAYMENT_REJECTED`	Payment was rejected by the financial institution
`PAYMENT_CANCELLED`	User cancelled the payment during authorisation
`INSUFFICIENT_FUNDS`	Account does not have enough funds
`INSTITUTION_UNAVAILABLE`	Financial institution is temporarily down or not responding
`INSTITUTION_NOT_SUPPORTED`	Financial institution is no longer supported on provider
`PROVIDER_ERROR`	Undocumented error fromm provider
`SESSION_EXPIRED`	Checkout URL expired before the user completed the payment flow

A data.meta field may also be included with additional information if you send any additional data to the field. The contents of this field vary by provider and are not guaranteed to be present. But for momo, a data.meta containing msisdn and channel field will always be present.

Get Started

Core Concepts

Webhooks

Guides

accounts.created

account_details.created

account_details.updated

inflows.completed

outflows.created

outflows.completed

outflows.failed

outflows.cancelled

payment_intent.completed

payment_intent.failed

payment_intent.cancelled

payment_refund.completed

payment_refund.failed

funding_sessions_updated

Failure Codes

​accounts.created

​account_details.created

​account_details.updated

​inflows.completed

​outflows.created

​outflows.completed

​outflows.failed

​outflows.cancelled

​payment_intent.completed

​payment_intent.failed

​payment_intent.cancelled

​payment_refund.completed

​payment_refund.failed

​funding_sessions_updated

​Failure Codes

accounts.created

account_details.created

account_details.updated

inflows.completed

outflows.created

outflows.completed

outflows.failed

outflows.cancelled

payment_intent.completed

payment_intent.failed

payment_intent.cancelled

payment_refund.completed

payment_refund.failed

funding_sessions_updated

Failure Codes