Transfer Payout Split: Stripe-Version 2017-04-06
On April 6, 2017, Stripe split the /v1/transfers
resource into /v1/transfers
and /v1/payouts
. This is a versioned change–your existing integrations don’t need to change.
Since Stripe was launched, we’ve used the word transfer to mean moving money out of Stripe and into your bank account or debit card. But when Connect was launched years later, we co-opted that term to also mean moving money between a platform and its connected accounts.
This ultimately turned out to be confusing. These are conceptually different flows of funds as they apply to a business. This made it difficult to document transfers, and also bloated the /v1/transfers
API because the fields needed to support each flow of funds were different.
As of Stripe-Version 2017-04-06
:
- Payouts will mean moving money from Stripe to your bank account or debit card and will be represented by
/v1/payouts
. - Transfers will mean moving money between Stripe accounts as part of Connect and will be represented by
/v1/transfers
. - Relative to the legacy
/v1/transfers
resource, the new/v1/transfers
resource won’t have these fields:method
- this only applies to payouts.status
- this only applies to payouts.type
- this only applies to payouts.bank_account
- this only applies to payouts.card
- this only applies to payouts.failure_message
- this only applies to payouts.failure_code
- this only applies to payouts.description
- description was confusing because it applied to the transfer but not the resultant payment on the connected account. Usemetadata
to attach additional information to a transfer.application_fee
- application_fee is no longer necessary. See Connect destination charges.
- Relative to the legacy
/v1/transfers
, the new/v1/payouts
resource won’t have these fields:reversals
- payouts can now be simply canceled.reversed
- refer to the payout status.application_fee
- this only applies to legacy transfers.destination_payment
- this only applies to transfers.source_transaction
- this only applies to legacy transfers.description
- description was removed because it didn’t provide enough value. Use metadata to attach additional information to a payout.
- On the
/v1/payouts
resource, thedate
field was renamed toarrival_date
. - To send a payout to your default bank account or debit card, instead of including the parameter
destination=default_for_currency
, simply omit thedestination
entirely. - Canceling a payout is now done via
POST /v1/payouts/:id/cancel
. The balance transaction resulting from a cancellation is available via thecancellation_balance_transaction
field on the payout. Thestatus
of a canceled payout iscanceled
. - When creating a transfer, you can now only use a charge as the
source_transaction
. Previously, it was possible to use any transaction (such as an application fee, or an adjustment) as asource_transaction
. This did not mesh well with the intended use case of tagging outgoing transfers with the incoming source of funds, so this is no longer supported on the new API version. - Payouts now generate these events:
payout.created
,payout.failed
,payout.reversed
,payout.paid
,payout.updated
, which are the equivalent of the legacytransfer.*
events. - Transfers no longer generate these events:
transfer.paid
andtransfer.failed
. - Balance transactions can have these types as they relate to payouts:
type
∈ {payout
,payout_failure
,payout_cancel
} - Balance transactions can have these types as they relate to transfers:
type
∈ {transfer
,transfer_refund
} - Fields on the Account API were renamed:
transfers_enabled
→payouts_enabled
transfer_schedule
→payout_schedule
transfer_statement_descriptor
→payout_statement_descriptor
- Transfers to deprecated Recipients API (link) are no longer represented on this version of the API. Use a legacy API version to access any transfers to recipients that you may have.