{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["Steps","Step"]},"type":"markdown"},"seo":{"title":"Payment webhooks","description":"Welcome to the Upvest API documentation. Here you will find all the information you need to integrate with our API.","siteUrl":"https://docs.upvest.co/","image":"/assets/upvest-logo-card.ee25ccc59849324b0b73151a5c972c87639419556344db0b6dcf518151cb4c3c.925ff8b2.png","keywords":"documentation, api","lang":"en-US","meta":[{"name":"description","content":"Welcome to the Upvest API documentation. Here you will find all the information you need to integrate with our API."},{"name":"image","content":"/assets/upvest-logo-card.ee25ccc59849324b0b73151a5c972c87639419556344db0b6dcf518151cb4c3c.925ff8b2.png"},{"name":"twitter:card","content":"summary_large_image"},{"name":"twitter:title","content":"Welcome to the Upvest API Documentation"},{"name":"twitter:image","content":"/assets/upvest-logo-card.ee25ccc59849324b0b73151a5c972c87639419556344db0b6dcf518151cb4c3c.925ff8b2.png"},{"name":"twitter:description","content":"Welcome to the Upvest API documentation. Here you will find all the information you need to integrate with our API."},{"name":"og:url","content":"https://docs.upvest.co/"},{"name":"og:title","content":"Welcome to the Upvest API Documentation"},{"name":"og:description","content":"Welcome to the Upvest API documentation. Here you will find all the information you need to integrate with our API."},{"name":"og:image","content":"/assets/upvest-logo-card.ee25ccc59849324b0b73151a5c972c87639419556344db0b6dcf518151cb4c3c.925ff8b2.png"}]},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"payment-webhooks","__idx":0},"children":["Payment webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"payment-event-types","__idx":1},"children":["Payment event types"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Upvest sends webhooks across five payment categories, each with distinct lifecycle stages."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"top-up-events","__idx":2},"children":["Top-up events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TOPUP.*"]}," event type notifies you of changes to a top-up's lifecycle."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Event"},"children":["Event"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Trigger"},"children":["Trigger"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"When It Fires"},"children":["When It Fires"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TOPUP.CONFIRMED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Top-up is confirmed."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Immediately when POST ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/payments/topups"]}," completes successfully."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TOPUP.SETTLED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Top-up settlement completes."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["When funds are received and processed by Upvest."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TOPUP.CANCELLED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Top-up is cancelled."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["When a CONFIRMED top-up is cancelled via DELETE ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/payments/topups/{topupID}"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Lifecycle"]},": CONFIRMED → SETTLED (or CANCELLED)"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"withdrawal-events","__idx":3},"children":["Withdrawal events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WITHDRAWAL.*"]}," event type notifies you of changes to a withdrawal's lifecycle."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Event"},"children":["Event"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Trigger"},"children":["Trigger"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"When It Fires"},"children":["When It Fires"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WITHDRAWAL.NEW"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Withdrawal is initiated."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Immediately when POST ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/payments/withdrawals"]}," completes successfully."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WITHDRAWAL.PROCESSING"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Withdrawal processing begins."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["When Upvest begins processing the withdrawal request with the bank."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WITHDRAWAL.CONFIRMED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Withdrawal settlement completes."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["When the bank confirms the withdrawal and funds reach the user's account."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WITHDRAWAL.CANCELLED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Withdrawal is cancelled."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["When a withdrawal is cancelled by user or system."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Lifecycle"]},": NEW → PROCESSING → CONFIRMED (or CANCELLED)"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"direct-debit-events","__idx":4},"children":["Direct debit events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DIRECT_DEBIT.*"]}," event type notifies you of changes to a direct debit's lifecycle."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Event"},"children":["Event"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Trigger"},"children":["Trigger"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"When It Fires"},"children":["When It Fires"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DIRECT_DEBIT.NEW"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Direct debit is initiated."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Immediately when POST ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/payments/direct-debits"]}," completes successfully."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DIRECT_DEBIT.PROCESSING"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Direct debit processing begins."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["When Upvest processes the direct debit mandate and begins payment processing."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DIRECT_DEBIT.CONFIRMED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Direct debit settlement completes."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["When the direct debit is settled and funds are confirmed."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DIRECT_DEBIT.CANCELLED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Direct debit is cancelled."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["When a direct debit is cancelled by user or system."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Lifecycle"]},": NEW → PROCESSING → CONFIRMED (or CANCELLED)"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"credit-funding-events","__idx":5},"children":["Credit funding events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CREDIT_FUNDING.*"]}," event type notifies you of changes to credit funding via virtual bank accounts (VIBANs)."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Event"},"children":["Event"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Trigger"},"children":["Trigger"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"When It Fires"},"children":["When It Fires"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CREDIT_FUNDING.CONFIRMED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Credit funding is confirmed."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Immediately when funds are received and credited to the virtual account."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CREDIT_FUNDING.CANCELLED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Credit funding is cancelled."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["When a credit funding operation is cancelled."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Lifecycle"]},": CONFIRMED (or CANCELLED) — immediate, no intermediate states"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"virtual-bank-account-events","__idx":6},"children":["Virtual bank account events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIRTUAL_BANK_ACCOUNT.*"]}," event type notifies you of changes to virtual bank account lifecycle."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Event"},"children":["Event"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Trigger"},"children":["Trigger"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"When It Fires"},"children":["When It Fires"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIRTUAL_BANK_ACCOUNT.CREATED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["VIBAN is created."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Immediately when POST ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/payments/virtual-bank-accounts"]}," completes successfully."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Lifecycle"]},": CREATED — terminal event"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"payment-lifecycle-flows","__idx":7},"children":["Payment lifecycle flows"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"top-up-lifecycle","__idx":8},"children":["Top-up lifecycle"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"CONFIRMED → SETTLED\n        ↓\n      CANCELLED\n"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["CONFIRMED"]},": Top-up request accepted, credit balance updated in real time"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SETTLED"]},": Bank transfer received and processed (0–5 business days)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["CANCELLED"]},": Top-up cancelled before settlement"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"withdrawal-lifecycle","__idx":9},"children":["Withdrawal lifecycle"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"NEW → PROCESSING → CONFIRMED\n      ↓\n    CANCELLED\n"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["NEW"]},": Withdrawal initiated, pending processing"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["PROCESSING"]},": Upvest sends withdrawal to the bank (1–3 business days)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["CONFIRMED"]},": Bank confirms withdrawal, funds reach user account"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["CANCELLED"]},": Withdrawal cancelled during processing"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"direct-debit-lifecycle","__idx":10},"children":["Direct debit lifecycle"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"NEW → PROCESSING → CONFIRMED\n      ↓\n    CANCELLED\n"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["NEW"]},": Direct debit mandate accepted, ready for processing"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["PROCESSING"]},": Payment processing with bank via SEPA (2–5 business days)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["CONFIRMED"]},": SEPA direct debit settled and confirmed"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["CANCELLED"]},": Direct debit cancelled during processing"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"credit-funding-viban-lifecycle","__idx":11},"children":["Credit funding (VIBAN) lifecycle"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"CONFIRMED (or CANCELLED immediately)\n"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["CONFIRMED"]},": Funds credited to virtual account instantly upon receipt"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["CANCELLED"]},": Funding cancelled (rare, typically after CONFIRMED)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"virtual-bank-account-viban-lifecycle","__idx":12},"children":["Virtual bank account (VIBAN) lifecycle"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"CREATED\n"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["CREATED"]},": VIBAN provisioned and ready to receive transfers"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"example-webhook-payloads","__idx":13},"children":["Example webhook payloads"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"top-up-confirmed-event","__idx":14},"children":["Top-up confirmed event"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a top-up is initiated, you receive a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TOPUP.CONFIRMED"]}," event:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"evt-topup-confirmed-001\",\n  \"created_at\": \"2024-03-01T09:00:00Z\",\n  \"type\": \"TOPUP.CONFIRMED\",\n  \"object\": {\n    \"id\": \"topup-001\",\n    \"created_at\": \"2024-03-01T09:00:00Z\",\n    \"updated_at\": \"2024-03-01T09:00:00Z\",\n    \"account_group_id\": \"acc-group-001\",\n    \"amount\": 5000.00,\n    \"currency\": \"EUR\",\n    \"status\": \"CONFIRMED\",\n    \"settlement_reference\": \"topup-settlement-ref-123\"\n  },\n  \"webhook_id\": \"wh-topup-confirmed-001\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"withdrawal-processing-event","__idx":15},"children":["Withdrawal processing event"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When withdrawal processing begins, you receive a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WITHDRAWAL.PROCESSING"]}," event:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"evt-withdrawal-processing-001\",\n  \"created_at\": \"2024-03-02T10:30:00Z\",\n  \"type\": \"WITHDRAWAL.PROCESSING\",\n  \"object\": {\n    \"id\": \"withdrawal-001\",\n    \"created_at\": \"2024-03-01T14:00:00Z\",\n    \"updated_at\": \"2024-03-02T10:30:00Z\",\n    \"account_group_id\": \"acc-group-001\",\n    \"amount\": 2000.00,\n    \"currency\": \"EUR\",\n    \"status\": \"PROCESSING\",\n    \"destination_account\": {\n      \"account_number\": \"DE89370400440532013000\",\n      \"account_holder\": \"Jane Doe\"\n    }\n  },\n  \"webhook_id\": \"wh-withdrawal-processing-001\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"direct-debit-confirmed-event","__idx":16},"children":["Direct debit confirmed event"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a direct debit settles, you receive a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DIRECT_DEBIT.CONFIRMED"]}," event:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"evt-direct-debit-confirmed-001\",\n  \"created_at\": \"2024-03-05T08:00:00Z\",\n  \"type\": \"DIRECT_DEBIT.CONFIRMED\",\n  \"object\": {\n    \"id\": \"direct-debit-001\",\n    \"created_at\": \"2024-03-01T15:00:00Z\",\n    \"updated_at\": \"2024-03-05T08:00:00Z\",\n    \"account_group_id\": \"acc-group-001\",\n    \"amount\": 1500.00,\n    \"currency\": \"EUR\",\n    \"status\": \"CONFIRMED\",\n    \"mandate_id\": \"mandate-001\",\n    \"creditor_reference\": \"creditor-ref-789\"\n  },\n  \"webhook_id\": \"wh-direct-debit-confirmed-001\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"credit-funding-confirmed-event","__idx":17},"children":["Credit funding confirmed event"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When funds are credited to a VIBAN, you receive a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CREDIT_FUNDING.CONFIRMED"]}," event:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"evt-credit-funding-confirmed-001\",\n  \"created_at\": \"2024-03-03T11:00:00Z\",\n  \"type\": \"CREDIT_FUNDING.CONFIRMED\",\n  \"object\": {\n    \"id\": \"credit-funding-001\",\n    \"created_at\": \"2024-03-03T11:00:00Z\",\n    \"updated_at\": \"2024-03-03T11:00:00Z\",\n    \"virtual_account_id\": \"viban-001\",\n    \"amount\": 10000.00,\n    \"currency\": \"EUR\",\n    \"status\": \"CONFIRMED\",\n    \"reference\": \"INVOICE-12345\"\n  },\n  \"webhook_id\": \"wh-credit-funding-confirmed-001\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"virtual-bank-account-created-event","__idx":18},"children":["Virtual bank account created event"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a VIBAN is provisioned, you receive a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIRTUAL_BANK_ACCOUNT.CREATED"]}," event:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"evt-viban-created-001\",\n  \"created_at\": \"2024-02-28T12:00:00Z\",\n  \"type\": \"VIRTUAL_BANK_ACCOUNT.CREATED\",\n  \"object\": {\n    \"id\": \"viban-001\",\n    \"created_at\": \"2024-02-28T12:00:00Z\",\n    \"updated_at\": \"2024-02-28T12:00:00Z\",\n    \"account_group_id\": \"acc-group-001\",\n    \"account_number\": \"DE89370400440532013000\",\n    \"bank_code\": \"37040044\",\n    \"account_holder\": \"Upvest Client Account\",\n    \"currency\": \"EUR\",\n    \"status\": \"CREATED\"\n  },\n  \"webhook_id\": \"wh-viban-created-001\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"recommended-workflow","__idx":19},"children":["Recommended workflow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use webhooks to track payment operations automatically:"]},{"$$mdtype":"Tag","name":"Steps","attributes":{},"children":[{"$$mdtype":"Tag","name":"Step","attributes":{"title":"Set up webhook listener"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Configure your webhook endpoint to listen for payment events. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/byol/getting_started/implementing_webhooks"},"children":["Implementing webhooks"]}," for setup instructions."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Subscribe to all payment event types: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TOPUP.*"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WITHDRAWAL.*"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DIRECT_DEBIT.*"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CREDIT_FUNDING.*"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIRTUAL_BANK_ACCOUNT.*"]},"."]}]},{"$$mdtype":"Tag","name":"Step","attributes":{"title":"Initiate a top-up or withdrawal"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create a top-up via POST ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/payments/topups"]}," or a withdrawal via POST ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/payments/withdrawals"]},". You receive a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TOPUP.CONFIRMED"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WITHDRAWAL.NEW"]}," event immediately."]}]},{"$$mdtype":"Tag","name":"Step","attributes":{"title":"Monitor payment processing"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For top-ups: wait for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TOPUP.SETTLED"]}," webhook (may take 0–5 business days depending on bank processing)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For withdrawals: monitor ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WITHDRAWAL.PROCESSING"]}," (processing begins within hours) and then ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WITHDRAWAL.CONFIRMED"]}," (1–3 business days)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For direct debits: monitor ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DIRECT_DEBIT.PROCESSING"]}," and then ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DIRECT_DEBIT.CONFIRMED"]}," (2–5 business days)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not poll the payment status endpoint; wait for webhook events instead."]}]},{"$$mdtype":"Tag","name":"Step","attributes":{"title":"Handle cancellations"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If a payment is cancelled, you receive ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TOPUP.CANCELLED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WITHDRAWAL.CANCELLED"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DIRECT_DEBIT.CANCELLED"]},". Update your application state and inform the user of the cancellation."]}]},{"$$mdtype":"Tag","name":"Step","attributes":{"title":"Manage virtual bank accounts"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you create a VIBAN, you receive a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIRTUAL_BANK_ACCOUNT.CREATED"]}," event with the account details. Monitor for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CREDIT_FUNDING.CONFIRMED"]}," events as external parties transfer funds to the VIBAN."]}]},{"$$mdtype":"Tag","name":"Step","attributes":{"title":"Reconcile settlement"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use webhook events to reconcile payment settlement. For each top-up or withdrawal, validate that the appropriate settlement event (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TOPUP.SETTLED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WITHDRAWAL.CONFIRMED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DIRECT_DEBIT.CONFIRMED"]},") was received."]}]},{"$$mdtype":"Tag","name":"Step","attributes":{"title":"Update user interface"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the webhook stream to update your application's payment status display in real time. Once a settlement event is received (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TOPUP.SETTLED"]},"), confirm successful completion to the user."]}]}]}]},"headings":[{"value":"Payment webhooks","id":"payment-webhooks","depth":1},{"value":"Payment event types","id":"payment-event-types","depth":2},{"value":"Top-up events","id":"top-up-events","depth":3},{"value":"Withdrawal events","id":"withdrawal-events","depth":3},{"value":"Direct debit events","id":"direct-debit-events","depth":3},{"value":"Credit funding events","id":"credit-funding-events","depth":3},{"value":"Virtual bank account events","id":"virtual-bank-account-events","depth":3},{"value":"Payment lifecycle flows","id":"payment-lifecycle-flows","depth":2},{"value":"Top-up lifecycle","id":"top-up-lifecycle","depth":3},{"value":"Withdrawal lifecycle","id":"withdrawal-lifecycle","depth":3},{"value":"Direct debit lifecycle","id":"direct-debit-lifecycle","depth":3},{"value":"Credit funding (VIBAN) lifecycle","id":"credit-funding-viban-lifecycle","depth":3},{"value":"Virtual bank account (VIBAN) lifecycle","id":"virtual-bank-account-viban-lifecycle","depth":3},{"value":"Example webhook payloads","id":"example-webhook-payloads","depth":2},{"value":"Top-up confirmed event","id":"top-up-confirmed-event","depth":3},{"value":"Withdrawal processing event","id":"withdrawal-processing-event","depth":3},{"value":"Direct debit confirmed event","id":"direct-debit-confirmed-event","depth":3},{"value":"Credit funding confirmed event","id":"credit-funding-confirmed-event","depth":3},{"value":"Virtual bank account created event","id":"virtual-bank-account-created-event","depth":3},{"value":"Recommended workflow","id":"recommended-workflow","depth":2}],"frontmatter":{"seo":{"title":"Payment webhooks"}},"lastModified":"2026-07-16T03:58:27.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/byol/guides/payments/payments_webhooks","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}