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

$ straddle payouts get

GET/v1/payouts/{id}

Update a payout

$ straddle payouts update

PUT/v1/payouts/{id}

Create a payout

$ straddle payouts create

POST/v1/payouts

Hold a payout

$ straddle payouts hold

PUT/v1/payouts/{id}/hold

Release a payout

$ straddle payouts release

PUT/v1/payouts/{id}/release

Cancel a payout

$ straddle payouts cancel

PUT/v1/payouts/{id}/cancel

Get a payout by id.

$ straddle payouts unmask

GET/v1/payouts/{id}/unmask

ModelsExpand Collapse

payoutV1: object { data, meta, response_type }

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

id: string

Unique identifier for the payout.

amount: number

The amount of the payout in cents.

config: object { auto_hold, auto_hold_message, sandbox_outcome }

Configuration for the payout.

auto_hold: optional boolean

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

auto_hold_message: optional string

The reason the payout is being automatically held on creation.

sandbox_outcome: optional "standard" or "paid" or "on_hold_daily_limit" or 8 more

Payment will simulate processing if not Standard.

"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: object { 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.

external_id: string

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

funding_ids: array of string

Funding Ids

paykey: string

Value of the paykey used for the payout.

payment_date: string

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.

status: "created" or "scheduled" or "failed" or 6 more

The current status of the payout.

"created"

"scheduled"

"failed"

"cancelled"

"on_hold"

"pending"

"paid"

"reversed"

"validating"

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

Details about the current status of the payout.

changed_at: string

The time the status change occurred.

message: string

A human-readable description of the current status.

reason: "insufficient_funds" or "closed_bank_account" or "invalid_bank_account" or 24 more

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

"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" or "bank_decline" or "customer_dispute" or 2 more

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

"watchtower"

"bank_decline"

"customer_dispute"

"user_action"

"system"

code: optional string

The status code if applicable.

status_history: array of object { changed_at, message, reason, 3 more }

History of the status changes for the payout.

changed_at: string

The time the status change occurred.

message: string

A human-readable description of the status.

reason: "insufficient_funds" or "closed_bank_account" or "invalid_bank_account" or 24 more

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

"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" or "bank_decline" or "customer_dispute" or 2 more

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

"watchtower"

"bank_decline"

"customer_dispute"

"user_action"

"system"

status: "created" or "scheduled" or "failed" or 6 more

The current status of the charge or payout.

"created"

"scheduled"

"failed"

"cancelled"

"on_hold"

"pending"

"paid"

"reversed"

"validating"

code: optional string

The status code if applicable.

trace_ids: map[string]

Trace Ids.

created_at: optional string

The time the payout was created.

customer_details: optional object { id, customer_type, email, 2 more }

Information about the customer associated with the payout.

id: string

Unique identifier for the customer

customer_type: "individual" or "business"

The type of customer

"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: optional string

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

metadata: optional map[string]

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

paykey_details: optional object { id, customer_id, label, balance }

Information about the paykey used for the payout.

id: string

Unique identifier for the paykey.

customer_id: string

Unique identifier for the customer associated with the paykey.

label: string

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

balance: optional number

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

payment_rail: optional "ach"

The payment rail used for the payout.

"ach"

processed_at: optional string

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

related_payments: optional map["original" or "resubmit" or "refund"]

Related payments.

"original"

"resubmit"

"refund"

updated_at: optional string

The time the payout was last updated.

meta: object { 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.

api_request_timestamp: string

Timestamp for this API request, useful for troubleshooting.

response_type: "object" or "array" or "error" or "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.

"object"

"array"

"error"

"none"