Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Revenue
Platforms and marketplaces
Money management
Developer resources
Overview
Get started with Connect
Integration fundamentals
Example integrations
Account management
Onboard accounts
Configure account Dashboards
    Get started with Connect embedded components
    Customize Connect embedded components
    Supported Connect embedded components
      Onboarding and compliance
      Account management
      Account onboarding
      Notification banner
      Payment management
      Payments
      Payment details
      Disputes for a payment
      Disputes list
      Payment method settings
      Payout management
      Payouts
      Payouts list
      Payout details
      Balances
      Instant payouts promotion
      Capital
      Capital components
      Tax
      Tax registrations
      Tax settings
      Export tax transactions
      Tax threshold monitoring
      Product tax code selector
      Treasury and issuing
      Financial account
      Financial account transactions
      Issuing card
      Issuing cards list
      Reporting
      Documents
      Reporting chart
      Apps
      App install
      App viewport
    Stripe Dashboard customization
    Platform controls for Stripe Dashboard accounts
    Express Dashboard
Work with connected account types
Payment processing
Accept payments
Pay out to accounts
Platform administration
Manage your Connect platform
Tax forms for your Connect platform
HomePlatforms and marketplacesConfigure account DashboardsSupported Connect embedded components

Payments

Show a list of payments with export, refund, and dispute capabilities.

Public preview

Payments in iOS is in preview.

Payments renders a transaction list for direct charges, destination charges, and separate charges and transfers 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 feature allows a connected account to see additional information with destination charges, as well as perform refunds and manage disputes.

Create an Account Session

When you create an Account Session, 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:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/account_sessions \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d account=
{{CONNECTED_ACCOUNT_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 and separate charges and transfers, 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 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 that have the on_behalf_of attribute. If you also turn on the dispute_management feature, your connected accounts can participate directly in handling their disputes.

Enabling the destination_on_behalf_of_charge_management feature has the following limitations:

  1. You can’t filter by charge status or payment methods.
  2. You can’t export certain data columns.

Render the payments component

After you create the account session and set up the StripeConnect SDK, you can render the payments component in your mobile application:

payments.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)
ParameterTypeDescriptionDefault
defaultFiltersPaymentsListDefaultFiltersOptionsOn load, show the payments matching the filter criteria. See the possible PaymentsListDefaultFiltersOptions properties.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:

NameTypeDescriptionExample 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.

This filter is ignored if the destination_on_behalf_of_charge_management feature is enabled.

.card

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, with or without on_behalf_of, Stripe debits dispute amounts and fees from your platform account.

We recommend setting up a webhook to listen to dispute created events. When that happens, you can attempt to recover funds from the connected account by reversing the transfer through the Dashboard or by creating a transfer reversal.

If the connected account has a negative balance, Stripe attempts to debit its external account 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.

Common mistake

Retransferring a previous reversal is subject to cross-border transfer restrictions, 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 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 and separate charges and transfers when this feature is off, follow these steps:

Destination charges

To update the 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.

  1. Find the existing transfer object you created for an account by finding the latest charge created on the PaymentIntent.
  2. Use the charge object to find the transfer object associated with the charge.
  3. Use the transfer object to find the destination_payment ID that exists on the transfer.
  4. Call the Update Charge API to update the description on the destination payment using the destination_payment ID.

Note

The destination_payment object belongs to the connected account, so you’ll need to set the Stripe-Account header to the connected account’s ID to make this call.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/charges/
{{PAYMENT_ID}}
\ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -H "Stripe-Account:
{{CONNECTED_ACCOUNT_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.

Separate charges and transfers

To update the 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.

  1. Use the transfer object to find the destination_payment ID that exists on the transfer.
  2. Call the Update Charge API to update the description on the destination payment using the destination_payment ID found in the previous step.

Note

The destination_payment object belongs to the connected account, so you’ll need to set the Stripe-Account header to the connected account’s ID to make this call.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/charges/
{{PAYMENT_ID}}
\ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -H "Stripe-Account:
{{CONNECTED_ACCOUNT_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.

Was this page helpful?
YesNo
  • Need help? Contact Support.
  • Join our early access program.
  • Check out our changelog.
  • Questions? Contact Sales.
  • LLM? Read llms.txt.
  • Powered by Markdoc