Striped

View Source Stripe.Payout (Striped v0.5.0) (generated)

A Payout object is created when you receive funds from Stripe, or when you initiate a payout to either a bank account or debit card of a connected Stripe account. You can retrieve individual payouts, as well as list all payouts. Payouts are made on varying schedules, depending on your country and industry.

Related guide: Receiving Payouts.

Link to this section Summary

Types

arrival_date()
created()
t()

The payout type.

Functions

cancel(client, payout, params \\ %{}, opts \\ [])

A previously created payout can be canceled if it has not yet been paid out. Funds will be refunded to your available balance. You may not cancel automatic Stripe payouts.

create(client, params \\ %{}, opts \\ [])

To send funds to your own bank account, you create a new payout object. Your Stripe balance must be able to cover the payout amount, or you’ll receive an “Insufficient Funds” error.

list(client, params \\ %{}, opts \\ [])

Returns a list of existing payouts sent to third-party bank accounts or that Stripe has sent you. The payouts are returned in sorted order, with the most recently created payouts appearing first.

retrieve(client, payout, params \\ %{}, opts \\ [])

Retrieves the details of an existing payout. Supply the unique payout ID from either a payout creation request or the payout list, and Stripe will return the corresponding payout information.

reverse(client, payout, params \\ %{}, opts \\ [])

Reverses a payout by debiting the destination bank account. Only payouts for connected accounts to US bank accounts may be reversed at this time. If the payout is in the pending status, /v1/payouts/:id/cancel should be used instead.

update(client, payout, params \\ %{}, opts \\ [])

Updates the specified payout by setting the values of the parameters passed. Any parameters not provided will be left unchanged. This request accepts only the metadata as arguments.

Link to this section Types

Link to this type

arrival_date()

View Source 
@type arrival_date() :: %{
  optional(:gt) => integer(),
  optional(:gte) => integer(),
  optional(:lt) => integer(),
  optional(:lte) => integer()
}
Link to this type

created()

View Source 
@type created() :: %{
  optional(:gt) => integer(),
  optional(:gte) => integer(),
  optional(:lt) => integer(),
  optional(:lte) => integer()
}
Link to this type

t()

View Source 
@type t() :: %Stripe.Payout{
  amount: integer(),
  arrival_date: integer(),
  automatic: boolean(),
  balance_transaction: (binary() | Stripe.BalanceTransaction.t()) | nil,
  created: integer(),
  currency: binary(),
  description: binary() | nil,
  destination:
    (binary() | Stripe.ExternalAccount.t() | Stripe.DeletedExternalAccount.t())
    | nil,
  failure_balance_transaction: (binary() | Stripe.BalanceTransaction.t()) | nil,
  failure_code: binary() | nil,
  failure_message: binary() | nil,
  id: binary(),
  livemode: boolean(),
  metadata: term() | nil,
  method: binary(),
  object: binary(),
  original_payout: (binary() | t()) | nil,
  reversed_by: (binary() | t()) | nil,
  source_type: binary(),
  statement_descriptor: binary() | nil,
  status: binary(),
  type: binary()
}

The payout type.

  • amount Amount (in %s) to be transferred to your bank account or debit card.
  • arrival_date Date the payout is expected to arrive in the bank. This factors in delays like weekends or bank holidays.
  • automatic Returns true if the payout was created by an automated payout schedule, and false if it was requested manually.
  • balance_transaction ID of the balance transaction that describes the impact of this payout on your account balance.
  • created Time at which the object was created. Measured in seconds since the Unix epoch.
  • currency Three-letter ISO currency code, in lowercase. Must be a supported currency.
  • description An arbitrary string attached to the object. Often useful for displaying to users.
  • destination ID of the bank account or card the payout was sent to.
  • failure_balance_transaction If the payout failed or was canceled, this will be the ID of the balance transaction that reversed the initial balance transaction, and puts the funds from the failed payout back in your balance.
  • failure_code Error code explaining reason for payout failure if available. See Types of payout failures for a list of failure codes.
  • failure_message Message to user further explaining reason for payout failure if available.
  • id Unique identifier for the object.
  • livemode Has the value true if the object exists in live mode or the value false if the object exists in test mode.
  • metadata 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.
  • method The method used to send this payout, which can be standard or instant. instant is only supported for payouts to debit cards. (See Instant payouts for marketplaces for more information.)
  • object String representing the object's type. Objects of the same type share the same value.
  • original_payout If the payout reverses another, this is the ID of the original payout.
  • reversed_by If the payout was reversed, this is the ID of the payout that reverses this payout.
  • source_type The source balance this payout came from. One of card, fpx, or bank_account.
  • statement_descriptor Extra information about a payout to be displayed on the user's bank statement.
  • status Current status of the payout: paid, pending, in_transit, canceled or failed. A payout is pending until it is submitted to the bank, when it becomes in_transit. The status then changes to paid if the transaction goes through, or to failed or canceled (within 5 business days). Some failed payouts may initially show as paid but then change to failed.
  • type Can be bank_account or card.

Link to this section Functions

Link to this function

cancel(client, payout, params \\ %{}, opts \\ [])

View Source 
@spec cancel(
  client :: Stripe.t(),
  payout :: binary(),
  params :: %{optional(:expand) => [binary()]},
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

A previously created payout can be canceled if it has not yet been paid out. Funds will be refunded to your available balance. You may not cancel automatic Stripe payouts.

Details

  • Method: post
  • Path: /v1/payouts/{payout}/cancel
Link to this function

create(client, params \\ %{}, opts \\ [])

View Source 
@spec create(
  client :: Stripe.t(),
  params :: %{
    optional(:amount) => integer(),
    optional(:currency) => binary(),
    optional(:description) => binary(),
    optional(:destination) => binary(),
    optional(:expand) => [binary()],
    optional(:metadata) => %{optional(binary()) => binary()},
    optional(:method) => :instant | :standard,
    optional(:source_type) => :bank_account | :card | :fpx,
    optional(:statement_descriptor) => binary()
  },
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

To send funds to your own bank account, you create a new payout object. Your Stripe balance must be able to cover the payout amount, or you’ll receive an “Insufficient Funds” error.

If your API key is in test mode, money won’t actually be sent, though everything else will occur as if in live mode.

If you are creating a manual payout on a Stripe account that uses multiple payment source types, you’ll need to specify the source type balance that the payout should draw from. The balance object details available and pending amounts by source type.

Details

  • Method: post
  • Path: /v1/payouts
Link to this function

list(client, params \\ %{}, opts \\ [])

View Source 
@spec list(
  client :: Stripe.t(),
  params :: %{
    optional(:arrival_date) => arrival_date() | integer(),
    optional(:created) => created() | integer(),
    optional(:destination) => binary(),
    optional(:ending_before) => binary(),
    optional(:expand) => [binary()],
    optional(:limit) => integer(),
    optional(:starting_after) => binary(),
    optional(:status) => binary()
  },
  opts :: Keyword.t()
) ::
  {:ok, Stripe.List.t(t())} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Returns a list of existing payouts sent to third-party bank accounts or that Stripe has sent you. The payouts are returned in sorted order, with the most recently created payouts appearing first.

Details

  • Method: get
  • Path: /v1/payouts
Link to this function

retrieve(client, payout, params \\ %{}, opts \\ [])

View Source 
@spec retrieve(
  client :: Stripe.t(),
  payout :: binary(),
  params :: %{optional(:expand) => [binary()]},
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Retrieves the details of an existing payout. Supply the unique payout ID from either a payout creation request or the payout list, and Stripe will return the corresponding payout information.

Details

  • Method: get
  • Path: /v1/payouts/{payout}
Link to this function

reverse(client, payout, params \\ %{}, opts \\ [])

View Source 
@spec reverse(
  client :: Stripe.t(),
  payout :: binary(),
  params :: %{
    optional(:expand) => [binary()],
    optional(:metadata) => %{optional(binary()) => binary()}
  },
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Reverses a payout by debiting the destination bank account. Only payouts for connected accounts to US bank accounts may be reversed at this time. If the payout is in the pending status, /v1/payouts/:id/cancel should be used instead.

By requesting a reversal via /v1/payouts/:id/reverse, you confirm that the authorized signatory of the selected bank account has authorized the debit on the bank account and that no other authorization is required.

Details

  • Method: post
  • Path: /v1/payouts/{payout}/reverse
Link to this function

update(client, payout, params \\ %{}, opts \\ [])

View Source 
@spec update(
  client :: Stripe.t(),
  payout :: binary(),
  params :: %{
    optional(:expand) => [binary()],
    optional(:metadata) => %{optional(binary()) => binary()} | binary()
  },
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Updates the specified payout by setting the values of the parameters passed. Any parameters not provided will be left unchanged. This request accepts only the metadata as arguments.

Details

  • Method: post
  • Path: /v1/payouts/{payout}