The Violet Payments system, Prism Pay, is designed to support a wide variety of payment and payout flows across different merchants, apps, and platforms. Whether you’re using Violet to orchestrate payments or simply tracking them through external providers, the core set of objects you’ll encounter are:

  1. PaymentTransaction - Tracks the intent and status of payments from shoppers.
  2. Distribution- Represents how funds from an order are split across merchants and channels.
  3. Transfer- Represents the movement of funds from your platform Payment Provider account to the merchant Payment Provider account.
  4. Payout- Represents the actual payout of funds to merchants or channels.

When a refund occurs, the following additional objects are available in Prism Pay to represent the movement of funds and accurate states.

  1. Refund - An object tied to the Order itself to holistically represent the refund from the external ecom platform.
  2. Distribution - These are the same as Distributions during Checkout, however, are negative in amount to represent a debit.
  3. TransferReversal - Tracks the reversal of funds previously paid out.

Each of these objects plays a critical role in understanding how money moves through Violet from shopper to merchant (and back, if refunded).

​
Core Objects and Flows

​
Payment Transactions

A PaymentTransaction represents the shopper-facing payment activity for a specific Order. It tracks:

  • Which Order and Bags are being paid for
  • Amount and currency being charged
  • Payment method and provider (e.g., Stripe)
  • Capture and transfer statuses (e.g., CAPTURED, FAILED, REFUNDED)
  • Errors and provider-specific metadata

Use this object to monitor the status of a payment and confirm whether the shopper has been charged successfully. Learn more here.

​
Distributions

A Distribution breaks down the funds collected from a shopper into amounts owed to different parties: merchants and channels. It includes:

  • The Bag and Order associated with the distribution
  • Who the funds are going to (MERCHANT, CHANNEL)
  • The amount and currency
  • Tax information (if applicable)
  • Status indicators for when the funds were transferred or reversed

These records are the foundation for financial reporting and reconciliation. You can view them in the Violet dashboard or export them for further analysis. Learn more here.

​
Transfers

A Transfer represents the movement of funds to a merchant or channel from your platform payment provider account, based on one or more Distributions. It includes:

  • Linked Distribution, Order, and Bag IDs
  • Amount and currency
  • Payment provider transaction identifiers
  • Status (PENDING, SENT, FAILED, etc.)

This object helps confirm that a merchant has been paid out for their share of an order. Learn more here.

​
Payouts

The Payout object represents the actual transfer of funds from the Payment Provider (e.g. Stripe) to a connected merchants bank account, and is usually an aggregate of multiple Transfers. In includes:

  • Unique IDs for both the Violet and Payment Provider payout objects.
  • Links back to the associated Transfers and Distributions that contributed to the Payout
  • Amount and currency
  • Status (PENDING, IN_TRANSIT, SETTLED, FAILED, etc.)

This object helps confirm that a merchant has received funds in their bank account for Orders placed through your app via Violet. Learn more here.

​
Refund

A Refund represents a formal refund request initiated by a merchant or app for a specific Order, Bag, or SKU. It also links together the refund’s financial consequences on Transfers and Distributions. A Refund includes:

  • The Order, Bag, and App initiating the refund
  • The related PaymentTransaction and provider-level transaction ID
  • Refunded amount (in shopper and platform currencies)
  • Associated TransferReversal IDs that show how payouts are clawed back
  • A breakdown of refunded SKUs, shipping, and tax amounts
  • Refund status (PROCESSING, COMPLETED, FAILED, etc.)
  • Optional reason codes (e.g. FRAUD, INVENTORY, CUSTOMER)
  • Linked errors, if any

​
Transfer Reversals

A TransferReversal is created when funds that were sent to a merchant need to be pulled back—typically due to a refund. It includes:

  • The original Transfer that’s being reversed
  • The amount and reason for the reversal
  • Status (PENDING, COMPLETE, or FAILED)
  • Provider-specific reversal IDs and metadata

These are automatically created and tracked when using Violet-managed transfers. Learn more here.

​
How These Objects Work Together

Here’s how these concepts flow together during Checkout:

Order created
    ↓
PaymentTransaction created and captured
    ↓
Payment Distributions created (defines who gets what)
    ↓
Transfers initiated (payouts sent to parties)
    ↓
If refunded:
    → Refund created
        → Refund Distributions created (defines the amounts being reversed from each party)
        → TransferReversals created