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_
- this only applies to payouts.account card
- this only applies to payouts.failure_
- this only applies to payouts.message failure_
- this only applies to payouts.code 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_
- application_fee is no longer necessary. See Connect destination charges.fee
- 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_
- this only applies to legacy transfers.fee destination_
- this only applies to transfers.payment source_
- this only applies to legacy transfers.transaction 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_
, simply omit thefor_ currency destination
entirely. - Canceling a payout is now done via
POST /v1/payouts/:id/cancel
. The balance transaction resulting from a cancellation is available via thecancellation_
field on the payout. Thebalance_ transaction status
of a canceled payout iscanceled
. - When creating a transfer, you can now only use a charge as the
source_
. Previously, it was possible to use any transaction (such as an application fee, or an adjustment) as atransaction source_
. 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.transaction - Payouts now generate these events:
payout.
,created payout.
,failed payout.
,reversed payout.
,paid payout.
, which are the equivalent of the legacyupdated transfer.
events.* - Transfers no longer generate these events:
transfer.
andpaid transfer.
.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 the deprecated Recipients API 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.