Create a payout

Changed on

To send funds to your own bank account, create a new payout object. Your Stripe balance must cover the payout amount. If it doesn’t, you receive an “Insufficient Funds” error.

If your API key is in test mode, money won’t actually be sent, though every other action occurs as if you’re in live mode.

If you create a manual payout on a Stripe account that uses multiple payment source types, you need to specify the source type balance that the payout draws from. The balance object details available and pending amounts by source type.

post/v1/payouts

Request

  • Base URL: https://api.stripe.com
  • URL: https://api.stripe.com/v1/payouts
  • Auth: one of:
    • HTTP basic
    • HTTP bearer

Request body application/x-www-form-urlencoded

amountinteger required

A positive integer in cents representing how much to pay out.

currencystring currency required

Three-letter ISO currency code, in lowercase. Must be a supported currency.

descriptionstring

An arbitrary string attached to the object. Often useful for displaying to users.

destinationstring

The ID of a bank account or a card to send the payout to. If you don't provide a destination, we use the default external account for the specified currency.

expandstring[]

Specifies which fields in the response should be expanded.

metadataobject

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

method'instant' | 'standard'

The method used to send this payout, which is standard or instant. We support instant for payouts to debit cards and bank accounts in certain countries. Learn more about bank support for Instant Payouts.

payout_methodstring

The ID of a v2 FinancialAccount to send funds to.

source_type'bank_account' | 'card' | 'fpx'

The balance type of your Stripe balance to draw this payout from. Balances for different payment sources are kept separately. You can find the amounts with the Balances API. One of bank_account, card, or fpx.

statement_descriptorstring

A string that displays on the recipient's bank or card statement (up to 22 characters). A statement_descriptor that's longer than 22 characters return an error. Most banks truncate this information and display it inconsistently. Some banks might not display it at all. For US ACH payouts, this maps to the ACH Company Entry Description field, which the NACHA standard limits to 10 characters. Stripe truncates descriptors longer than 10 characters for US ACH payouts.

Response

Successful response.

amountinteger required

The amount (in cents (or local equivalent)) that transfers to your bank account or debit card.

application_fee_amountinteger nullable

The amount of the application fee (if any) requested for the payout. See the Connect documentation for details.

arrival_dateinteger required

Date that you can expect the payout to arrive in the bank. This factors in delays to account for weekends or bank holidays.

automaticboolean required

Returns true if the payout is created by an automated payout schedule and false if it's requested manually.

createdinteger required

Time at which the object was created. Measured in seconds since the Unix epoch.

currencystring currency required

Three-letter ISO currency code, in lowercase. Must be a supported currency.

descriptionstring nullable

An arbitrary string attached to the object. Often useful for displaying to users.

failure_codestring nullable

Error code that provides a reason for a payout failure, if available. View our list of failure codes.

failure_messagestring nullable

Message that provides the reason for a payout failure, if available.

idstring required

Unique identifier for the object.

livemodeboolean required

If the object exists in live mode, the value is true. If the object exists in test mode, the value is false.

metadataobject nullable

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

methodstring required

The method used to send this payout, which can be standard or instant. instant is supported for payouts to debit cards and bank accounts in certain countries. Learn more about bank support for Instant Payouts.

object'payout' required

String representing the object's type. Objects of the same type share the same value.

payout_methodstring nullable

ID of the v2 FinancialAccount the funds are sent to.

reconciliation_status'completed' | 'in_progress' | 'not_applicable' required

If completed, you can use the Balance Transactions API to list all balance transactions that are paid out in this payout.

source_typestring required

The source balance this payout came from, which can be one of the following: card, fpx, or bank_account.

statement_descriptorstring nullable

Extra information about a payout that displays on the user's bank statement.

statusstring required

Current status of the payout: paid, pending, in_transit, canceled or failed. A payout is pending until it's submitted to the bank, when it becomes in_transit. The status changes to paid if the transaction succeeds, or to failed or canceled (within 5 business days). Some payouts that fail might initially show as paid, then change to failed.

type'bank_account' | 'card' required

Can be bank_account or card.

Changes

  • c113b1939b8fRevision changes
    • info

      added the optional property ////// to the response with the status

  • 7b8f614372caRevision changes
    • info

      added the optional property ////////// to the response with the status

Some revisions have not been checked yet.