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.

Related Documentation

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, 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.

PreviousSyncsNextPayment Transactions

Last updated

Was this helpful?