Public preview
Manage payouts Public preview
Learn how to monitor payout statuses and reports.
After you create a payout, you can view its status, receive events when the status changes, cancel or reverse the payout, investigate returned payouts or a missing trace ID, and view reporting.
Use API keys
You must use restricted API keys to make live requests to the Global Payouts APIs. For a standard integration, create a restricted key with the following permissions:
- Recipient Configuration: Write
- Money Management Financial Accounts: Read
- Money Management Payout Methods: Write
- Money Management Outbound Payments: Write
Grant additional permissions for these scenarios:
- For UK Confirmation of Payee or the related setting/Eurozone payments that require Recipient Verifications, grant Money Management Recipient Verifications: Write .
- If you use the gated Payout Intents API path, grant Money Management Payout Intents: Write .
Monitor payouts
View payout status
You can view a payout’s status in the Dashboard or with the API by inspecting its status.
- In the Stripe Dashboard, go to Global Payouts .
- Use the filter buttons to sort payouts by processing , posted , failed , returned , canceled , or scheduled .
You can also view an itemized receipt that includes details of the payout.
Payout statuses
PayoutIntent statuses Private preview
The following table describes the possible statuses for a PayoutIntent.
| Status | Description |
|---|---|
| processing | The starting state of the payout. Funds allocate to a pending transaction and remain part of the current outbound_pending balance. If the cancelable parameter is set to true, you can cancel the payout. |
| requires_action | The payout requires user action before it can proceed. Review next_action.handle_failure.failure_reason to understand the issue and take corrective action. Update the payout using the Payout Intents API after resolving the issue. |
| posted | The payout posts and funds leave the FinancialAccount. A posted status doesn’t guarantee that your recipient has received money, because their bank might delay the release of funds. If a payout is posted but the recipient hasn’t received money, instruct them to wait several business days or to inquire with their bank. |
| canceled | The payout was canceled before it posted. Stripe voids the pending transaction and returns the funds to you. |
OutboundPayment statuses
The following table describes the possible statuses for an OutboundPayment.
| Status | Description |
|---|---|
| scheduled | The payout is scheduled to be sent on a specific date. This payout’s status changes to processing on its scheduled send date. Scheduled payouts are only available in the Dashboard. |
| processing | The starting state of the payout. Funds allocate to a pending transaction and remain part of the current outbound_pending balance. If the cancelable parameter is set to true, you can cancel the payout. |
| failed | The payout failed. Stripe voids the pending transaction and returns the funds to you. |
| canceled | The payout was canceled before it posted. Stripe voids the pending transaction and returns the funds to you. |
| posted | The payout posts and funds leave the FinancialAccount. A posted status doesn’t guarantee that your recipient has received money, because their bank might delay the release of funds. If a payout is posted but the recipient hasn’t received money, instruct them to wait several business days or to inquire with their bank. |
| returned | The payout failed to arrive at the destination. Stripe returns the funds to you in a separate transaction ( returned_details[transaction]). To see the return reason, on the Global Payouts page, click the payout in the list view and see the return reason listed in the Timeline section. You can also view return reasons in OutboundPayments. Payouts are typically returned within 2-3 business days, but might take longer depending on the recipient country. |
View changes in payout state
You can view changes in payout state in the Dashboard or by receiving events to your webhook endpoint.
- In the Dashboard, go to Global Payouts .
- Find the payout that you want to inspect, and select it.
- View the Timeline section to see a record of state changes.
View payout trace ID
If a payout has status posted but the recipient hasn’t received the payout, you can provide the trace ID to the recipient. The recipient can provide the trace ID to the bank to investigate the specific status of the payout.
- In the Stripe Dashboard, go to the Global Payouts page.
- Select the payout that you want to inspect.
- View the Trace ID section. If the trace ID exists, you can click the ID to copy it.
View reports and transactions
You can use the Dashboard and API to view your account balance and reports, view transactions to and from the balance, and withdraw funds.
Navigate to Payouts and click Export to export a CSV file of historical payout information. You can select your preferred time zone, date range, and desired columns. You can also download reports from Balances. Fees can take up to 96 hours and other activity up to 24 hours to appear in these reports.
You can also view a summary of payouts activity in Reports. Click Financial account balance summary and download the Balance summary or the Balance change from activity. You can select your preferred time zone, date range, and desired columns.
Private preview
Sigma or Stripe Data Pipeline reporting with Global Payouts is in private preview. If you’re interested in getting access, enter your email.
Manage payouts
Cancel or reverse a payout
If you unintentionally send a payout, you might be able to cancel the payout if it hasn’t been initiated. You can do this using the Dashboard or API.
If the payout posts, you can still request a reversal by emailing Stripe Support if your payout method supports it. Stripe makes an attempt to reverse the payout and return the funds to your account. Stripe can’t guarantee a reversal, and some payout methods aren’t reversible.
| Payout type | Reversal support |
|---|---|
| US domestic payouts (local bank transfer) | You must request a reversal within 24 hours of creating the payout. |
| US domestic payouts (wire) | You must request a reversal within 24 hours of creating the payout. |
| UK domestic payouts (local bank transfer) | No |
| Cross-border payouts | No |
Manage returned payouts
Incorrect destination information causes most returned payouts (for example, the provided bank account is closed, or the account holder’s details don’t match the recipient’s information). If a payout has been returned:
- Read the failure or return reason. You can view it in the Dashboard by selecting the payout in the list view and reading through the Timeline section. You can also view return reasons in OutboundPayments, or view failure details in the PayoutIntent’s next _ action. handle _ failure. failure _ reason field (private preview).
- If the payout failed or returned because of incorrect destination information, confirm the details and ask the recipient to update their information if needed. Then, send a new payout to their updated destination.
- If the payout failed or returned for an unknown reason, confirm the details and ask the recipient to update their information if needed. Then, try sending the money again. If the payout still fails, contact Stripe Support .
Configure payout settings
Set default payout methods (Optional)
You can choose the payout method for each payout, or set a global default method that applies across all recipients. Unlike per-recipient payout methods, default preferences apply to newly created payouts and newly created recipients. To set a default payout method:
- Go to Settings , then click Global Payouts .
- Enable at least one payout method.
- Click Done .
You can override these settings with the API or in the Dashboard.
Set your communication preference (Optional)
Global communication preferences determine how Stripe can communicate on your behalf with recipients. You can override these settings with the API or in the Dashboard.
To set default communication preferences for all recipients:
- Go to Settings , then click Global Payouts .
- In Recipient communication permissions , choose whether you want Stripe to email recipients on your behalf or if you plan to handle communications with recipients yourself.