{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Virtual cash webhook events","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":"virtual-cash-webhook-events","__idx":0},"children":["Virtual cash webhook events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide documents the webhook event types available for the virtual cash domain. Webhooks enable you to track virtual cash increases and decreases through their complete lifecycle and be notified immediately at each state transition, eliminating the need to poll for status updates."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"event-types-overview","__idx":1},"children":["Event types overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Upvest sends webhook notifications whenever a virtual cash increase or decrease changes status during processing. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIRTUAL_CASH_INCREASE.*"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIRTUAL_CASH_DECREASE.*"]}," events fire at each state transition as requests progress from initial creation through confirmation, queuing, or cancellation, allowing your application to track the entire lifecycle."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Virtual cash operations enable managing tradeable balances for your end users. Each operation progresses through defined states, with webhooks sent for each transition:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["ISSUED (request created) → CONFIRMED (balance available or removed) or QUEUED (pending sufficient funds) or CANCELLED."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"virtual-cash-event-table","__idx":2},"children":["Virtual cash event table"]},{"$$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 type"},"children":["Event type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Trigger"},"children":["Trigger"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$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_CASH_INCREASE.ISSUED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Increase requested."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Immediate"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A virtual cash increase request has been created. The balance increase is pending confirmation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIRTUAL_CASH_INCREASE.CONFIRMED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Increase confirmed."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Immediate"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The virtual cash increase has been confirmed. The balance is now available for trading."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIRTUAL_CASH_INCREASE.CANCELLED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cancellation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Immediate"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The virtual cash increase has been cancelled.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"For certain tax wrappers, like German pensions, you may receive a cancellation if an increase would cause the end user to exceed their allowance limit."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIRTUAL_CASH_DECREASE.ISSUED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Decrease requested."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Immediate"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A virtual cash decrease request has been created. The balance reduction is pending confirmation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIRTUAL_CASH_DECREASE.CONFIRMED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Decrease confirmed."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Immediate"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The virtual cash decrease has been confirmed. The cash balance has been removed from the account."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIRTUAL_CASH_DECREASE.QUEUED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Insufficient funds."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Immediate"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The virtual cash decrease could not be confirmed due to insufficient available funds. The request has been placed in the backlog queue and will automatically move to CONFIRMED once sufficient funds arrive."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIRTUAL_CASH_DECREASE.CANCELLED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cancellation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Immediate"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The virtual cash decrease has been cancelled. Only possible if the decrease was in ISSUED or QUEUED state."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"virtual-cash-lifecycle","__idx":3},"children":["Virtual cash lifecycle"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Virtual cash increases and decreases follow defined lifecycles with state transitions. The following diagrams show typical flows:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"increase-lifecycle","__idx":4},"children":["Increase lifecycle"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"Increase requested\n     ↓\nVIRTUAL_CASH_INCREASE.ISSUED\n     ↓\nIncrease confirmed\n     ↓\nVIRTUAL_CASH_INCREASE.CONFIRMED\n     ↓\nBalance available for trading\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"decrease-lifecycle","__idx":5},"children":["Decrease lifecycle"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"Decrease requested\n     ↓\nVIRTUAL_CASH_DECREASE.ISSUED\n     ↓\nEither:\n  → VIRTUAL_CASH_DECREASE.CONFIRMED (sufficient funds)\n  → VIRTUAL_CASH_DECREASE.QUEUED (insufficient funds, enters backlog)\n     ↓\nIf queued and funds arrive later:\n  → VIRTUAL_CASH_DECREASE.CONFIRMED\n     ↓\nDecrease complete\n\n(Alternative: VIRTUAL_CASH_DECREASE.CANCELLED at ISSUED or QUEUED state)\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"virtual-cash-event-details","__idx":6},"children":["Virtual cash event details"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"virtual_cash_increaseissued","__idx":7},"children":["VIRTUAL_CASH_INCREASE.ISSUED"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sent when a virtual cash increase request has been received and is awaiting confirmation."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"3f6c1c4a-8e2d-4b9f-a1c3-2e5d7f9b4a6c\",\n  \"created_at\": \"2024-02-15T10:30:00.00Z\",\n  \"type\": \"VIRTUAL_CASH_INCREASE.ISSUED\",\n  \"object\": {\n    \"id\": \"increase-12345abc\",\n    \"account_group_id\": \"acg-67890def\",\n    \"amount\": \"1000.00\",\n    \"currency\": \"EUR\",\n    \"status\": \"ISSUED\",\n    \"created_at\": \"2024-02-15T10:30:00.000Z\",\n    \"updated_at\": \"2024-02-15T10:30:00.000Z\"\n  },\n  \"webhook_id\": \"webhook-abc123def456\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"virtual_cash_increaseconfirmed","__idx":8},"children":["VIRTUAL_CASH_INCREASE.CONFIRMED"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sent when the virtual cash increase has been confirmed and the balance is now available for trading."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"4a7d2d5b-9f3e-5c0a-b2d4-3f6e8a0c5b7d\",\n  \"created_at\": \"2024-02-15T10:30:15.00Z\",\n  \"type\": \"VIRTUAL_CASH_INCREASE.CONFIRMED\",\n  \"object\": {\n    \"id\": \"increase-12345abc\",\n    \"account_group_id\": \"acg-67890def\",\n    \"amount\": \"1000.00\",\n    \"currency\": \"EUR\",\n    \"status\": \"CONFIRMED\",\n    \"created_at\": \"2024-02-15T10:30:00.000Z\",\n    \"updated_at\": \"2024-02-15T10:30:15.000Z\"\n  },\n  \"webhook_id\": \"webhook-abc123def456\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"virtual_cash_decreaseissued","__idx":9},"children":["VIRTUAL_CASH_DECREASE.ISSUED"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sent when a virtual cash decrease request has been received and is awaiting confirmation or queuing."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"virtual_cash_decreaseconfirmed","__idx":10},"children":["VIRTUAL_CASH_DECREASE.CONFIRMED"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sent when a virtual cash decrease has been confirmed. The balance has been removed from the account. This may occur immediately if funds were available, or after the request was queued and funds later arrived."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"virtual_cash_decreasequeued","__idx":11},"children":["VIRTUAL_CASH_DECREASE.QUEUED"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sent when a virtual cash decrease could not be confirmed due to insufficient available funds. The request has entered the backlog queue and will automatically transition to CONFIRMED once sufficient funds arrive."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"virtual_cash_decreasecancelled","__idx":12},"children":["VIRTUAL_CASH_DECREASE.CANCELLED"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sent when a virtual cash decrease has been cancelled. Only possible if the decrease was in ISSUED or QUEUED state at the time of cancellation."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"field-descriptions","__idx":13},"children":["Field descriptions"]},{"$$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":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string (UUID)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unique identifier for this webhook event."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created_at"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string (ISO 8601 timestamp)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["When the webhook event was created (UTC)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Event type: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIRTUAL_CASH_INCREASE.ISSUED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIRTUAL_CASH_INCREASE.CONFIRMED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIRTUAL_CASH_DECREASE.ISSUED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIRTUAL_CASH_DECREASE.CONFIRMED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIRTUAL_CASH_DECREASE.QUEUED"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIRTUAL_CASH_DECREASE.CANCELLED"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["object.id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Virtual cash operation ID — use this to retrieve the operation status via the API."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["object.account_group_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string (UUID)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Account group ID associated with this virtual cash operation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["object.amount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string (decimal)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Amount of the operation in the specified currency."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["object.currency"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Currency of the operation (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EUR"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["object.status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Current operation status: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ISSUED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CONFIRMED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["QUEUED"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CANCELLED"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["object.created_at"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string (ISO 8601 timestamp)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["When the operation was created (UTC)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["object.updated_at"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string (ISO 8601 timestamp)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["When the operation was last updated (UTC)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string (UUID)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unique identifier for this webhook subscription — used for debugging."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"recommended-workflow","__idx":14},"children":["Recommended workflow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Follow these steps to implement virtual cash tracking via webhooks:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Set up webhook handler"]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Create an HTTP endpoint to listen for incoming webhooks. Endpoint must validate webhook signatures and respond with HTTP ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["204"]}," within 30 seconds.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"For more information, refer to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/byol/getting_started/implementing_webhooks"},"children":["Implementing webhooks"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Subscribe to VIRTUAL_CASH events"]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /webhooks"]}," with event types: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIRTUAL_CASH_INCREASE.ISSUED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIRTUAL_CASH_INCREASE.CONFIRMED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIRTUAL_CASH_DECREASE.ISSUED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIRTUAL_CASH_DECREASE.CONFIRMED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIRTUAL_CASH_DECREASE.QUEUED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIRTUAL_CASH_DECREASE.CANCELLED"]},".",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"For more information, refer to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api/webhook-subscriptions/create_webhook"},"children":["Webhook subscription"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Initiate virtual cash operation"]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /virtual_cash_balances/increases"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /virtual_cash_balances/decreases"]}," to begin the operation. Receive an operation ID in the response."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Handle VIRTUAL_CASH."]}," webhooks"]},"*",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Your webhook handler receives events at each state transition. Track the operation progress in your application state. For decreases that move to QUEUED, monitor for subsequent CONFIRMED events."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Handle queued decreases (optional)"]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"If a decrease enters QUEUED state, your application may notify the end user that the operation is pending. When funds arrive and the request moves to CONFIRMED, notify the user that the balance has been updated."]}]}]}]},"headings":[{"value":"Virtual cash webhook events","id":"virtual-cash-webhook-events","depth":1},{"value":"Event types overview","id":"event-types-overview","depth":2},{"value":"Virtual cash event table","id":"virtual-cash-event-table","depth":2},{"value":"Virtual cash lifecycle","id":"virtual-cash-lifecycle","depth":2},{"value":"Increase lifecycle","id":"increase-lifecycle","depth":3},{"value":"Decrease lifecycle","id":"decrease-lifecycle","depth":3},{"value":"Virtual cash event details","id":"virtual-cash-event-details","depth":2},{"value":"VIRTUAL_CASH_INCREASE.ISSUED","id":"virtual_cash_increaseissued","depth":3},{"value":"VIRTUAL_CASH_INCREASE.CONFIRMED","id":"virtual_cash_increaseconfirmed","depth":3},{"value":"VIRTUAL_CASH_DECREASE.ISSUED","id":"virtual_cash_decreaseissued","depth":3},{"value":"VIRTUAL_CASH_DECREASE.CONFIRMED","id":"virtual_cash_decreaseconfirmed","depth":3},{"value":"VIRTUAL_CASH_DECREASE.QUEUED","id":"virtual_cash_decreasequeued","depth":3},{"value":"VIRTUAL_CASH_DECREASE.CANCELLED","id":"virtual_cash_decreasecancelled","depth":3},{"value":"Field descriptions","id":"field-descriptions","depth":2},{"value":"Recommended workflow","id":"recommended-workflow","depth":2}],"frontmatter":{"seo":{"title":"Virtual cash webhook events"}},"lastModified":"2026-07-16T03:58:27.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/byol/guides/virtual_cash/virtual_cash_webhooks","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}