# Transfers Transfer webhooks notify your application about the lifecycle of funds moving from your platform to merchant accounts. These events are essential for tracking payment distributions, handling failed transfers, and managing refund reversals. ## Overview Transfer webhooks specifically relate to **transfer updates**, enabling you to monitor the lifecycle of funds moving from your platform to the merchant's connected Prism Pay account. Learn more about Transfers in the [Transfers documentation](https://docs.violet.io/prism/payments/payments-during-checkout/transfers). ## Available Events ### TRANSFER\_SENT **Trigger:** When a `Transfer` is successfully sent to a merchant's connected payment provider account. **Use Case:** Subscribe to this event to: * Confirm successful fund transfers to merchants * Update payout status in dashboards * Log successful transfers for compliance * Trigger merchant payout notifications * Update financial reporting * Calculate payout timing metrics **Significance:** This event indicates that the full transfer amount has been successfully transferred from your connected Platform Account and is now in the merchant's Stripe Connect account (or other payment provider account). ### TRANSFER\_PARTIALLY\_SENT **Trigger:** When only part of a `Transfer` is successfully sent to a merchant's connected payment provider account. **Use Case:** Monitor this event to: * Track partial transfer completion * Calculate remaining transfer amounts * Update payout status to reflect partial completion * Alert teams to investigate partial transfer reasons * Log partial transfer events for reconciliation **When This Occurs:** * Insufficient funds in platform account for full transfer * Platform account limitations preventing full transfer * Split transfers due to payment processor constraints * Partial transfer due to merchant account restrictions **Important:** When a transfer is only partially sent, you should investigate the root cause and complete the remaining transfer amount. The merchant has only received part of their expected payout. **Next Steps:** Resolve the issue preventing full transfer and complete the remaining amount. Monitor for another `TRANSFER_PARTIALLY_SENT` or `TRANSFER_SENT` event for the remainder. ### TRANSFER\_FAILED **Trigger:** When a `Transfer` fails to be sent to a merchant's connected payment provider account. **Use Case:** Monitor this event to: * Alert internal teams to transfer failures * Notify merchants of payout issues * Log failure reasons for debugging * Implement retry mechanisms * Track transfer reliability * Investigate merchant account issues **Common Failure Reasons:** * Insufficient funds in platform account * Invalid merchant account details * Issues with the payment provider * Merchant account not properly configured * Platform account limitations exceeded **Action Required:** Transfer failures typically require investigation and resolution before funds can be successfully transferred to the merchant. ### TRANSFER\_UPDATED **Trigger:** A catch-all event for any updates to a `Transfer` within Violet. **Use Case:** Subscribe to this event to: * Track all transfer state changes * Monitor transfer lifecycle comprehensively * Log transfer history * Update transfer status in dashboards * Track transfer modifications **Common Updates:** * Status changes during transfer reversals * Metadata updates * Amount adjustments * State transitions ### TRANSFER\_REVERSED **Trigger:** When a refund is being processed and funds are reversed from a `Transfer` to a merchant. **Use Case:** Monitor this event to: * Track full refund reversals * Update merchant payout balances * Reconcile financial records * Adjust commission distributions * Log reversal events for compliance * Update merchant notifications **Important:** This event indicates that funds previously transferred to a merchant are being returned due to a complete order refund. The merchant's account balance will be reduced by the reversal amount. ### TRANSFER\_PARTIALLY\_REVERSED **Trigger:** When a partial refund is being processed and a portion of the funds are reversed from a merchant's `Transfer`. **When and Why This Happens:** **Common Scenarios:** * **Single-item refund in multi-item order**: Customer returns one item from an order containing multiple items * **Partial quantity refund**: Customer returns 2 out of 5 units ordered * **Price adjustment**: Merchant issues a partial refund for a damaged item without requiring return * **Shipping-excluded refund**: Customer charged for shipping but the amount of the items and tax is refunded * **Multi-merchant order with partial return**: In an order with items from multiple merchants, only one merchant's items are returned **How It Works:** 1. Customer requests a partial refund or returns some items 2. Merchant processes partial refund through their platform (or Channel processes refund via Violet API) 3. Violet identifies the original Transfer that sent funds to the merchant 4. A TransferReversal object is created for the partial amount 5. Funds are reversed from the merchant's payout account 6. `TRANSFER_PARTIALLY_REVERSED` event fires 7. Merchant's net payout balance is reduced by the reversal amount **Multiple Partial Reversals:** The same transfer can be partially reversed multiple times. For example: * Original order: $100 (Transfer sent to merchant) * First partial refund: $30 → `TRANSFER_PARTIALLY_REVERSED` fires (merchant owes $30 back) * Second partial refund: $20 → `TRANSFER_PARTIALLY_REVERSED` fires again (merchant owes additional $20) * Remaining transfer value: $50 If the remaining $50 is refunded, `TRANSFER_REVERSED` would fire (full reversal). **Use Case:** Subscribe to this event to: * Track partial refund reversals accurately * Calculate remaining net transfer amounts * Update payout records in real-time * Adjust commissions proportionally based on actual retained sales * Reconcile partial refunds with payment transactions * Update merchant payout dashboards with current net amounts * Track patterns in partial refunds per merchant **Impact:** * Merchant's payout balance is immediately reduced by the reversed amount * If the merchant hasn't been paid out yet, the amount is deducted before transfer * If the merchant has already been paid, the amount may be deducted from future payouts or require immediate reversal * Your platform may need to adjust commission calculations based on the reduced order value **Related Events:** * See `TRANSFER_REVERSED` for full transfer reversals * Monitor `ORDER_REFUNDED` for the corresponding order-level refund event * Check `PAYMENT_TRANSACTION_CAPTURE_STATUS_PARTIALLY_REFUNDED` for customer refund status **Note:** The correct event name is `TRANSFER_PARTIALLY_REVERSED` (not `TRANSFER_PARTIALLY_REFUNDED`). This event indicates funds being reversed from a merchant transfer, not the customer-facing refund itself. ### TRANSFER\_REVERSAL\_FAILED **Trigger:** When a transfer reversal fails. **Use Case:** Monitor this event to: * Alert teams to reversal failures * Investigate reversal issues * Implement fallback strategies * Contact payment provider support * Track reversal reliability * Handle customer refund delays **When This Occurs:** * Transfer reversal is not successful for any reason * Exceptions from the underlying payment provider (e.g., Stripe) * Insufficient funds in merchant account * Invalid account configuration * Payment provider limitations **Error Information:** Both the `Transfer` and `TransferReversal` objects contain information about the error when a reversal fails. **Impact:** When a transfer reversal fails, the customer refund may be delayed or require manual intervention. Immediate action is typically required to resolve the issue. ## Related Documentation * [Transfers](https://docs.violet.io/prism/payments/payments-during-checkout/transfers) - Learn about the Transfer model * [Transfer Reversals](https://docs.violet.io/prism/payments/payments-during-checkout/transfer-reversals) - Understand refund processing * [Handling Failed Transfers](https://docs.violet.io/prism/payments/payments-during-checkout/guides/handling-failed-transfers) - Guide for managing transfer failures * [Payment Transactions](https://docs.violet.io/prism/payments/payments-during-checkout/payment-transactions) - Understand the full payment flow * [Handling Webhooks](https://docs.violet.io/prism/webhooks/handling-webhooks) - Process transfer webhooks properly ## Best Practices 1. **Handle TRANSFER\_FAILED immediately** - Transfer failures require prompt attention. Implement alerting and investigation workflows for failed transfers. 2. **Monitor reversal failures closely** - `TRANSFER_REVERSAL_FAILED` events can impact customer refunds. Escalate these failures quickly to ensure customers receive their refunds. 3. **Track transfer-to-merchant mapping** - Maintain a clear mapping of which transfers belong to which merchants and orders for easier reconciliation. 4. **Coordinate with Payment Transaction events** - Transfer events often occur alongside Payment Transaction events. Monitor both for complete financial visibility. 5. **Implement retry logic carefully** - For failed transfers, implement retry logic with exponential backoff, but investigate the root cause before retrying excessively. 6. **Calculate net payouts** - When processing reversals, calculate the net payout amount to merchants accounting for both transfers and reversals. 7. **Update merchant dashboards in real-time** - Use transfer events to update merchant-facing dashboards with current payout status and amounts. 8. **Log all transfer events** - Maintain comprehensive logs of all transfer events for financial reconciliation and compliance purposes. ## Webhook Headers Transfer webhooks include the [default webhook headers](https://docs.violet.io/prism/webhooks/managing-webhook-headers), plus: ### X-Violet-Order-Id Contains the Violet Order ID associated with this transfer. ### X-Violet-Entity-Id Contains the Transfer ID for the transfer that was updated. ## Common Integration Patterns ### Successful Transfer Flow ``` TRANSFER_SENT → Update merchant payout status → Log successful transfer → Notify merchant ``` ### Failed Transfer Flow ``` TRANSFER_FAILED → Alert team → Investigate cause → Resolve issue → Retry transfer ``` ### Refund Reversal Flow ``` Order refunded → Payment refunded to customer TRANSFER_REVERSED → Reverse funds from merchant → Update payout balance ``` ### Partial Refund Reversal Flow ``` Partial order refund → Partial payment refund TRANSFER_PARTIALLY_REVERSED → Reverse partial funds → Calculate new net payout ``` ### Reversal Failure Handling ``` TRANSFER_REVERSAL_FAILED → Alert team → Check error details → Contact payment provider → Manual resolution ``` ## Coordinating with Other Events Transfer events often occur in conjunction with other webhook events. Understanding the full flow helps ensure proper processing: ### Full Refund with Transfer Reversal ``` ORDER_REFUNDED → Full order refund initiated PAYMENT_TRANSACTION_CAPTURE_STATUS_REFUNDED → Funds refunded to customer TRANSFER_REVERSED → Funds reversed from merchant payout ``` ### Partial Refund with Partial Reversal ``` ORDER_REFUNDED (partial) → Partial refund initiated PAYMENT_TRANSACTION_CAPTURE_STATUS_PARTIALLY_REFUNDED → Partial funds to customer TRANSFER_PARTIALLY_REVERSED → Partial funds reversed from merchant ``` ### Failed Transfer Scenario ``` Order completed → Transfer initiated TRANSFER_FAILED → Transfer cannot complete Investigate → Resolve issue → Retry TRANSFER_SENT → Transfer succeeds ``` Monitor all related event types for complete visibility into the payment and transfer lifecycle. ## Understanding Transfer States Transfers typically progress through these states: 1. **Pending** - Transfer created but not yet sent 2. **Partially Sent** - Transfer partially sent to merchant account (`TRANSFER_PARTIALLY_SENT`) 3. **Sent** - Transfer successfully sent to merchant account (`TRANSFER_SENT`) 4. **Failed** - Transfer failed to send (`TRANSFER_FAILED`) 5. **Reversed** - Transfer fully reversed due to refund (`TRANSFER_REVERSED`) 6. **Partially Reversed** - Transfer partially reversed (`TRANSFER_PARTIALLY_REVERSED`) Track these state transitions using the webhook events to maintain accurate financial records and merchant payout information.