# Trace payouts with a unique identifier

## What’s new

Introduces a [trace_id](https://docs.stripe.com/api/payouts/object.md?api-version=2024-11-20.acacia#payout_object-trace_id) field on the [Payout](https://docs.stripe.com/api/payouts.md?api-version=2024-11-20.acacia) resource.

[Trace IDs](https://docs.stripe.com/payouts/trace-id.md) are unique identifiers for payouts that our banking partners create to help you track missing or delayed payouts. If an expected payout hasn’t settled in your bank account after 10 business days, contact your bank for an update and provide the trace ID.

For Connect users, you can provide your connected accounts their payout trace IDs by [retrieving them from the Stripe API](https://docs.stripe.com/api/payouts/retrieve.md?api-version=2024-11-20.acacia).

This enables your connected accounts to self-serve their late or missing payouts without the need for manual support intervention.

The `trace_id` contains two sub-fields: [value](https://docs.stripe.com/api/payouts/object.md?api-version=2024-11-20.acacia#payout_object-trace_id-value) and [status](https://docs.stripe.com/api/payouts/object.md?api-version=2024-11-20.acacia#payout_object-trace_id-status):

- `value`: The trace ID string that we retrieve from our banking partners when a payout is paid.
- `status`: The current status of the trace ID during retrieval from our banking partners.

| Status        | Description                                                                                                                                                               |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pending`     | After you mark a payout as paid, Stripe attempts to retrieve the trace ID from the banking partner for up to 10 days. During this time the `status` becomes `pending`.    |
| `supported`   | After the banking partner provides the trace ID, the `status` becomes `supported` and Stripe updates the `value`.                                                         |
| `unsupported` | Some scenarios prevent providing the trace ID, such as a payout failure or an unsupported country and currency combination. In these cases the `status` is `unsupported`. |

## Impact

You can get the trace ID for a specific payout by [retrieving the payout](https://docs.stripe.com/api/payouts/retrieve.md?api-version=2024-11-20.acacia).

For Connect users, providing the trace ID to your connected accounts allows you to:

- Minimize support requests from your connected accounts relating to late or missing payouts.
- Improve user satisfaction by letting your connected accounts self-serve their late or missing payout investigations with their bank.

## Changes

#### REST API

#### Ruby

This change does not affect the Ruby SDK.

#### Python

#### PHP

#### Java

#### Node.js

#### Go

#### .NET

## Upgrade

#### REST API

1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench.
1. If you use an SDK, upgrade to the corresponding SDK version for this API version.
   - If you don’t use an SDK, update your [API requests](https://docs.stripe.com/api/versioning.md) to include `Stripe-Version: 2024-11-20.acacia`
1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md).
1. [Test your integration](https://docs.stripe.com/testing.md) against the new version.
1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md).
1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours.

Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md).

#### Ruby

1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench.
1. Upgrade your Ruby SDK to [v13.2.0](https://github.com/stripe/stripe-ruby/releases/tag/v13.2.0)
1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md).
1. [Test your integration](https://docs.stripe.com/testing.md) against the new version.
1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md).
1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours.

Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md).

#### Python

1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench.
1. Upgrade your Python SDK to [v11.3.0](https://github.com/stripe/stripe-python/releases/tag/v11.3.0)
1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md).
1. [Test your integration](https://docs.stripe.com/testing.md) against the new version.
1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md).
1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours.

Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md).

#### PHP

1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench.
1. Upgrade your PHP SDK to [v16.3.0](https://github.com/stripe/stripe-php/releases/tag/v16.3.0)
1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md).
1. [Test your integration](https://docs.stripe.com/testing.md) against the new version.
1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md).
1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours.

Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md).

#### Java

1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench.
1. Upgrade your Java SDK to [v28.1.0](https://github.com/stripe/stripe-java/releases/tag/v28.1.0)
1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md).
1. [Test your integration](https://docs.stripe.com/testing.md) against the new version.
1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md).
1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours.

Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md).

#### Node.js

1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench.
1. Upgrade your Node SDK to [v17.4.0](https://github.com/stripe/stripe-node/releases/tag/v17.4.0)
1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md).
1. [Test your integration](https://docs.stripe.com/testing.md) against the new version.
1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md).
1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours.

Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md).

#### Go

1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench.
1. Upgrade your Go SDK to [v81.1.0](https://github.com/stripe/stripe-go/releases/tag/v81.1.0)
1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md).
1. [Test your integration](https://docs.stripe.com/testing.md) against the new version.
1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md).
1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours.

Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md).

#### .NET

1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench.
1. Upgrade your .NET SDK to [v47.1.0](https://github.com/stripe/stripe-dotnet/releases/tag/v47.1.0)
1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md).
1. [Test your integration](https://docs.stripe.com/testing.md) against the new version.
1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md).
1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours.

Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md).