# Payments Show a list of payments with export, refund, and dispute capabilities. > Payments in iOS is in preview. > Payments in Android is in preview. Payments renders a transaction list for [direct charges](https://docs.stripe.com/connect/direct-charges.md), [destination charges](https://docs.stripe.com/connect/destination-charges.md), and [separate charges and transfers](https://docs.stripe.com/connect/separate-charges-and-transfers.md) on the connected account. By default, the embedded components offer limited information for destination charges and separate charges and transfers. They don’t provide access to customer information, payment methods, and some charge amount details. The [destination_on_behalf_of_charge_management](https://docs.stripe.com/connect/supported-embedded-components/payments.md#allow-your-connected-accounts-to-manage-destination-charges) feature allows a connected account to perform refunds, manage disputes, and see additional information for destination charges, including customer information, payment methods, and fees. 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. 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. 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. 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. ## Create an Account Session When you [create an Account Session](https://docs.stripe.com/api/account_sessions/create.md), enable the payments embedded component by specifying `payments` in the `components` parameter. You can turn on or off an individual feature of the payments component by specifying the `features` parameter under `payments`: ```curl curl https://api.stripe.com/v1/account_sessions \ -u "<>:" \ -d account="{{CONNECTEDACCOUNT_ID}}" \ -d "components[payments][enabled]"=true \ -d "components[payments][features][refund_management]"=true \ -d "components[payments][features][dispute_management]"=true \ -d "components[payments][features][capture_payments]"=true \ -d "components[payments][features][destination_on_behalf_of_charge_management]"=false ``` The payments component shows different information and supports different features for different charge types: - For direct charges, your connected accounts can view the complete set of information. They can also manage refunds, manage disputes, and capture payments if you enable the corresponding features when creating an account session. - For [destination charges](https://docs.stripe.com/connect/destination-charges.md) and [separate charges and transfers](https://docs.stripe.com/connect/separate-charges-and-transfers.md), your connected accounts can only see the transfer object associated with the selected charge, which contains limited information. - For destination charges with the [on_behalf_of](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-on_behalf_of) attribute, your connected accounts can view the complete set of information when the `destination_on_behalf_of_charge_management` feature is enabled. When this feature is turned on, you can also enable refund and disputes management by enabling the corresponding features. ### Allow your connected accounts to manage destination charges When you set the `destination_on_behalf_of_charge_management` feature to `true`, your connected accounts can use the payments component to view and manage [destination charges](https://docs.stripe.com/connect/destination-charges.md) that have the [on_behalf_of](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-on_behalf_of) attribute. If you also turn on the `dispute_management` feature, your connected accounts can [participate directly in handling their disputes](https://docs.stripe.com/connect/supported-embedded-components/payments.md#dispute-management-for-destination-charges). Enabling the `destination_on_behalf_of_charge_management` feature has the following limitations: 1. You can’t filter by charge status or payment methods. 1. You can’t export certain data columns. ## Render the payments component After you create the account session and [initialize ConnectJS](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#account-sessions), you can render the payments component in the front end: #### JavaScript ```js // Include this element in your HTML const payments = stripeConnectInstance.create('payments'); container.appendChild(payments); // Optional: specify filters to apply on load // payments.setDefaultFilters({ // amount: {greaterThan: 100}, // date: {before: new Date(2024, 0, 1)}, // status: ['partially_refunded', 'refund_pending', 'refunded'], // paymentMethod: 'card',}); ``` #### HTML + JS | Method | Type | Description | Default | | ------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `setDefaultFilters` | `PaymentsListDefaultFilters` | On load, show the payments matching the filter criteria. See the possible [PaymentsListDefaultFilters properties](https://docs.stripe.com/connect/supported-embedded-components/payments.md#the-object). | none | #### React | React prop | Type | Description | Default | Required or Optional | | ---------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------------------- | | `defaultFilters` | `PaymentsListDefaultFilters` | On load, show the payments matching the filter criteria. See the possible [PaymentsListDefaultFilters properties](https://docs.stripe.com/connect/supported-embedded-components/payments.md#the-object). | none | optional | ### Set default filters Setting default filters for the payments list is optional. If set, it applies any valid filters and ignores invalid filters. If the `destination_on_behalf_of_charge_management` feature is enabled, then you can’t filter by status or payment method so it ignores these filters automatically. You can specify any combination of payment filters of your choice using the `PaymentsListDefaultFilters` object. #### The `PaymentsListDefaultFilters` object To specify default filters, pass a `PaymentsListDefaultFilters` object into the `setDefaultFilters` setter. The object has the following properties, which are all optional: | Name | Type | Description | Example value | | --------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | | `amount` | `{equals: number} | {greaterThan: number} | {lessThan: number} | {between: {lowerBound: number, upperBound: number}}` | Filter by the payment amount (to the nearest hundredth). | `{greaterThan: 100}` | | `date` | `{before: Date} | {after: Date} | {between: {start: Date; end: Date}` | Provide `Date` objects to filter by date. It accepts any date format allowed by a JavaScript `Date` object. Only the year, month, and day are taken into consideration. | `{before: new Date(2024, 0, 1)}` | | `status` | `Status[]` | Provide one or more statuses. The valid status options are: `'blocked' | 'canceled' | 'disputed' | 'early_fraud_warning' | 'failed' | 'incomplete' | 'partially_refunded' | 'pending' | 'refund_pending' | 'refunded' | 'successful' | 'uncaptured'` This filter is ignored if the `destination_on_behalf_of_charge_management` feature is enabled. | `['disputed', 'canceled']` | | `paymentMethod` | `PaymentMethod` | The full list of payment methods is available under the type enum for the [PaymentMethod object](https://docs.stripe.com/api/payment_methods/object.md#payment_method_object-type). To see which payment methods are available to you, check your [payment method settings](https://dashboard.stripe.com/login?redirect=%2Fsettings%2Fpayment_methods%2Fconnected_accounts%3Fconfig_id%3Dpmc_1KldNkAppfGnVJgHI6jpKIek). This filter is ignored if the `destination_on_behalf_of_charge_management` feature is enabled. | `'card'` | ## Render the payments component After you create the account session and set up the [StripeConnect SDK](https://docs.stripe.com/connect/get-started-connect-embedded-components.md?platform=ios#install-the-stripeconnect-sdk), you can render the payments component in your mobile application: #### Swift ```swift // Optional: specify filters to apply on load let defaultFilters = EmbeddedComponentManager.PaymentsListDefaultFiltersOptions() defaultFilters.amount = .greaterThan(10.10) // Show payments > $10.10 defaultFilters.status = [.successful, .pending] // Only successful and pending payments defaultFilters.paymentMethod = .card // Only card payments defaultFilters.date = .between(start: startDate, end: endDate) // Date range // Display this view controller in your app let paymentsViewController = embeddedComponentManager.createPaymentsViewController(defaultFilters: defaultFilters) present(paymentsViewController) ``` | Parameter | Type | Description | Default | | ---------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `defaultFilters` | `PaymentsListDefaultFiltersOptions` | On load, show the payments matching the filter criteria. See the possible [PaymentsListDefaultFiltersOptions properties](https://docs.stripe.com/connect/supported-embedded-components/payments.md#the-object). | none | ### Set default filters Setting default filters for the payments list is optional. If set, it applies any valid filters and ignores invalid filters. If the `destination_on_behalf_of_charge_management` feature is enabled, then you can’t filter by status or payment method so it ignores these filters automatically. You can specify any combination of payment filters of your choice using the `PaymentsListDefaultFiltersOptions` object. ### The `PaymentsListDefaultFiltersOptions` object To specify default filters, create a `PaymentsListDefaultFiltersOptions` object and pass it into the `defaultFilters` parameter. The object has the following properties, which are all optional: | Name | Type | Description | Example value | | --------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | | `amount` | `AmountFilter?` | Filter by the payment amount (to the nearest hundredth). Use enum cases: `.equals(Double)` `.greaterThan(Double)` `.lessThan(Double)` `.between(lowerBound: Double, upperBound: Double)` | `.greaterThan(100.0)` | | `date` | `DateFilter?` | Filter by date using `Date` objects. Use enum cases: `.before(Date)` `.after(Date)` `.between(start: Date, end: Date)` Only the year, month, and day are taken into consideration. | `.before(Date())` | | `status` | `[Status]?` | Provide one or more statuses. The valid status options are: `.blocked` `.canceled` `.disputed` `.earlyFraudWarning` `.failed` `.incomplete` `.partiallyRefunded` `.pending` `.refundPending` `.refunded` `.successful` `.uncaptured` This filter is ignored if the `destination_on_behalf_of_charge_management` feature is enabled. | `[.disputed, .canceled]` | | `paymentMethod` | `PaymentMethod?` | A single payment method from the available enum cases including `.card`, `.applePay`, `.googlePay`, and many others. To see which payment methods are available to you, check your [payment method settings](https://dashboard.stripe.com/login?redirect=%2Fsettings%2Fpayment_methods%2Fconnected_accounts%3Fconfig_id%3Dpmc_1KldNkAppfGnVJgHI6jpKIek). This filter is ignored if the `destination_on_behalf_of_charge_management` feature is enabled. | `.card` | ## Render the payments component After you create the account session and set up the [StripeConnect SDK](https://docs.stripe.com/connect/get-started-connect-embedded-components.md?platform=android#install-the-stripeconnect-sdk), you can render the payments component in your mobile application: #### Kotlin ```kotlin // Optional: specify filters to apply on load val defaultFilters = PaymentsProps.PaymentsListDefaultFilters( amount = PaymentsProps.AmountFilter.greaterThan(10.10), // Show payments > $10.10 status = listOf(PaymentsProps.Status.SUCCESSFUL, PaymentsProps.Status.PENDING), // Only successful and pending payments paymentMethod = PaymentsProps.PaymentMethod.CARD, // Only card payments date = PaymentsProps.DateFilter.between(startDate, endDate) // Date range ) val props = PaymentsProps(defaultFilters = defaultFilters) val paymentsView: View = embeddedComponentManager.createPaymentsView( context = activity, // Use an activity or activity-derived context props = props ) findViewById(R.id.content_view).addView(paymentsView) ``` | Parameter | Type | Description | Default | | ---------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `defaultFilters` | `PaymentsListDefaultFilters` | On load, show the payments matching the filter criteria. See the possible [PaymentsListDefaultFilters properties](https://docs.stripe.com/connect/supported-embedded-components/payments.md#the-object). | null | ### Set default filters Setting default filters for the payments list is optional. If set, it applies any valid filters and ignores invalid filters. If the `destination_on_behalf_of_charge_management` feature is enabled, then you can’t filter by status or payment method so it ignores these filters automatically. You can specify any combination of payment filters of your choice using the `PaymentsProps.PaymentsListDefaultFilters` object. ### The `PaymentsProps.PaymentsListDefaultFilters` object To specify default filters, create a `PaymentsProps.PaymentsListDefaultFilters` object and pass it into the `defaultFilters` parameter of `PaymentsProps`. The object has the following properties, which are all optional: | Name | Type | Description | Example value | | --------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | | `amount` | `AmountFilter?` | Filter by the payment amount (to the nearest hundredth). Use static methods: `AmountFilter.equalTo(Double)` `AmountFilter.greaterThan(Double)` `AmountFilter.lessThan(Double)` `AmountFilter.between(Double, Double)` | `AmountFilter.greaterThan(100.0)` | | `date` | `DateFilter?` | Filter by date using `Date` objects. Use static methods: `DateFilter.before(Date)` `DateFilter.after(Date)` `DateFilter.between(Date, Date)` Only the year, month, and day are taken into consideration. | `DateFilter.before(Date())` | | `status` | `List?` | Provide one or more statuses. The valid status options are: `Status.BLOCKED` `Status.CANCELED` `Status.DISPUTED` `Status.EARLY_FRAUD_WARNING` `Status.FAILED` `Status.INCOMPLETE` `Status.PARTIALLY_REFUNDED` `Status.PENDING` `Status.REFUND_PENDING` `Status.REFUNDED` `Status.SUCCESSFUL` `Status.UNCAPTURED` This filter is ignored if the `destination_on_behalf_of_charge_management` feature is enabled. | `listOf(Status.DISPUTED, Status.CANCELED)` | | `paymentMethod` | `PaymentMethod?` | A single payment method from the available enum cases including `PaymentMethod.CARD`, `PaymentMethod.APPLE_PAY`, `PaymentMethod.GOOGLE_PAY`, and many others. To see which payment methods are available to you, check your [payment method settings](https://dashboard.stripe.com/login?redirect=%2Fsettings%2Fpayment_methods%2Fconnected_accounts%3Fconfig_id%3Dpmc_1KldNkAppfGnVJgHI6jpKIek). This filter is ignored if the `destination_on_behalf_of_charge_management` feature is enabled. | `PaymentMethod.CARD` | ## Render the payments component After you create the Account Session and set up the [Stripe React Native SDK](https://docs.stripe.com/connect/get-started-connect-embedded-components.md?platform=react-native#install-the-stripe-react-native-sdk), you can render the payments component in your application: #### TypeScript ```javascript import { ConnectPayments } from '@stripe/stripe-react-native'; export default function PaymentsScreen() { return ; } ``` ## Request access (Private preview) Sign in to request access to Connect embedded components for React Native in private preview. If you don’t have a Stripe account, you can [register now](https://dashboard.stripe.com/register). ## Dispute management for destination charges When you enable both `dispute_management` and `destination_on_behalf_of_charge_management`, your connected accounts can update and modify dispute evidence, counter disputes, and accept disputes for destination charges with the `on_behalf_of` attribute set to the connected account. For [destination charges](https://docs.stripe.com/connect/destination-charges.md), with or without `on_behalf_of`, Stripe debits dispute amounts and fees from your platform account. We recommend setting up [a webhook](https://docs.stripe.com/webhooks.md) to listen to [dispute created events](https://docs.stripe.com/api/events/types.md#event_types-charge.dispute.created). When that happens, you can attempt to recover funds from the connected account by reversing the transfer through the [Dashboard](https://dashboard.stripe.com/test/transfers) or by [creating a transfer reversal](https://docs.stripe.com/api/transfer_reversals/create.md). If the connected account has a negative balance, Stripe attempts to [debit its external account](https://docs.stripe.com/connect/account-balances.md#automatically-debit-connected-accounts) if `debit_negative_balances` is set to `true`. If you challenge the dispute and win, you can transfer the funds that you previously reversed back to the connected account. If your platform has an insufficient balance, the transfer fails. Prevent insufficient balance errors by [adding funds to your Stripe balance](https://docs.stripe.com/get-started/account/add-funds.md). > Retransferring a previous reversal is subject to [cross-border transfer restrictions](https://docs.stripe.com/connect/account-capabilities.md#transfers-cross-border), meaning you might have no means to repay your connected account. Instead, wait to recover disputed cross-border payment transfers for destination charges with `on_behalf_of` until after a dispute is lost. ## Customize the description If you’re using the [destination_on_behalf_of_charge_management](https://docs.stripe.com/connect/supported-embedded-components/payments.md#allow-your-connected-accounts-to-manage-destination-charges) option, the payment information (including the description) shown for destination charges with the `on_behalf_of` attribute corresponds to the original created payment. To display a custom description within the payment detail view for [destination charges](https://docs.stripe.com/connect/destination-charges.md) and [separate charges and transfers](https://docs.stripe.com/connect/separate-charges-and-transfers.md) when this feature is off, follow these steps: ### Destination charges To update the [description](https://docs.stripe.com/api/charges/object.md#charge_object-description) on a payment object that’s visible to your platform’s users, you need to use the Stripe API. This applies to all platforms that use [destination charges](https://docs.stripe.com/connect/destination-charges.md). 1. Find the existing transfer object you created for an account by finding the latest [charge](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges) created on the [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md). 1. Use the charge object to find the [transfer](https://docs.stripe.com/api/charges/object.md#charge_object-transfer) object associated with the charge. 1. Use the transfer object to find the [destination_payment](https://docs.stripe.com/api/transfers/object.md#transfer_object-destination_payment) ID that exists on the transfer. 1. Call the [Update Charge](https://docs.stripe.com/api/charges/update.md) API to update the [description](https://docs.stripe.com/api/charges/update.md#update_charge-description) on the destination payment using the `destination_payment` ID. > The [destination_payment](https://docs.stripe.com/api/transfers/object.md#transfer_object-destination_payment) object belongs to the connected account, so you’ll need to set [the Stripe-Account header](https://docs.stripe.com/connect/authentication.md) to the connected account’s ID to make this call. ```curl curl https://api.stripe.com/v1/charges/{{PAYMENT_ID}} \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d description="My custom description" ``` This description becomes visible on the charge after you’ve written this field. Learn more about [creating destination charges on your platform](https://docs.stripe.com/connect/destination-charges.md). ### Separate charges and transfers To update the [description](https://docs.stripe.com/api/charges/object.md#charge_object-description) on a payment object that’s visible to your platform’s users, you need to use the Stripe API. This applies to platforms that use [separate charges and transfers](https://docs.stripe.com/connect/separate-charges-and-transfers.md). 1. Use the transfer object to find the [destination_payment](https://docs.stripe.com/api/transfers/object.md#transfer_object-destination_payment) ID that exists on the transfer. 1. Call the [Update Charge](https://docs.stripe.com/api/charges/update.md) API to update the [description](https://docs.stripe.com/api/charges/update.md#update_charge-description) on the destination payment using the `destination_payment` ID found in the previous step. > The [destination_payment](https://docs.stripe.com/api/transfers/object.md#transfer_object-destination_payment) object belongs to the connected account, so you’ll need to set [the Stripe-Account header](https://docs.stripe.com/connect/authentication.md) to the connected account’s ID to make this call. ```curl curl https://api.stripe.com/v1/charges/{{PAYMENT_ID}} \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d description="My custom description" ``` This description becomes visible on the charge after you’ve written this field. Learn more about [creating separate charges and transfers](https://docs.stripe.com/connect/separate-charges-and-transfers.md).