# 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](https://docs.violet.io/prism/payments/payment-settings/transfer-mechanisms) 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) | {% hint style="warning" %} **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. {% endhint %} ### 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** ```json { "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": "chelseadabest@violet.io", "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](https://docs.stripe.com/api/accounts/object?lang=php). | **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](https://docs.violet.io/prism/payments/payment-settings/transfer-mechanisms): | 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 | {% hint style="info" %} The transfer mechanism is configured at the app level. See [Transfer Mechanisms](https://docs.violet.io/prism/payments/payment-settings/transfer-mechanisms) for more information on configuring your app's transfer mechanism. {% endhint %} ### 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 ```json { "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](https://docs.violet.io/prism/payments/payments-during-checkout/guides/using-external-transfers) to keep distributions in sync See [Using External Transfers](https://docs.violet.io/prism/payments/payments-during-checkout/guides/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](https://app.gitbook.com/s/8lXIp71Ct5qCUhXjko2q/payments/payout-accounts/get-payout-account) * [Get all Prism Pay Accounts for a Merchant](https://app.gitbook.com/s/8lXIp71Ct5qCUhXjko2q/payments/payout-accounts/get-payout-accounts) * [Get Prism Pay Account by specific Prism Pay Account ID](https://app.gitbook.com/s/8lXIp71Ct5qCUhXjko2q/payments/payout-accounts/get-payout-account-by-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](https://github.com/violetio/docs/blob/main/channel-docs/prism/payments/payouts/prism-payout-accounts/broken-reference/README.md)