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.
Upvest sends webhooks across five payment categories, each with distinct lifecycle stages.
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)
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)
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)
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
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
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
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
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
CONFIRMED (or CANCELLED immediately)- CONFIRMED: Funds credited to virtual account instantly upon receipt
- CANCELLED: Funding cancelled (rare, typically after CONFIRMED)
CREATED- CREATED: VIBAN provisioned and ready to receive transfers
When a top-up is initiated, you receive a TOPUP.CONFIRMED event:
{
"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"
}When withdrawal processing begins, you receive a WITHDRAWAL.PROCESSING event:
{
"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"
}When a direct debit settles, you receive a DIRECT_DEBIT.CONFIRMED event:
{
"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"
}When funds are credited to a VIBAN, you receive a CREDIT_FUNDING.CONFIRMED event:
{
"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"
}When a VIBAN is provisioned, you receive a VIRTUAL_BANK_ACCOUNT.CREATED event:
{
"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"
}Use webhooks to track payment operations automatically:
Set up webhook listener
Configure your webhook endpoint to listen for payment events. See 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.