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.

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:

Process transfers to merchants independently (e.g., via direct bank transfer, wire transfer, or another payment provider)
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:

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

PreviousPayouts NextPayout Account Setup

Last updated 2 days ago

Was this helpful?