Payouts

Payouts represent transfers from Straddle to customer bank accounts. Create payouts to handle disbursements, process refunds, or manage marketplace settlements. Use payouts to send money quickly and securely with the most cost-effective rail automatically selected.

Lookup a payout

payouts.get(id, **kwargs) -> PayoutV1 { data, meta, response_type }

GET/v1/payouts/{id}

Update a payout

payouts.update(id, **kwargs) -> PayoutV1 { data, meta, response_type }

PUT/v1/payouts/{id}

Create a payout

payouts.create(**kwargs) -> PayoutV1 { data, meta, response_type }

POST/v1/payouts

Hold a payout

payouts.hold(id, **kwargs) -> PayoutV1 { data, meta, response_type }

PUT/v1/payouts/{id}/hold

Release a payout

payouts.release(id, **kwargs) -> PayoutV1 { data, meta, response_type }

PUT/v1/payouts/{id}/release

Cancel a payout

payouts.cancel(id, **kwargs) -> PayoutV1 { data, meta, response_type }

PUT/v1/payouts/{id}/cancel

Get a payout by id.

payouts.unmask(id, **kwargs) -> PayoutUnmaskResponse { data, meta, response_type }

GET/v1/payouts/{id}/unmask

ModelsExpand Collapse

class PayoutV1 { data, meta, response_type }

data: { id, amount, config, 20 more}

id: String

Unique identifier for the payout.

formatuuid

amount: Integer

The amount of the payout in cents.

formatint32

config: { auto_hold, auto_hold_message, sandbox_outcome}

Configuration for the payout.

auto_hold: bool

Defines whether to automatically place this charge on hold after being created.

auto_hold_message: String

The reason the payout is being automatically held on creation.

sandbox_outcome: :standard | :paid | :on_hold_daily_limit | 8 more

Payment will simulate processing if not Standard.

One of the following:

:standard

:paid

:on_hold_daily_limit

:cancelled_for_fraud_risk

:cancelled_for_balance_check

:failed_insufficient_funds

:reversed_insufficient_funds

:failed_customer_dispute

:reversed_customer_dispute

:failed_closed_bank_account

:reversed_closed_bank_account

currency: String

The currency of the payout. Only USD is supported.

description: String

An arbitrary description for the payout.

device: DeviceInfoV1 { ip_address }

Information about the device used when the customer authorized the payout.

ip_address: String

The IP address of the device used when the customer authorized the charge or payout. Use 0.0.0.0 to represent an offline consent interaction.

formatipv4

external_id: String

Unique identifier for the payout in your database. This value must be unique across all payouts.

funding_ids: Array[String]

Funding Ids

paykey: String

Value of the paykey used for the payout.

payment_date: Date

The desired date on which the payment should be occur. For payouts, this means the date you want the funds to be sent from your bank account.

formatdate

status: :created | :scheduled | :failed | 6 more

The current status of the payout.

One of the following:

:created

:scheduled

:failed

:cancelled

:on_hold

:pending

:paid

:reversed

:validating

status_details: StatusDetailsV1 { changed_at, message, reason, 2 more }

Details about the current status of the payout.

changed_at: Time

The time the status change occurred.

formatdate-time

message: String

A human-readable description of the current status.

reason: :insufficient_funds | :closed_bank_account | :invalid_bank_account | 24 more

A machine-readable identifier for the specific status, useful for programmatic handling.

One of the following:

:insufficient_funds

:closed_bank_account

:invalid_bank_account

:invalid_routing

:disputed

:payment_stopped

:owner_deceased

:frozen_bank_account

:risk_review

:fraudulent

:duplicate_entry

:invalid_paykey

:payment_blocked

:amount_too_large

:too_many_attempts

:internal_system_error

:user_request

:ok

:other_network_return

:payout_refused

:cancel_request

:failed_verification

:require_review

:blocked_by_system

:watchtower_review

:validating

:auto_hold

source: :watchtower | :bank_decline | :customer_dispute | 2 more

Identifies the origin of the status change (e.g., bank_decline, watchtower). This helps in tracking the cause of status updates.

One of the following:

:watchtower

:bank_decline

:customer_dispute

:user_action

:system

code: String

The status code if applicable.

status_history: Array[{ changed_at, message, reason, 3 more}]

History of the status changes for the payout.

changed_at: Time

The time the status change occurred.

formatdate-time

message: String

A human-readable description of the status.

reason: :insufficient_funds | :closed_bank_account | :invalid_bank_account | 24 more

A machine-readable identifier for the specific status, useful for programmatic handling.

One of the following:

:insufficient_funds

:closed_bank_account

:invalid_bank_account

:invalid_routing

:disputed

:payment_stopped

:owner_deceased

:frozen_bank_account

:risk_review

:fraudulent

:duplicate_entry

:invalid_paykey

:payment_blocked

:amount_too_large

:too_many_attempts

:internal_system_error

:user_request

:ok

:other_network_return

:payout_refused

:cancel_request

:failed_verification

:require_review

:blocked_by_system

:watchtower_review

:validating

:auto_hold

source: :watchtower | :bank_decline | :customer_dispute | 2 more

Identifies the origin of the status change (e.g., bank_decline, watchtower). This helps in tracking the cause of status updates.

One of the following:

:watchtower

:bank_decline

:customer_dispute

:user_action

:system

status: :created | :scheduled | :failed | 6 more

The current status of the charge or payout.

One of the following:

:created

:scheduled

:failed

:cancelled

:on_hold

:pending

:paid

:reversed

:validating

code: String

The status code if applicable.

trace_ids: Hash[Symbol, String]

Trace Ids.

created_at: Time

The time the payout was created.

formatdate-time

customer_details: CustomerDetailsV1 { id, customer_type, email, 2 more }

Information about the customer associated with the payout.

id: String

Unique identifier for the customer

formatuuid

customer_type: :individual | :business

The type of customer

One of the following:

:individual

:business

email: String

The customer's email address

name: String

The name of the customer

phone: String

The customer's phone number in E.164 format

effective_at: Time

The actual date on which the payment occurred. For payouts, this is the date the funds were sent from your bank account.

formatdate-time

metadata: Hash[Symbol, String]

Up to 20 additional user-defined key-value pairs. Useful for storing additional information about the payout in a structured format.

paykey_details: PaykeyDetailsV1 { id, customer_id, label, balance }

Information about the paykey used for the payout.

id: String

Unique identifier for the paykey.

formatuuid

customer_id: String

Unique identifier for the customer associated with the paykey.

formatuuid

label: String

Human-readable label that combines the bank name and masked account number to help easility represent this paykey in a UI

balance: Integer

The most recent balance of the bank account associated with the paykey in dollars.

formatint32

payment_rail: :ach

The payment rail used for the payout.

processed_at: Time

The time the payout was processed by Straddle and originated to the payment rail.

formatdate-time

related_payments: Hash[Symbol, :original | :resubmit | :refund]

Related payments.

One of the following:

:original

:resubmit

:refund

updated_at: Time

The time the payout was last updated.

formatdate-time

meta: ResponseMetadata { api_request_id, api_request_timestamp }

Metadata about the API request, including an identifier and timestamp.

api_request_id: String

Unique identifier for this API request, useful for troubleshooting.

formatuuid

api_request_timestamp: Time

Timestamp for this API request, useful for troubleshooting.

formatdate-time

response_type: :object | :array | :error | :none

Indicates the structure of the returned content.

"object" means the data field contains a single JSON object.
"array" means the data field contains an array of objects.
"error" means the data field contains an error object with details of the issue.
"none" means no data is returned.

One of the following:

:object

:array

:error

:none

class PayoutUnmaskResponse { data, meta, response_type }

data: { id, amount, config, 20 more}

id: String

Id.

formatuuid

amount: Integer

Amount.

formatint32

config: { auto_hold, auto_hold_message, sandbox_outcome}

auto_hold: bool

Defines whether to automatically place this charge on hold after being created.

auto_hold_message: String

The reason the payout is being automatically held on creation.

sandbox_outcome: :standard | :paid | :on_hold_daily_limit | 8 more

Payment will simulate processing if not Standard.

One of the following:

:standard

:paid

:on_hold_daily_limit

:cancelled_for_fraud_risk

:cancelled_for_balance_check

:failed_insufficient_funds

:reversed_insufficient_funds

:failed_customer_dispute

:reversed_customer_dispute

:failed_closed_bank_account

:reversed_closed_bank_account

currency: String

Currency.

description: String

Description.

device: { ip_address}

ip_address: String

Ip address.

format**.**.**.**

external_id: String

External id.

funding_ids: Array[String]

Funding Ids

paykey: String

Paykey.

payment_date: Date

Payment date.

formatdate

status: :created | :scheduled | :failed | 6 more

The current status of the charge or payout.

One of the following:

:created

:scheduled

:failed

:cancelled

:on_hold

:pending

:paid

:reversed

:validating

status_details: StatusDetailsV1 { changed_at, message, reason, 2 more }

changed_at: Time

The time the status change occurred.

formatdate-time

message: String

A human-readable description of the current status.

reason: :insufficient_funds | :closed_bank_account | :invalid_bank_account | 24 more

A machine-readable identifier for the specific status, useful for programmatic handling.

One of the following:

:insufficient_funds

:closed_bank_account

:invalid_bank_account

:invalid_routing

:disputed

:payment_stopped

:owner_deceased

:frozen_bank_account

:risk_review

:fraudulent

:duplicate_entry

:invalid_paykey

:payment_blocked

:amount_too_large

:too_many_attempts

:internal_system_error

:user_request

:ok

:other_network_return

:payout_refused

:cancel_request

:failed_verification

:require_review

:blocked_by_system

:watchtower_review

:validating

:auto_hold

source: :watchtower | :bank_decline | :customer_dispute | 2 more

Identifies the origin of the status change (e.g., bank_decline, watchtower). This helps in tracking the cause of status updates.

One of the following:

:watchtower

:bank_decline

:customer_dispute

:user_action

:system

code: String

The status code if applicable.

status_history: Array[{ changed_at, message, reason, 3 more}]

Status history.

changed_at: Time

The time the status change occurred.

formatdate-time

message: String

A human-readable description of the status.

reason: :insufficient_funds | :closed_bank_account | :invalid_bank_account | 24 more

A machine-readable identifier for the specific status, useful for programmatic handling.

One of the following:

:insufficient_funds

:closed_bank_account

:invalid_bank_account

:invalid_routing

:disputed

:payment_stopped

:owner_deceased

:frozen_bank_account

:risk_review

:fraudulent

:duplicate_entry

:invalid_paykey

:payment_blocked

:amount_too_large

:too_many_attempts

:internal_system_error

:user_request

:ok

:other_network_return

:payout_refused

:cancel_request

:failed_verification

:require_review

:blocked_by_system

:watchtower_review

:validating

:auto_hold

source: :watchtower | :bank_decline | :customer_dispute | 2 more

Identifies the origin of the status change (e.g., bank_decline, watchtower). This helps in tracking the cause of status updates.

One of the following:

:watchtower

:bank_decline

:customer_dispute

:user_action

:system

status: :created | :scheduled | :failed | 6 more

The current status of the charge or payout.

One of the following:

:created

:scheduled

:failed

:cancelled

:on_hold

:pending

:paid

:reversed

:validating

code: String

The status code if applicable.

trace_ids: Hash[Symbol, String]

Trace Ids.

created_at: Time

Created at.

formatdate-time

customer_details: CustomerDetailsV1 { id, customer_type, email, 2 more }

Information about the customer associated with the charge or payout.

id: String

Unique identifier for the customer

formatuuid

customer_type: :individual | :business

The type of customer

One of the following:

:individual

:business

email: String

The customer's email address

name: String

The name of the customer

phone: String

The customer's phone number in E.164 format

effective_at: Time

Effective at.

formatdate-time

metadata: Hash[Symbol, String]

Metadata.

paykey_details: PaykeyDetailsV1 { id, customer_id, label, balance }

id: String

Unique identifier for the paykey.

formatuuid

customer_id: String

Unique identifier for the customer associated with the paykey.

formatuuid

label: String

Human-readable label that combines the bank name and masked account number to help easility represent this paykey in a UI

balance: Integer

The most recent balance of the bank account associated with the paykey in dollars.

formatint32

payment_rail: :ach

The payment rail used for the charge or payout.

processed_at: Time

Processed at.

formatdate-time

related_payments: Hash[Symbol, :original | :resubmit | :refund]

Related payments.

One of the following:

:original

:resubmit

:refund

updated_at: Time

Updated at.

formatdate-time

meta: ResponseMetadata { api_request_id, api_request_timestamp }

Metadata about the API request, including an identifier and timestamp.

api_request_id: String

Unique identifier for this API request, useful for troubleshooting.

formatuuid

api_request_timestamp: Time

Timestamp for this API request, useful for troubleshooting.

formatdate-time

response_type: :object | :array | :error | :none

Indicates the structure of the returned content.

"object" means the data field contains a single JSON object.
"array" means the data field contains an array of objects.
"error" means the data field contains an error object with details of the issue.
"none" means no data is returned.

One of the following:

:object

:array

:error

:none