# Payment webhooks

Throughout the payment lifecycle — from top-up confirmation to settlement, withdrawal processing, and credit funding — Upvest sends webhook events to notify you of progress at each stage. Monitor these webhooks to track funding, settlement, and withdrawal status.

## Payment event types

Upvest sends webhooks across five payment categories, each with distinct lifecycle stages.

### Top-up events

The `TOPUP.*` event type notifies you of changes to a top-up's lifecycle.

| Event | Trigger | When It Fires |
|  --- | --- | --- |
| `TOPUP.CONFIRMED` | Top-up is confirmed. | Immediately when POST `/payments/topups` completes successfully. |
| `TOPUP.SETTLED` | Top-up settlement completes. | When funds are received and processed by Upvest. |
| `TOPUP.CANCELLED` | Top-up is cancelled. | When a CONFIRMED top-up is cancelled via DELETE `/payments/topups/{topupID}`. |


**Lifecycle**: CONFIRMED → SETTLED (or CANCELLED)

### Withdrawal events

The `WITHDRAWAL.*` event type notifies you of changes to a withdrawal's lifecycle.

| Event | Trigger | When It Fires |
|  --- | --- | --- |
| `WITHDRAWAL.NEW` | Withdrawal is initiated. | Immediately when POST `/payments/withdrawals` completes successfully. |
| `WITHDRAWAL.PROCESSING` | Withdrawal processing begins. | When Upvest begins processing the withdrawal request with the bank. |
| `WITHDRAWAL.CONFIRMED` | Withdrawal settlement completes. | When the bank confirms the withdrawal and funds reach the user's account. |
| `WITHDRAWAL.CANCELLED` | Withdrawal is cancelled. | When a withdrawal is cancelled by user or system. |


**Lifecycle**: NEW → PROCESSING → CONFIRMED (or CANCELLED)

### Direct debit events

The `DIRECT_DEBIT.*` event type notifies you of changes to a direct debit's lifecycle.

| Event | Trigger | When It Fires |
|  --- | --- | --- |
| `DIRECT_DEBIT.NEW` | Direct debit is initiated. | Immediately when POST `/payments/direct-debits` completes successfully. |
| `DIRECT_DEBIT.PROCESSING` | Direct debit processing begins. | When Upvest processes the direct debit mandate and begins payment processing. |
| `DIRECT_DEBIT.CONFIRMED` | Direct debit settlement completes. | When the direct debit is settled and funds are confirmed. |
| `DIRECT_DEBIT.CANCELLED` | Direct debit is cancelled. | When a direct debit is cancelled by user or system. |


**Lifecycle**: NEW → PROCESSING → CONFIRMED (or CANCELLED)

### Credit funding events

The `CREDIT_FUNDING.*` event type notifies you of changes to credit funding via virtual bank accounts (VIBANs).

| Event | Trigger | When It Fires |
|  --- | --- | --- |
| `CREDIT_FUNDING.CONFIRMED` | Credit funding is confirmed. | Immediately when funds are received and credited to the virtual account. |
| `CREDIT_FUNDING.CANCELLED` | Credit funding is cancelled. | When a credit funding operation is cancelled. |


**Lifecycle**: CONFIRMED (or CANCELLED) — immediate, no intermediate states

### Virtual bank account events

The `VIRTUAL_BANK_ACCOUNT.*` event type notifies you of changes to virtual bank account lifecycle.

| Event | Trigger | When It Fires |
|  --- | --- | --- |
| `VIRTUAL_BANK_ACCOUNT.CREATED` | VIBAN is created. | Immediately when POST `/payments/virtual-bank-accounts` completes successfully. |


**Lifecycle**: CREATED — terminal event

## Payment lifecycle flows

### Top-up lifecycle

```
CONFIRMED → SETTLED
        ↓
      CANCELLED
```

- **CONFIRMED**: Top-up request accepted, credit balance updated in real time
- **SETTLED**: Bank transfer received and processed (0–5 business days)
- **CANCELLED**: Top-up cancelled before settlement


### Withdrawal lifecycle

```
NEW → PROCESSING → CONFIRMED
      ↓
    CANCELLED
```

- **NEW**: Withdrawal initiated, pending processing
- **PROCESSING**: Upvest sends withdrawal to the bank (1–3 business days)
- **CONFIRMED**: Bank confirms withdrawal, funds reach user account
- **CANCELLED**: Withdrawal cancelled during processing


### Direct debit lifecycle

```
NEW → PROCESSING → CONFIRMED
      ↓
    CANCELLED
```

- **NEW**: Direct debit mandate accepted, ready for processing
- **PROCESSING**: Payment processing with bank via SEPA (2–5 business days)
- **CONFIRMED**: SEPA direct debit settled and confirmed
- **CANCELLED**: Direct debit cancelled during processing


### Credit funding (VIBAN) lifecycle

```
CONFIRMED (or CANCELLED immediately)
```

- **CONFIRMED**: Funds credited to virtual account instantly upon receipt
- **CANCELLED**: Funding cancelled (rare, typically after CONFIRMED)


### Virtual bank account (VIBAN) lifecycle

```
CREATED
```

- **CREATED**: VIBAN provisioned and ready to receive transfers


## Example webhook payloads

### Top-up confirmed event

When a top-up is initiated, you receive a `TOPUP.CONFIRMED` event:

```json
{
  "id": "evt-topup-confirmed-001",
  "created_at": "2024-03-01T09:00:00Z",
  "type": "TOPUP.CONFIRMED",
  "object": {
    "id": "topup-001",
    "created_at": "2024-03-01T09:00:00Z",
    "updated_at": "2024-03-01T09:00:00Z",
    "account_group_id": "acc-group-001",
    "amount": 5000.00,
    "currency": "EUR",
    "status": "CONFIRMED",
    "settlement_reference": "topup-settlement-ref-123"
  },
  "webhook_id": "wh-topup-confirmed-001"
}
```

### Withdrawal processing event

When withdrawal processing begins, you receive a `WITHDRAWAL.PROCESSING` event:

```json
{
  "id": "evt-withdrawal-processing-001",
  "created_at": "2024-03-02T10:30:00Z",
  "type": "WITHDRAWAL.PROCESSING",
  "object": {
    "id": "withdrawal-001",
    "created_at": "2024-03-01T14:00:00Z",
    "updated_at": "2024-03-02T10:30:00Z",
    "account_group_id": "acc-group-001",
    "amount": 2000.00,
    "currency": "EUR",
    "status": "PROCESSING",
    "destination_account": {
      "account_number": "DE89370400440532013000",
      "account_holder": "Jane Doe"
    }
  },
  "webhook_id": "wh-withdrawal-processing-001"
}
```

### Direct debit confirmed event

When a direct debit settles, you receive a `DIRECT_DEBIT.CONFIRMED` event:

```json
{
  "id": "evt-direct-debit-confirmed-001",
  "created_at": "2024-03-05T08:00:00Z",
  "type": "DIRECT_DEBIT.CONFIRMED",
  "object": {
    "id": "direct-debit-001",
    "created_at": "2024-03-01T15:00:00Z",
    "updated_at": "2024-03-05T08:00:00Z",
    "account_group_id": "acc-group-001",
    "amount": 1500.00,
    "currency": "EUR",
    "status": "CONFIRMED",
    "mandate_id": "mandate-001",
    "creditor_reference": "creditor-ref-789"
  },
  "webhook_id": "wh-direct-debit-confirmed-001"
}
```

### Credit funding confirmed event

When funds are credited to a VIBAN, you receive a `CREDIT_FUNDING.CONFIRMED` event:

```json
{
  "id": "evt-credit-funding-confirmed-001",
  "created_at": "2024-03-03T11:00:00Z",
  "type": "CREDIT_FUNDING.CONFIRMED",
  "object": {
    "id": "credit-funding-001",
    "created_at": "2024-03-03T11:00:00Z",
    "updated_at": "2024-03-03T11:00:00Z",
    "virtual_account_id": "viban-001",
    "amount": 10000.00,
    "currency": "EUR",
    "status": "CONFIRMED",
    "reference": "INVOICE-12345"
  },
  "webhook_id": "wh-credit-funding-confirmed-001"
}
```

### Virtual bank account created event

When a VIBAN is provisioned, you receive a `VIRTUAL_BANK_ACCOUNT.CREATED` event:

```json
{
  "id": "evt-viban-created-001",
  "created_at": "2024-02-28T12:00:00Z",
  "type": "VIRTUAL_BANK_ACCOUNT.CREATED",
  "object": {
    "id": "viban-001",
    "created_at": "2024-02-28T12:00:00Z",
    "updated_at": "2024-02-28T12:00:00Z",
    "account_group_id": "acc-group-001",
    "account_number": "DE89370400440532013000",
    "bank_code": "37040044",
    "account_holder": "Upvest Client Account",
    "currency": "EUR",
    "status": "CREATED"
  },
  "webhook_id": "wh-viban-created-001"
}
```

## Recommended workflow

Use webhooks to track payment operations automatically:

Set up webhook listener
Configure your webhook endpoint to listen for payment events. See [Implementing webhooks](/products/byol/getting_started/implementing_webhooks) for setup instructions.

Subscribe to all payment event types: `TOPUP.*`, `WITHDRAWAL.*`, `DIRECT_DEBIT.*`, `CREDIT_FUNDING.*`, `VIRTUAL_BANK_ACCOUNT.*`.

Initiate a top-up or withdrawal
Create a top-up via POST `/payments/topups` or a withdrawal via POST `/payments/withdrawals`. You receive a `TOPUP.CONFIRMED` or `WITHDRAWAL.NEW` event immediately.

Monitor payment processing
For top-ups: wait for `TOPUP.SETTLED` webhook (may take 0–5 business days depending on bank processing).

For withdrawals: monitor `WITHDRAWAL.PROCESSING` (processing begins within hours) and then `WITHDRAWAL.CONFIRMED` (1–3 business days).

For direct debits: monitor `DIRECT_DEBIT.PROCESSING` and then `DIRECT_DEBIT.CONFIRMED` (2–5 business days).

Do not poll the payment status endpoint; wait for webhook events instead.

Handle cancellations
If a payment is cancelled, you receive `TOPUP.CANCELLED`, `WITHDRAWAL.CANCELLED`, or `DIRECT_DEBIT.CANCELLED`. Update your application state and inform the user of the cancellation.

Manage virtual bank accounts
When you create a VIBAN, you receive a `VIRTUAL_BANK_ACCOUNT.CREATED` event with the account details. Monitor for `CREDIT_FUNDING.CONFIRMED` events as external parties transfer funds to the VIBAN.

Reconcile settlement
Use webhook events to reconcile payment settlement. For each top-up or withdrawal, validate that the appropriate settlement event (`TOPUP.SETTLED`, `WITHDRAWAL.CONFIRMED`, `DIRECT_DEBIT.CONFIRMED`) was received.

Update user interface
Use the webhook stream to update your application's payment status display in real time. Once a settlement event is received (e.g., `TOPUP.SETTLED`), confirm successful completion to the user.