# Instant payouts promotion

Show promotional content to increase Instant Payout conversion for your connected accounts.

Render a UI component for connected accounts that displays the ability to make an Instant Payout and the amount of funds available to pay out instantly. Connected accounts can initiate an Instant Payout through this component by clicking the call-to-action button.

Note: The following is a preview/demo component that behaves differently than live mode usage with real connected accounts. The actual component has more functionality than what might appear in this demo component. For example, for connected accounts without Stripe dashboard access (custom accounts), no user authentication is required in production.

## Display dynamic content

This component displays dynamic content (header, sub-header, call-to-action text) per connected account to increase instant payout usage. The content can change based on time (for example, weekends).

In addition, this component always shows the amount eligible for Instant Payouts.

## Display logic

### For connected accounts where Stripe is responsible for negative balances

The component renders when the following conditions are met:

- Stripe is responsible for negative balances ([defaults.responsibilities.losses_collector](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-defaults-responsibilities-losses_collector) has the value `stripe`)
- The connected account has funds eligible for Instant Payouts (as [determined by Stripe](https://support.stripe.com/questions/what-are-instant-payouts-and-who-is-eligible))
- In the component parameters, `enabled` is set to `true`

The component doesn’t render any UI otherwise.

### For connected accounts where the platform is responsible for negative balances

The component renders when the following conditions are met:

- The platform is responsible for negative balances ([defaults.responsibilities.losses_collector](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-defaults-responsibilities-losses_collector) has the value `application`)
- Your platform and connected account are in a supported country for Instant Payouts and meet the [eligibility criteria](https://docs.stripe.com/connect/instant-payouts.md#eligible-connected-accounts)
- The connected account has available funds to pay out
- In the component parameters, `enabled` is set to `true`

The component doesn’t render any UI otherwise.

> You’re liable for uncovered negative balances caused by refunds or disputes and are responsible for [managing risk and eligibility](https://docs.stripe.com/connect/instant-payouts.md#manage-risk-and-eligibility) for Instant Payouts. Additionally, you can determine whether the UI renders in the `onInstantPayoutsPromotionLoaded` callback function.

## Create an account session

When [creating an account session](https://docs.stripe.com/api/account_sessions/create.md), enable the Instant Payouts promotion component by specifying `instant_payouts_promotion` in the `components` parameter. This component requires the `instant_payouts` feature to be enabled.

```curl
curl https://api.stripe.com/v1/account_sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "account={{CONNECTEDACCOUNT_ID}}" \
  -d "components[instant_payouts_promotion][enabled]=true" \
  -d "components[instant_payouts_promotion][features][instant_payouts]=true"
```

## Rendering the component

After creating the account session and [initialising ConnectJS](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#account-sessions), you can render the Instant Payouts promotion component in the front end. This component provides two optional callback handlers so platforms can track connected account usage:

#### JavaScript

```js
const handlePromotionLoaded = ({promotionShown}) => {
  if (promotionShown) {
    // Logic specific to when promotion is shown (for example, track in analytics)
  } else {
    // ...
  }
};

const handleInstantPayoutCreated = ({payoutId}) => {
  console.log('Instant Payout created:', payoutId);
};

const container = document.getElementById('instant-payouts-promotion-container');
const instantPayoutsPromotion = stripeConnectInstance.create('instant-payouts-promotion');

instantPayoutsPromotion.setOnInstantPayoutsPromotionLoaded(handlePromotionLoaded);
instantPayoutsPromotion.setOnInstantPayoutCreated(handleInstantPayoutCreated);

container.appendChild(instantPayoutsPromotion);
```

#### HTML + JS

| Method                               | Type                                  | Description                                                                                                                                   |
| ------------------------------------ | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `setOnInstantPayoutsPromotionLoaded` | `({promotionShown: boolean}) => void` | Called when the promotion loads for the connected account. `promotionShown` indicates whether the promotion is shown to the connected account |
| `setOnInstantPayoutCreated`          | `({payoutId: string}) => void`        | Called when the connected account initiates an Instant Payout in this component. `payoutId` is the ID of the payout created                   |

#### React

| React prop                        | Type                                  | Description                                                                                                                                   |
| --------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `onInstantPayoutsPromotionLoaded` | `({promotionShown: boolean}) => void` | Called when the promotion loads for the connected account. `promotionShown` indicates whether the promotion is shown to the connected account |
| `onInstantPayoutCreated`          | `({payoutId: string}) => void`        | Called when the connected account initiates an Instant Payout in this component. `payoutId` is the ID of the payout created                   |