Skip to content
straddle API Docs
Get started
API Reference

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(strid, PayoutGetParams**kwargs) -> PayoutV1
GET/v1/payouts/{id}
Update a payout
payouts.update(strid, PayoutUpdateParams**kwargs) -> PayoutV1
PUT/v1/payouts/{id}
Create a payout
payouts.create(PayoutCreateParams**kwargs) -> PayoutV1
POST/v1/payouts
Hold a payout
payouts.hold(strid, PayoutHoldParams**kwargs) -> PayoutV1
PUT/v1/payouts/{id}/hold
Release a payout
payouts.release(strid, PayoutReleaseParams**kwargs) -> PayoutV1
PUT/v1/payouts/{id}/release
Cancel a payout
payouts.cancel(strid, PayoutCancelParams**kwargs) -> PayoutV1
PUT/v1/payouts/{id}/cancel
Get a payout by id.
payouts.unmask(strid, PayoutUnmaskParams**kwargs) -> PayoutUnmaskResponse
GET/v1/payouts/{id}/unmask
ModelsExpand Collapse
class PayoutV1: …
data: Data
id: str

Unique identifier for the payout.

formatuuid
amount: int

The amount of the payout in cents.

formatint32
config: DataConfig

Configuration for the payout.

auto_hold: Optional[bool]

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

auto_hold_message: Optional[str]

The reason the payout is being automatically held on creation.

sandbox_outcome: Optional[Literal["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: str

The currency of the payout. Only USD is supported.

description: Optional[str]

An arbitrary description for the payout.

device: DeviceInfoV1

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

ip_address: str

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: str

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

funding_ids: List[str]

Funding Ids

paykey: str

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: Literal["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

Details about the current status of the payout.

changed_at: datetime

The time the status change occurred.

formatdate-time
message: str

A human-readable description of the current status.

reason: Literal["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: Literal["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: Optional[str]

The status code if applicable.

status_history: List[DataStatusHistory]

History of the status changes for the payout.

changed_at: datetime

The time the status change occurred.

formatdate-time
message: str

A human-readable description of the status.

reason: Literal["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: Literal["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: Literal["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: Optional[str]

The status code if applicable.

trace_ids: Dict[str, str]

Trace Ids.

created_at: Optional[datetime]

The time the payout was created.

formatdate-time
customer_details: Optional[CustomerDetailsV1]

Information about the customer associated with the payout.

id: str

Unique identifier for the customer

formatuuid
customer_type: Literal["individual", "business"]

The type of customer

One of the following:
"individual"
"business"
email: str

The customer's email address

name: str

The name of the customer

phone: str

The customer's phone number in E.164 format

effective_at: Optional[datetime]

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: Optional[Dict[str, str]]

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

paykey_details: Optional[PaykeyDetailsV1]

Information about the paykey used for the payout.

id: str

Unique identifier for the paykey.

formatuuid
customer_id: str

Unique identifier for the customer associated with the paykey.

formatuuid
label: str

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

balance: Optional[int]

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

formatint32
payment_rail: Optional[Literal["ach"]]

The payment rail used for the payout.

processed_at: Optional[datetime]

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

formatdate-time

Related payments.

One of the following:
updated_at: Optional[datetime]

The time the payout was last updated.

formatdate-time

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

api_request_id: str

Unique identifier for this API request, useful for troubleshooting.

formatuuid
api_request_timestamp: datetime

Timestamp for this API request, useful for troubleshooting.

formatdate-time
response_type: Literal["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: Data
id: str

Id.

formatuuid
amount: int

Amount.

formatint32
config: DataConfig
auto_hold: Optional[bool]

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

auto_hold_message: Optional[str]

The reason the payout is being automatically held on creation.

sandbox_outcome: Optional[Literal["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: str

Currency.

description: Optional[str]

Description.

device: DataDevice
ip_address: str

Ip address.

format**.**.**.**
external_id: str

External id.

funding_ids: List[str]

Funding Ids

paykey: str

Paykey.

payment_date: date

Payment date.

formatdate
status: Literal["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: datetime

The time the status change occurred.

formatdate-time
message: str

A human-readable description of the current status.

reason: Literal["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: Literal["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: Optional[str]

The status code if applicable.

status_history: List[DataStatusHistory]

Status history.

changed_at: datetime

The time the status change occurred.

formatdate-time
message: str

A human-readable description of the status.

reason: Literal["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: Literal["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: Literal["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: Optional[str]

The status code if applicable.

trace_ids: Dict[str, str]

Trace Ids.

created_at: Optional[datetime]

Created at.

formatdate-time
customer_details: Optional[CustomerDetailsV1]

Information about the customer associated with the charge or payout.

id: str

Unique identifier for the customer

formatuuid
customer_type: Literal["individual", "business"]

The type of customer

One of the following:
"individual"
"business"
email: str

The customer's email address

name: str

The name of the customer

phone: str

The customer's phone number in E.164 format

effective_at: Optional[datetime]

Effective at.

formatdate-time
metadata: Optional[Dict[str, str]]

Metadata.

paykey_details: Optional[PaykeyDetailsV1]
id: str

Unique identifier for the paykey.

formatuuid
customer_id: str

Unique identifier for the customer associated with the paykey.

formatuuid
label: str

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

balance: Optional[int]

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

formatint32
payment_rail: Optional[Literal["ach"]]

The payment rail used for the charge or payout.

processed_at: Optional[datetime]

Processed at.

formatdate-time

Related payments.

One of the following:
updated_at: Optional[datetime]

Updated at.

formatdate-time

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

api_request_id: str

Unique identifier for this API request, useful for troubleshooting.

formatuuid
api_request_timestamp: datetime

Timestamp for this API request, useful for troubleshooting.

formatdate-time
response_type: Literal["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"