> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nuvion.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Event Types

> Full payload schemas and examples for every Nuvion webhook event.

All webhook payloads follow the same envelope:

```json theme={null}
{
  "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.

<ResponseField name="account" type="object">
  The newly created account.

  <Expandable title="account fields">
    <ResponseField name="id" type="string">Unique account identifier.</ResponseField>
    <ResponseField name="entity_id" type="string">The ID of the entity that owns this account.</ResponseField>
    <ResponseField name="type" type="string">Account type. e.g. `checking`.</ResponseField>
    <ResponseField name="currency" type="string">ISO 4217 currency code.</ResponseField>
    <ResponseField name="display_name" type="string">Human-readable account label.</ResponseField>

    <ResponseField name="balance" type="object">
      Current account balance.

      <Expandable title="balance fields">
        <ResponseField name="available" type="number">Available balance in the smallest currency unit.</ResponseField>
        <ResponseField name="current" type="number">Current balance including pending transactions.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="meta" type="object">Key-value metadata attached to the account.</ResponseField>
    <ResponseField name="created" type="number">Creation timestamp in Unix milliseconds.</ResponseField>
    <ResponseField name="updated" type="number">Last update timestamp in Unix milliseconds.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="entity_impact" type="object">
  Summary of how this account creation affects the entity.

  <Expandable title="entity_impact fields">
    <ResponseField name="entity_id" type="string">The entity ID.</ResponseField>
    <ResponseField name="total_accounts" type="number">Total number of accounts now held by this entity.</ResponseField>
    <ResponseField name="account_type" type="array">List of account types held by the entity.</ResponseField>
    <ResponseField name="default_account_set" type="boolean">Whether a default account has been set for this entity.</ResponseField>
  </Expandable>
</ResponseField>

```json theme={null}
{
  "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.

<ResponseField name="account_details" type="object">
  The newly created account details record.

  <Expandable title="account_details fields">
    <ResponseField name="id" type="string">Unique identifier for the account details record.</ResponseField>
    <ResponseField name="entity_id" type="string">The ID of the entity that owns this account.</ResponseField>
    <ResponseField name="account_id" type="string">The ID of the account these details belong to.</ResponseField>
    <ResponseField name="account_number" type="string">The assigned account number.</ResponseField>
    <ResponseField name="routing_number" type="string">The routing number (where applicable).</ResponseField>

    <ResponseField name="issuer" type="object">
      The issuing bank or institution.

      <Expandable title="issuer fields">
        <ResponseField name="code" type="string">Institution code.</ResponseField>
        <ResponseField name="name" type="string">Institution name.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="status" type="string">Account details status. e.g. `active`.</ResponseField>
    <ResponseField name="created" type="number">Creation timestamp in Unix milliseconds.</ResponseField>
    <ResponseField name="updated" type="number">Last update timestamp in Unix milliseconds.</ResponseField>
  </Expandable>
</ResponseField>

```json theme={null}
{
  "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.

<ResponseField name="id" type="string">Unique identifier for the account details record.</ResponseField>
<ResponseField name="entity_id" type="string">The ID of the entity that owns this account.</ResponseField>
<ResponseField name="account_id" type="string">The ID of the account these details belong to.</ResponseField>
<ResponseField name="account_number" type="string">The account number.</ResponseField>

<ResponseField name="issuer" type="object">
  The issuing bank or institution.

  <Expandable title="issuer fields">
    <ResponseField name="code" type="string">Institution code.</ResponseField>
    <ResponseField name="name" type="string">Institution name.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="status" type="string">Updated status of the account details record.</ResponseField>
<ResponseField name="created" type="number">Original creation timestamp in Unix milliseconds.</ResponseField>
<ResponseField name="updated" type="number">Timestamp of this update in Unix milliseconds.</ResponseField>

```json theme={null}
{
  "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.

<ResponseField name="id" type="string">Unique identifier for the inflow transaction.</ResponseField>
<ResponseField name="amount" type="number">Amount received in the smallest currency unit.</ResponseField>
<ResponseField name="currency" type="string">ISO 4217 currency code.</ResponseField>
<ResponseField name="unique_reference" type="string">Unique reference for the transaction. Use this to deduplicate events.</ResponseField>
<ResponseField name="counterparty_id" type="string">Identifier of the sending counterparty.</ResponseField>
<ResponseField name="account_id" type="string">The ID of the account that received the funds.</ResponseField>
<ResponseField name="entity_id" type="string">The ID of the entity that owns the receiving account.</ResponseField>
<ResponseField name="status" type="string">Transaction status. `successful` for completed inflows.</ResponseField>
<ResponseField name="status_reason" type="string">Human-readable status description.</ResponseField>
<ResponseField name="narration" type="string">Payment reference or description from the sender.</ResponseField>
<ResponseField name="type" type="string">`inflow`.</ResponseField>
<ResponseField name="applicable_fee" type="number">Fee applied to this transaction in the smallest currency unit.</ResponseField>
<ResponseField name="meta" type="object">Key-value metadata.</ResponseField>
<ResponseField name="created" type="number">Creation timestamp in Unix milliseconds.</ResponseField>
<ResponseField name="updated" type="number">Last update timestamp in Unix milliseconds.</ResponseField>

```json theme={null}
{
  "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.

<ResponseField name="id" type="string">Unique identifier for the outflow transaction.</ResponseField>
<ResponseField name="amount" type="number">Transfer amount in the smallest currency unit.</ResponseField>
<ResponseField name="currency" type="string">ISO 4217 currency code.</ResponseField>
<ResponseField name="unique_reference" type="string">The idempotency key passed when initiating the transfer.</ResponseField>
<ResponseField name="counterparty_id" type="string">The ID of the recipient counterparty.</ResponseField>
<ResponseField name="account_id" type="string">The ID of the source account being debited.</ResponseField>
<ResponseField name="entity_id" type="string">The ID of the entity initiating the transfer.</ResponseField>
<ResponseField name="status" type="string">`pending` — transfer is queued and awaiting processing.</ResponseField>
<ResponseField name="status_reason" type="string">`awaiting_processing`.</ResponseField>
<ResponseField name="narration" type="string">Transfer description.</ResponseField>
<ResponseField name="type" type="string">`outflow`.</ResponseField>
<ResponseField name="applicable_fee" type="number">Fee applied to this transfer in the smallest currency unit.</ResponseField>
<ResponseField name="meta" type="object">Key-value metadata.</ResponseField>
<ResponseField name="created" type="number">Creation timestamp in Unix milliseconds.</ResponseField>
<ResponseField name="updated" type="number">Last update timestamp in Unix milliseconds.</ResponseField>

```json theme={null}
{
  "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`.

```json theme={null}
{
  "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`.

<Note>
  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.
</Note>

```json theme={null}
{
  "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`.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.