Adds destination payment description and metadata support to transfer data
What’s new
You can now specify a description and metadata for destination payments when creating transfers through the transfer_data parameter on PaymentIntent and Charge objects. The payment_data hash allows you to set these properties specifically for the destination payment, separate from the transfer itself.
Previously, you could set description and metadata on the transfer, but not on the destination payment created as part of the transfer process. This enhancement uses Stripe’s standard _data pattern for subordinate object creation and maintains full backward compatibility with existing integrations.
Impact
You can provide more detailed information about destination payments to help with reconciliation and customer support. This is particularly useful for platforms that need to pass through payment descriptions from the original PaymentIntent to the destination account, or attach custom metadata to track payment-specific information at the destination level.
To use this feature, include the payment_data hash in your transfer_data parameter when creating PaymentIntents. The description can be up to 5,000 characters, and metadata follows Stripe’s standard key-value pair format with values up to 500 characters each.
Changes
| Parameters | Change | Resources or endpoints |
|---|---|---|
| description | Added | Charge#create. transfer_data PaymentIntent#create. transfer_data PaymentIntent#update. transfer_data + 1 more PaymentIntent. transfer_data |
| metadata payment_data | Added | PaymentIntent#create. transfer_data PaymentIntent#update. transfer_data PaymentIntent. transfer_data |
Upgrade
- View your current API version in Workbench.
- 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 to include Stripe-Version: 2026-05-27. dahlia
- Upgrade the API version used for webhook endpoints .
- Test your integration against the new version.
- If you use Connect, test your Connect integration .
- In Workbench, perform the upgrade . You can roll back the version for 72 hours.
Learn more about Stripe API upgrades.