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.

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 - Learn about the Transfer model

• Transfer Reversals - Understand refund processing

• Handling Failed Transfers - Guide for managing transfer failures

• Payment Transactions - Understand the full payment flow

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