# Payout Accounts Payout Account webhooks notify your application about changes to merchant payout accounts, which enable merchants to receive payments through your platform. These events are essential for tracking merchant onboarding progress and payout account status. ## Available Events ### MERCHANT\_PAYOUT\_ACCOUNT\_CREATED **Trigger:** When a new Violet Payout Account is created for a merchant. **Use Case:** Subscribe to this event to: * Track merchant payout onboarding progress * Send confirmation emails to merchants * Update merchant dashboard status * Log account creation for compliance * Trigger next steps in onboarding flow **Significance:** This event indicates the merchant has completed the first step in enabling payouts through your application. However, the account may still need additional information (KYC requirements) before it can be activated. ### MERCHANT\_PAYOUT\_ACCOUNT\_REQUIREMENTS\_UPDATED **Trigger:** When the KYC or onboarding requirements for a merchant's payout account are updated. **Use Case:** Monitor this event to: * Notify merchants of additional information needed * Display updated requirements in merchant dashboard * Track KYC completion progress * Send reminder emails for pending requirements * Update compliance status **When This Occurs:** * After account creation, when initial requirements are set * When Stripe (or another provider) requests additional information * When requirements are satisfied and cleared * When requirements expire and need to be resubmitted **Important:** This event can fire multiple times throughout the account lifecycle as requirements change. ### MERCHANT\_PAYOUT\_ACCOUNT\_ACTIVATED **Trigger:** When a Prism Payout Account is marked as the active payout account. **Use Case:** Subscribe to this event to: * Enable payment processing for the merchant * Congratulate merchants on completing setup * Begin processing payouts * Update merchant status to "active" * Trigger payment-related features **Important:** Only one Payout Account can be marked as active at any given time per merchant. ### MERCHANT\_PAYOUT\_ACCOUNT\_DEACTIVATED **Trigger:** When a Prism Payout Account is deactivated. **Use Case:** Monitor this event to: * Update merchant payout status * Pause payout processing * Notify merchants of deactivation * Log deactivation events * Update internal dashboards **When This Occurs:** A Payout Account is deactivated when a different Payout Account is marked as `active`. This is not an error condition—it simply means another account is now the active one. ### MERCHANT\_PAYOUT\_ACCOUNT\_DELETED **Trigger:** When a Prism Payout Account is deleted. **Use Case:** Monitor this event to: * Clean up payout account data * Update merchant records * Remove payout-related features if no active account exists * Log deletion for audit purposes * Notify relevant stakeholders **Note:** Currently, accounts can only be deleted via API. Learn more about [deleting payout accounts](https://docs.violet.io/prism/payments/payouts/prism-payout-accounts/delete-payout-accounts). ## Related Documentation * [Prism Payout Accounts](https://docs.violet.io/prism/payments/payouts/prism-payout-accounts) - Learn about payout accounts * [Payout Account Setup](https://docs.violet.io/prism/payments/payouts/prism-payout-accounts/setting-up-a-payout-account) - Set up payout accounts for merchants * [Stripe KYC Guide](https://docs.violet.io/prism/payments/payouts/guides/stripe-kyc-guide) - Understand KYC requirements * [Delete Payout Accounts](https://docs.violet.io/prism/payments/payouts/prism-payout-accounts/delete-payout-accounts) - Learn about account deletion * [Violet Connect Payouts](https://docs.violet.io/prism/violet-connect/payouts) - Understand payouts in the connection flow ## Best Practices 1. **Track the full lifecycle** - Monitor all five events to maintain a complete view of each merchant's payout account status. 2. **Handle requirements proactively** - When receiving `MERCHANT_PAYOUT_ACCOUNT_REQUIREMENTS_UPDATED`, proactively reach out to merchants with clear guidance on what information is needed. 3. **Don't process payouts before activation** - Only enable payout features after receiving `MERCHANT_PAYOUT_ACCOUNT_ACTIVATED` to ensure the account is ready. 4. **Handle account switching** - When an account is deactivated due to another being activated, update your systems to use the new active account for future payouts. 5. **Store account history** - Keep records of all payout account events for compliance and support purposes. 6. **Validate before operations** - Always verify that a payout account is active before attempting to process payouts. 7. **Monitor requirements status** - Requirements can change over time (e.g., expiring documents). Stay updated by processing `REQUIREMENTS_UPDATED` events promptly. ## Webhook Headers Payout Account webhooks include the [default webhook headers](https://docs.violet.io/prism/webhooks/managing-webhook-headers), which contain: * `X-Violet-Entity-Id` - The Violet Payout Account ID * `X-Violet-Topic` - The event type (MERCHANT\_PAYOUT\_ACCOUNT\_CREATED, etc.) * `X-Violet-Event-Id` - Unique event identifier for idempotency ## Common Integration Patterns ### Merchant Onboarding Flow ``` MERCHANT_PAYOUT_ACCOUNT_CREATED → Fetch requirements → Display to merchant MERCHANT_PAYOUT_ACCOUNT_REQUIREMENTS_UPDATED → Check if complete → Update UI MERCHANT_PAYOUT_ACCOUNT_ACTIVATED → Enable payouts → Notify merchant ``` ### Account Management ``` MERCHANT_PAYOUT_ACCOUNT_ACTIVATED → Set as default account → Update config MERCHANT_PAYOUT_ACCOUNT_DEACTIVATED → Log change → Update to new active account MERCHANT_PAYOUT_ACCOUNT_DELETED → Clean up references → Archive data ``` ### Compliance Tracking ``` MERCHANT_PAYOUT_ACCOUNT_REQUIREMENTS_UPDATED → Parse requirements → Update compliance dashboard Requirements complete → Wait for activation MERCHANT_PAYOUT_ACCOUNT_ACTIVATED → Mark compliant → Enable features ``` ## Understanding Account States Payout accounts typically progress through these states: 1. **Created** - Account exists but may need requirements fulfilled 2. **Requirements Pending** - Additional information needed from merchant 3. **Requirements Complete** - All requirements satisfied, ready for activation 4. **Activated** - Account is active and can receive payouts 5. **Deactivated** - Account exists but another account is now active 6. **Deleted** - Account has been removed Monitor these webhook events to track state transitions and ensure merchants can successfully receive payouts.