Prism Payout Accounts

The Prism Payout Account (PPA) acts as a wrapper around an underlying payment provider account, enabling payment orchestration. Each PPA is linked to a specific account with the payment provider, and merchants can have multiple PPAs. However, only one PPA is active for payouts at any given time. Violet provides you with the ability to view Payout Accounts via APIs and Webhooks to let you build any custom flows needed around Merchant enablement or onboarding.

Payout Account Onboarding Overview

When merchants connect to your app through Violet Connect, the type of payout account created depends on your app's transfer mechanism configuration and the merchant's country.

How Onboarding Works

The onboarding flow is determined by two factors:

1. Transfer Mechanism: Your app's configured transfer mechanism (STANDARD_TRANSFERS or DESTINATION_PAYMENTS)

2. Country Support: Whether the merchant's banking country supports the transfer mechanism

Merchant Onboards → Check Transfer Mechanism → Check Country Support → Create Payout Account
                           ↓                           ↓
                    STANDARD_TRANSFERS        Country in supported
                    or DESTINATION_PAYMENTS   transfer countries?
                                                      ↓
                                              YES → STRIPE Account (Express or Standard)
                                              NO  → EXTERNAL Account

Country Support by Transfer Mechanism

Different transfer mechanisms use different country support checks:

Transfer Mechanism	Country Check	How It Works
STANDARD_TRANSFERS	Stripe supported transfer countries	Checks if merchant's country is in the platform's supported transfer countries list via Stripe CountrySpec API
DESTINATION_PAYMENTS	Stripe destination charge support	Checks if merchant's country supports Stripe destination charges (i.e., "stripe" is in the country's supported payment methods)

Important: The same country may have different support status depending on your transfer mechanism. A country might support standard transfers but not destination charges, or vice versa. This is determined by Stripe's capabilities for that country.

Onboarding Decision Tree

┌─────────────────────────────────────────────────────────────────────┐
│                    Merchant Connects to App                          │
└─────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
         ┌─────────────────────────────────────────────┐
         │   What is the App's Transfer Mechanism?      │
         └─────────────────────────────────────────────┘
                    │                          │
        STANDARD_TRANSFERS            DESTINATION_PAYMENTS
                    │                          │
                    ▼                          ▼
    ┌───────────────────────────┐  ┌───────────────────────────┐
    │ Is merchant's country in  │  │ Does merchant's country   │
    │ supported transfer        │  │ support Stripe destination│
    │ countries list?           │  │ charges?                  │
    └───────────────────────────┘  └───────────────────────────┘
           │           │                  │           │
          YES          NO                YES          NO
           │           │                  │           │
           ▼           ▼                  ▼           ▼
    ┌──────────┐ ┌──────────┐      ┌──────────┐ ┌──────────┐
    │  STRIPE  │ │ EXTERNAL │      │  STRIPE  │ │ EXTERNAL │
    │ Account  │ │ Account  │      │ Account  │ │ Account  │
    └──────────┘ └──────────┘      └──────────┘ └──────────┘

Account Type Comparison

Aspect	STRIPE Account	EXTERNAL Account
When Created	Country supports the transfer mechanism	Country does NOT support the transfer mechanism
KYC Required	Yes (via Stripe)	No
Transfer Processing	Automatic via Prism Pay	Manual by Channel outside Violet
Stripe Dashboard	Available	Not available
Distribution Tracking	Yes	Yes
Merchant Visibility	Full payout tracking in Merchant Dashboard	Can view pending distributions only

Business Value of Each Account Type

STRIPE Payout Accounts

• Automated payouts: Funds flow automatically through Stripe without manual intervention

• Built-in KYC: Stripe handles identity verification and compliance

• Merchant dashboard access: Merchants can view transfers and payouts directly in Stripe

• Transfer reversal support: Auto-debit capabilities for handling refunds post-payout (Express accounts)

EXTERNAL Payout Accounts

• Global reach: Accept merchants from countries not supported by Stripe

• Payment provider flexibility: Process payouts through any payment method (wire transfers, other providers)

• No KYC friction: Faster onboarding for merchants in unsupported regions

• Distribution tracking: Still leverage Violet's distribution and bookkeeping features

Sample Prism Payout Account

{
    "id": 13618,
    "merchant_id": 15756,
    "app_id": 10000,
    "is_active": true,
    "country_code": "US",
    "payment_provider": "STRIPE",
    "payment_provider_account_id": "acct_asdfghjklASDFGH",
    "payment_provider_account": {
        "account_id": "acct_asdfghjklASDFGH",
        "account_type": "EXPRESS",
        "email": "[email protected]",
        "banking_country": "US",
        "banking_currency": "usd",
        "charges_enabled": true,
        "payouts_enabled": true,
        "requirements": {
            "alternatives": [],
            "currently_due": [],
            "errors": [],
            "eventually_due": [],
            "past_due": [],
            "pending_verification": []
        },
        "date_created": "2025-03-18T16:03:01+0000",
        "date_last_modified": "2025-04-05T00:39:53+0000"
    },
    "errors": [],
    "date_created": "2025-03-18T16:03:01+0000",
    "date_last_modified": "2025-04-05T03:19:20+0000",
}

The following fields are available in the Prism Pay Payout Account:

Field	Type	Sample Value	Description
id	Long	12345	Unique identifier for the Violet Payout Account.
account_type	Enum	"MERCHANT"	Type of the account entity in Violet. This value is always MERCHANT for merchant payout accounts.
account_id	Long	12345	Identifier of the account entity in Violet. For merchants, this is the Violet Merchant ID.
app_id	Long	11206	Unique identifier of the app that this Violet Payout Account is associated with.
is_active	Boolean	true	Whether or not the payout account is currently active. Only one Payout Account can be active for a given app_id.
country_code	String	"US"	Two-letter country code of the bank that this Payout Account is associated to.
payment_provider	String	"STRIPE"	The payment provider backing the underlying payout account.
payment_provider_account_id	String	"acct_1R42bBHasdfghjk2"	Identifier of the payout account in the payment provider system.
payment_provider_account	Object	{}	A custom object representing specific details about the Payout Account in the underlying Payment Provider.
errors	nullable List of Strings	[]	A list of errors associated with this Violet Payout Account, if any.
date_created	String in ISO-8601 format	"2025-03-18T16:03:01+0000"	Time at which the object was created. In ISO-8601 format.
date_last_modified	String in ISO-8601 format	"2025-04-05T03:19:20+0000"	Time at which the object was last modified. In ISO-8601 format.

The following fields are available in the underlying Payment Provider Account when the payment provider of the Violet Payout Account is STRIPE . You can learn more about these fields in the Stripe docs.

Field	Type	Sample Value	Description
account_id	String	"acct_1R42bBHJKNmFQUp2"	Unique identifier of the account in the payment provider system.
account_type	String	"EXPRESS"	Type of account (e.g. EXPRESS, STANDARD, CUSTOM) with the provider
banking_country	String	"US"	Country where the banking account is registered
banking_currency	String	"usd"	Currency used for banking operations
charges_enabled	Boolean	true	Indicates if the account can accept transfers from the platform account. From the perspective of the payout account, Stripe refers to this as a charge, which is why this field is called charges_enabled .
payouts_enabled	Boolean	true	Indicates whether or not payouts are enabled on the underlying Stripe account. A Payout is money moving from the Stripe Connect account to the merchants connected bank account.
requirements	Object	{}	Object detailing account verification and onboarding requirements.
date_created	String in ISO-8601 format	"2025-03-18T16:03:01+0000"	Timestamp when the payment provider account was created
date_last_modified	String in ISO-8601 format	"2025-04-05T00:39:53+0000"	Timestamp of the most recent update to the account in the payment provider.

Requirements

The requirements section of the STRIPE payment_provider_account directly corresponds to KYC information that Stripe requires for this account to remain in good standing.

Field	Type	Sample Value	Description
alternatives	nullable List of Strings	[]	Fields that are due and can be satisfied by providing the corresponding alternative fields instead.
currently_due	nullable List of Strings	[]	Fields that need to be collected to keep the account enabled. If not collected by current_deadline, these fields appear in past_due as well, and the account is disabled.
errors	nullable List of Strings	[]	Fields that are currently_due and need to be collected again because validation or verification failed.
eventually_due	nullable List of Strings	[]	Fields you must collect when all thresholds are reached. As they become required, they appear in currently_due as well, and current_deadline becomes set.
past_due	nullable List of Strings	[]	Fields that weren’t collected by current_deadline. These fields need to be collected to enable the account.
pending_verification	nullable List of Strings	[]	Fields that might become required depending on the results of verification or review. It's an empty array unless an asynchronous verification is pending. If verification fails, these fields move to eventually_due, currently_due, or past_due. Fields might appear in eventually_due, currently_due, or past_due and in pending_verification if verification fails but another verification is still pending.

---

EXTERNAL Payout Accounts

In some cases, a merchant's country may not be supported by Stripe for destination charges or standard transfers. When this happens, Violet automatically creates an EXTERNAL payout account as a fallback mechanism.

When EXTERNAL Accounts Are Created

EXTERNAL payout accounts are created automatically during Violet Connect when the merchant's country is not supported by Stripe for the channel's configured transfer mechanism:

Transfer Mechanism	Country Check	EXTERNAL Created When
DESTINATION_PAYMENTS	Stripe destination charge support	Merchant's country doesn't support Stripe destination charges
STANDARD_TRANSFERS	Supported transfer countries list	Merchant's country isn't in the list of supported transfer countries

The transfer mechanism is configured at the app level. See Transfer Mechanisms for more information on configuring your app's transfer mechanism.

Key Characteristics

Aspect	STRIPE Account	EXTERNAL Account
payment_provider_account_id	Stripe account ID (e.g., acct_xxx)	Not set (null)
payment_provider_account	Contains Stripe account details	Not set (null)
KYC Validation	Required (charges/payouts enabled)	None required
Initial is_active state	Based on KYC completion	false (requires explicit activation unless first payout account)
Transfer Processing	Via Prism Pay (Stripe)	Cannot be processed through Prism Pay
Dashboard Link	Available via Stripe	Not available

Sample EXTERNAL Payout Account

{
    "id": 14500,
    "merchant_id": 16000,
    "app_id": 10000,
    "is_active": false,
    "country_code": "NG",
    "payment_provider": "EXTERNAL",
    "payment_provider_account_id": null,
    "payment_provider_account": null,
    "errors": [],
    "date_created": "2025-03-18T16:03:01+0000",
    "date_last_modified": "2025-03-18T16:03:01+0000"
}

Note how the EXTERNAL payout account differs from a STRIPE account:

• payment_provider is "EXTERNAL" instead of "STRIPE"

• payment_provider_account_id is null (no underlying payment provider account)

• payment_provider_account is null (no provider-specific details)

• is_active is false by default (requires explicit activation unless it's the merchant's first payout account for this app)

Working with EXTERNAL Payout Accounts

Transfers Must Be External

Transfers for merchants with EXTERNAL payout accounts cannot be processed through Prism Pay. Attempting to process a transfer through Prism Pay for a merchant with an EXTERNAL payout account will result in an error.

Channels must:

1. Process transfers to merchants independently (e.g., via direct bank transfer, wire transfer, or another payment provider)

2. Register these transfers with Violet using the Register Transfer API to keep distributions in sync

See Using External Transfers for the complete guide on handling transfers for merchants with EXTERNAL payout accounts.

No KYC Requirements

EXTERNAL accounts don't have KYC validation requirements since there's no underlying payment provider account.

---

Payout Account APIs

You can retrieve Prism Pay Payout Accounts using the following APIs:

• Get active Prism Pay Account by Violet Merchant ID

• Get all Prism Pay Accounts for a Merchant

• Get Prism Pay Account by specific Prism Pay Account ID

Webhooks

The following events are available for you to subscribe to in order to receive updates about the Prism Pay Payout Account:

• MERCHANT_PAYOUT_ACCOUNT_CREATED

• MERCHANT_PAYOUT_ACCOUNT_REQUIREMENTS_UPDATED

Learn more here