# Payments during Checkout

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.

5. `Refund` - An object tied to the `Order` itself to holistically represent the refund from the external ecom platform.
6. `Distribution` - These are the same as Distributions during Checkout, however, are negative in amount to represent a debit.
7. `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 `Bag`s 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](/prism/payments/payments-during-checkout/payment-transactions.md).

### 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](/prism/payments/payouts/distributions.md).

### 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](/prism/payments/payments-during-checkout/transfers.md).

### 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](/prism/payments/payouts.md).

### 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](/prism/payments/payments-during-checkout/transfer-reversals.md).

## **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
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.violet.io/prism/payments/payments-during-checkout.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.