API Reference

Payouts

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Create a payout

client.Payouts.New(ctx, params) (*PayoutV1, error)

POST/v1/payouts

Use payouts to send money to your customers.

ParametersExpand Collapse

params PayoutNewParams

Amount param.Field[int64]

Body param: The amount of the payout in cents.

formatint32

Currency param.Field[string]

Body param: The currency of the payout. Only USD is supported.

Description param.Field[string]

Body param: An arbitrary description for the payout.

Device param.Field[DeviceInfoV1]

Body param: Information about the device used when the customer authorized the payout.

ExternalID param.Field[string]

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

Paykey param.Field[string]

Body param: Value of the paykey used for the payout.

PaymentDate param.Field[Time]

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

formatdate

Config param.Field[PayoutNewParamsConfig]optional

Body param

AutoHold booloptional

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

AutoHoldMessage stringoptional

The reason the payout is being automatically held on creation.

SandboxOutcome stringoptional

Payment will simulate processing if not Standard.

One of the following:

const PayoutNewParamsConfigSandboxOutcomeStandard PayoutNewParamsConfigSandboxOutcome = "standard"

const PayoutNewParamsConfigSandboxOutcomePaid PayoutNewParamsConfigSandboxOutcome = "paid"

const PayoutNewParamsConfigSandboxOutcomeOnHoldDailyLimit PayoutNewParamsConfigSandboxOutcome = "on_hold_daily_limit"

const PayoutNewParamsConfigSandboxOutcomeCancelledForFraudRisk PayoutNewParamsConfigSandboxOutcome = "cancelled_for_fraud_risk"

const PayoutNewParamsConfigSandboxOutcomeCancelledForBalanceCheck PayoutNewParamsConfigSandboxOutcome = "cancelled_for_balance_check"

const PayoutNewParamsConfigSandboxOutcomeFailedInsufficientFunds PayoutNewParamsConfigSandboxOutcome = "failed_insufficient_funds"

const PayoutNewParamsConfigSandboxOutcomeReversedInsufficientFunds PayoutNewParamsConfigSandboxOutcome = "reversed_insufficient_funds"

const PayoutNewParamsConfigSandboxOutcomeFailedCustomerDispute PayoutNewParamsConfigSandboxOutcome = "failed_customer_dispute"

const PayoutNewParamsConfigSandboxOutcomeReversedCustomerDispute PayoutNewParamsConfigSandboxOutcome = "reversed_customer_dispute"

const PayoutNewParamsConfigSandboxOutcomeFailedClosedBankAccount PayoutNewParamsConfigSandboxOutcome = "failed_closed_bank_account"

const PayoutNewParamsConfigSandboxOutcomeReversedClosedBankAccount PayoutNewParamsConfigSandboxOutcome = "reversed_closed_bank_account"

Metadata param.Field[map[string, string]]optional

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

CorrelationID param.Field[string]optional

Header param: Optional client generated identifier to trace and debug a series of requests.

IdempotencyKey param.Field[string]optional

Header param: Optional client generated value to use for idempotent requests.

maxLength40

minLength10

RequestID param.Field[string]optional

Header param: Optional client generated identifier to trace and debug a request.

StraddleAccountID param.Field[string]optional

Header param: For use by platforms to specify an account id and set scope of a request.

formatuuid

ReturnsExpand Collapse

type PayoutV1 struct{…}

Data PayoutV1Data

ID string

Unique identifier for the payout.

formatuuid

Amount int64

The amount of the payout in cents.

formatint32

Config PayoutV1DataConfig

Configuration for the payout.

AutoHold booloptional

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

AutoHoldMessage stringoptional

The reason the payout is being automatically held on creation.

SandboxOutcome stringoptional

Payment will simulate processing if not Standard.

One of the following:

const PayoutV1DataConfigSandboxOutcomeStandard PayoutV1DataConfigSandboxOutcome = "standard"

const PayoutV1DataConfigSandboxOutcomePaid PayoutV1DataConfigSandboxOutcome = "paid"

const PayoutV1DataConfigSandboxOutcomeOnHoldDailyLimit PayoutV1DataConfigSandboxOutcome = "on_hold_daily_limit"

const PayoutV1DataConfigSandboxOutcomeCancelledForFraudRisk PayoutV1DataConfigSandboxOutcome = "cancelled_for_fraud_risk"

const PayoutV1DataConfigSandboxOutcomeCancelledForBalanceCheck PayoutV1DataConfigSandboxOutcome = "cancelled_for_balance_check"

const PayoutV1DataConfigSandboxOutcomeFailedInsufficientFunds PayoutV1DataConfigSandboxOutcome = "failed_insufficient_funds"

const PayoutV1DataConfigSandboxOutcomeReversedInsufficientFunds PayoutV1DataConfigSandboxOutcome = "reversed_insufficient_funds"

const PayoutV1DataConfigSandboxOutcomeFailedCustomerDispute PayoutV1DataConfigSandboxOutcome = "failed_customer_dispute"

const PayoutV1DataConfigSandboxOutcomeReversedCustomerDispute PayoutV1DataConfigSandboxOutcome = "reversed_customer_dispute"

const PayoutV1DataConfigSandboxOutcomeFailedClosedBankAccount PayoutV1DataConfigSandboxOutcome = "failed_closed_bank_account"

const PayoutV1DataConfigSandboxOutcomeReversedClosedBankAccount PayoutV1DataConfigSandboxOutcome = "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

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

IPAddress 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

ExternalID string

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

FundingIDs []string

Funding Ids

Paykey string

Value of the paykey used for the payout.

PaymentDate Time

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 string

The current status of the payout.

One of the following:

const PayoutV1DataStatusCreated PayoutV1DataStatus = "created"

const PayoutV1DataStatusScheduled PayoutV1DataStatus = "scheduled"

const PayoutV1DataStatusFailed PayoutV1DataStatus = "failed"

const PayoutV1DataStatusCancelled PayoutV1DataStatus = "cancelled"

const PayoutV1DataStatusOnHold PayoutV1DataStatus = "on_hold"

const PayoutV1DataStatusPending PayoutV1DataStatus = "pending"

const PayoutV1DataStatusPaid PayoutV1DataStatus = "paid"

const PayoutV1DataStatusReversed PayoutV1DataStatus = "reversed"

const PayoutV1DataStatusValidating PayoutV1DataStatus = "validating"

StatusDetails StatusDetailsV1

Details about the current status of the payout.

ChangedAt Time

The time the status change occurred.

formatdate-time

Message string

A human-readable description of the current status.

Reason StatusDetailsV1Reason

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

One of the following:

const StatusDetailsV1ReasonInsufficientFunds StatusDetailsV1Reason = "insufficient_funds"

const StatusDetailsV1ReasonClosedBankAccount StatusDetailsV1Reason = "closed_bank_account"

const StatusDetailsV1ReasonInvalidBankAccount StatusDetailsV1Reason = "invalid_bank_account"

const StatusDetailsV1ReasonInvalidRouting StatusDetailsV1Reason = "invalid_routing"

const StatusDetailsV1ReasonDisputed StatusDetailsV1Reason = "disputed"

const StatusDetailsV1ReasonPaymentStopped StatusDetailsV1Reason = "payment_stopped"

const StatusDetailsV1ReasonOwnerDeceased StatusDetailsV1Reason = "owner_deceased"

const StatusDetailsV1ReasonFrozenBankAccount StatusDetailsV1Reason = "frozen_bank_account"

const StatusDetailsV1ReasonRiskReview StatusDetailsV1Reason = "risk_review"

const StatusDetailsV1ReasonFraudulent StatusDetailsV1Reason = "fraudulent"

const StatusDetailsV1ReasonDuplicateEntry StatusDetailsV1Reason = "duplicate_entry"

const StatusDetailsV1ReasonInvalidPaykey StatusDetailsV1Reason = "invalid_paykey"

const StatusDetailsV1ReasonPaymentBlocked StatusDetailsV1Reason = "payment_blocked"

const StatusDetailsV1ReasonAmountTooLarge StatusDetailsV1Reason = "amount_too_large"

const StatusDetailsV1ReasonTooManyAttempts StatusDetailsV1Reason = "too_many_attempts"

const StatusDetailsV1ReasonInternalSystemError StatusDetailsV1Reason = "internal_system_error"

const StatusDetailsV1ReasonUserRequest StatusDetailsV1Reason = "user_request"

const StatusDetailsV1ReasonOk StatusDetailsV1Reason = "ok"

const StatusDetailsV1ReasonOtherNetworkReturn StatusDetailsV1Reason = "other_network_return"

const StatusDetailsV1ReasonPayoutRefused StatusDetailsV1Reason = "payout_refused"

const StatusDetailsV1ReasonCancelRequest StatusDetailsV1Reason = "cancel_request"

const StatusDetailsV1ReasonFailedVerification StatusDetailsV1Reason = "failed_verification"

const StatusDetailsV1ReasonRequireReview StatusDetailsV1Reason = "require_review"

const StatusDetailsV1ReasonBlockedBySystem StatusDetailsV1Reason = "blocked_by_system"

const StatusDetailsV1ReasonWatchtowerReview StatusDetailsV1Reason = "watchtower_review"

const StatusDetailsV1ReasonValidating StatusDetailsV1Reason = "validating"

const StatusDetailsV1ReasonAutoHold StatusDetailsV1Reason = "auto_hold"

Source StatusDetailsV1Source

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:

const StatusDetailsV1SourceWatchtower StatusDetailsV1Source = "watchtower"

const StatusDetailsV1SourceBankDecline StatusDetailsV1Source = "bank_decline"

const StatusDetailsV1SourceCustomerDispute StatusDetailsV1Source = "customer_dispute"

const StatusDetailsV1SourceUserAction StatusDetailsV1Source = "user_action"

const StatusDetailsV1SourceSystem StatusDetailsV1Source = "system"

Code stringoptional

The status code if applicable.

StatusHistory []PayoutV1DataStatusHistory

History of the status changes for the payout.

ChangedAt Time

The time the status change occurred.

formatdate-time

Message string

A human-readable description of the status.

Reason string

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

One of the following:

const PayoutV1DataStatusHistoryReasonInsufficientFunds PayoutV1DataStatusHistoryReason = "insufficient_funds"

const PayoutV1DataStatusHistoryReasonClosedBankAccount PayoutV1DataStatusHistoryReason = "closed_bank_account"

const PayoutV1DataStatusHistoryReasonInvalidBankAccount PayoutV1DataStatusHistoryReason = "invalid_bank_account"

const PayoutV1DataStatusHistoryReasonInvalidRouting PayoutV1DataStatusHistoryReason = "invalid_routing"

const PayoutV1DataStatusHistoryReasonDisputed PayoutV1DataStatusHistoryReason = "disputed"

const PayoutV1DataStatusHistoryReasonPaymentStopped PayoutV1DataStatusHistoryReason = "payment_stopped"

const PayoutV1DataStatusHistoryReasonOwnerDeceased PayoutV1DataStatusHistoryReason = "owner_deceased"

const PayoutV1DataStatusHistoryReasonFrozenBankAccount PayoutV1DataStatusHistoryReason = "frozen_bank_account"

const PayoutV1DataStatusHistoryReasonRiskReview PayoutV1DataStatusHistoryReason = "risk_review"

const PayoutV1DataStatusHistoryReasonFraudulent PayoutV1DataStatusHistoryReason = "fraudulent"

const PayoutV1DataStatusHistoryReasonDuplicateEntry PayoutV1DataStatusHistoryReason = "duplicate_entry"

const PayoutV1DataStatusHistoryReasonInvalidPaykey PayoutV1DataStatusHistoryReason = "invalid_paykey"

const PayoutV1DataStatusHistoryReasonPaymentBlocked PayoutV1DataStatusHistoryReason = "payment_blocked"

const PayoutV1DataStatusHistoryReasonAmountTooLarge PayoutV1DataStatusHistoryReason = "amount_too_large"

const PayoutV1DataStatusHistoryReasonTooManyAttempts PayoutV1DataStatusHistoryReason = "too_many_attempts"

const PayoutV1DataStatusHistoryReasonInternalSystemError PayoutV1DataStatusHistoryReason = "internal_system_error"

const PayoutV1DataStatusHistoryReasonUserRequest PayoutV1DataStatusHistoryReason = "user_request"

const PayoutV1DataStatusHistoryReasonOk PayoutV1DataStatusHistoryReason = "ok"

const PayoutV1DataStatusHistoryReasonOtherNetworkReturn PayoutV1DataStatusHistoryReason = "other_network_return"

const PayoutV1DataStatusHistoryReasonPayoutRefused PayoutV1DataStatusHistoryReason = "payout_refused"

const PayoutV1DataStatusHistoryReasonCancelRequest PayoutV1DataStatusHistoryReason = "cancel_request"

const PayoutV1DataStatusHistoryReasonFailedVerification PayoutV1DataStatusHistoryReason = "failed_verification"

const PayoutV1DataStatusHistoryReasonRequireReview PayoutV1DataStatusHistoryReason = "require_review"

const PayoutV1DataStatusHistoryReasonBlockedBySystem PayoutV1DataStatusHistoryReason = "blocked_by_system"

const PayoutV1DataStatusHistoryReasonWatchtowerReview PayoutV1DataStatusHistoryReason = "watchtower_review"

const PayoutV1DataStatusHistoryReasonValidating PayoutV1DataStatusHistoryReason = "validating"

const PayoutV1DataStatusHistoryReasonAutoHold PayoutV1DataStatusHistoryReason = "auto_hold"

Source string

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:

const PayoutV1DataStatusHistorySourceWatchtower PayoutV1DataStatusHistorySource = "watchtower"

const PayoutV1DataStatusHistorySourceBankDecline PayoutV1DataStatusHistorySource = "bank_decline"

const PayoutV1DataStatusHistorySourceCustomerDispute PayoutV1DataStatusHistorySource = "customer_dispute"

const PayoutV1DataStatusHistorySourceUserAction PayoutV1DataStatusHistorySource = "user_action"

const PayoutV1DataStatusHistorySourceSystem PayoutV1DataStatusHistorySource = "system"

Status string

The current status of the charge or payout.

One of the following:

const PayoutV1DataStatusHistoryStatusCreated PayoutV1DataStatusHistoryStatus = "created"

const PayoutV1DataStatusHistoryStatusScheduled PayoutV1DataStatusHistoryStatus = "scheduled"

const PayoutV1DataStatusHistoryStatusFailed PayoutV1DataStatusHistoryStatus = "failed"

const PayoutV1DataStatusHistoryStatusCancelled PayoutV1DataStatusHistoryStatus = "cancelled"

const PayoutV1DataStatusHistoryStatusOnHold PayoutV1DataStatusHistoryStatus = "on_hold"

const PayoutV1DataStatusHistoryStatusPending PayoutV1DataStatusHistoryStatus = "pending"

const PayoutV1DataStatusHistoryStatusPaid PayoutV1DataStatusHistoryStatus = "paid"

const PayoutV1DataStatusHistoryStatusReversed PayoutV1DataStatusHistoryStatus = "reversed"

const PayoutV1DataStatusHistoryStatusValidating PayoutV1DataStatusHistoryStatus = "validating"

Code stringoptional

The status code if applicable.

TraceIDs map[string, string]

Trace Ids.

CreatedAt Timeoptional

The time the payout was created.

formatdate-time

CustomerDetails CustomerDetailsV1optional

Information about the customer associated with the payout.

ID string

Unique identifier for the customer

formatuuid

CustomerType CustomerDetailsV1CustomerType

The type of customer

One of the following:

const CustomerDetailsV1CustomerTypeIndividual CustomerDetailsV1CustomerType = "individual"

const CustomerDetailsV1CustomerTypeBusiness CustomerDetailsV1CustomerType = "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

EffectiveAt Timeoptional

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 map[string, string]optional

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

PaykeyDetails PaykeyDetailsV1optional

Information about the paykey used for the payout.

ID string

Unique identifier for the paykey.

formatuuid

CustomerID 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 int64optional

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

formatint32

PaymentRail stringoptional

The payment rail used for the payout.

ProcessedAt Timeoptional

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

formatdate-time

RelatedPayments map[string, string]optional

Related payments.

One of the following:

const PayoutV1DataRelatedPaymentOriginal PayoutV1DataRelatedPayment = "original"

const PayoutV1DataRelatedPaymentResubmit PayoutV1DataRelatedPayment = "resubmit"

const PayoutV1DataRelatedPaymentRefund PayoutV1DataRelatedPayment = "refund"

UpdatedAt Timeoptional

The time the payout was last updated.

formatdate-time

Meta ResponseMetadata

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

APIRequestID string

Unique identifier for this API request, useful for troubleshooting.

formatuuid

APIRequestTimestamp Time

Timestamp for this API request, useful for troubleshooting.

formatdate-time

ResponseType PayoutV1ResponseType

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:

const PayoutV1ResponseTypeObject PayoutV1ResponseType = "object"

const PayoutV1ResponseTypeArray PayoutV1ResponseType = "array"

const PayoutV1ResponseTypeError PayoutV1ResponseType = "error"

const PayoutV1ResponseTypeNone PayoutV1ResponseType = "none"

Create a payout

Go

HTTP

TypeScript

Python

Go

Ruby

CLI Tool

C#

package main

import (
  "context"
  "fmt"
  "time"

  "github.com/straddleio/straddle-go"
  "github.com/straddleio/straddle-go/option"
  "github.com/straddleio/straddle-go/shared"
)

func main() {
  client := straddle.NewClient(
    option.WithAPIKey("My API Key"),
  )
  payoutV1, err := client.Payouts.New(context.TODO(), straddle.PayoutNewParams{
    Amount: 10000,
    Currency: "currency",
    Description: straddle.String("Vendor invoice payment"),
    Device: shared.DeviceInfoV1Param{
      IPAddress: "192.168.1.1",
    },
    ExternalID: "external_id",
    Paykey: "paykey",
    PaymentDate: time.Now(),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", payoutV1.Data)
}

200 example

{
  "data": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "amount": 10000,
    "config": {
      "auto_hold": true,
      "auto_hold_message": "auto_hold_message",
      "sandbox_outcome": "standard"
    },
    "currency": "currency",
    "description": "description",
    "device": {
      "ip_address": "192.168.1.1"
    },
    "external_id": "external_id",
    "funding_ids": [
      "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
    ],
    "paykey": "paykey",
    "payment_date": "2019-12-27",
    "status": "created",
    "status_details": {
      "changed_at": "2019-12-27T18:11:19.117Z",
      "message": "Payment successfully created and awaiting validation.",
      "reason": "insufficient_funds",
      "source": "system",
      "code": null
    },
    "status_history": [
      {
        "changed_at": "2019-12-27T18:11:19.117Z",
        "message": "Payment successfully created and awaiting validation.",
        "reason": "insufficient_funds",
        "source": "watchtower",
        "status": "created",
        "code": null
      }
    ],
    "trace_ids": {
      "foo": "string"
    },
    "created_at": "2019-12-27T18:11:19.117Z",
    "customer_details": {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "customer_type": "individual",
      "email": "ron@swanson.com",
      "name": "Ron Swanson",
      "phone": "+1234567890"
    },
    "effective_at": "2019-12-27T18:11:19.117Z",
    "metadata": {
      "foo": "string"
    },
    "paykey_details": {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "customer_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "label": "Bank of America ****1234",
      "balance": 0
    },
    "payment_rail": "ach",
    "processed_at": "2019-12-27T18:11:19.117Z",
    "related_payments": {
      "foo": "original"
    },
    "updated_at": "2019-12-27T18:11:19.117Z"
  },
  "meta": {
    "api_request_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "api_request_timestamp": "2019-12-27T18:11:19.117Z"
  },
  "response_type": "object"
}

Returns Examples

200 example

{
  "data": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "amount": 10000,
    "config": {
      "auto_hold": true,
      "auto_hold_message": "auto_hold_message",
      "sandbox_outcome": "standard"
    },
    "currency": "currency",
    "description": "description",
    "device": {
      "ip_address": "192.168.1.1"
    },
    "external_id": "external_id",
    "funding_ids": [
      "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
    ],
    "paykey": "paykey",
    "payment_date": "2019-12-27",
    "status": "created",
    "status_details": {
      "changed_at": "2019-12-27T18:11:19.117Z",
      "message": "Payment successfully created and awaiting validation.",
      "reason": "insufficient_funds",
      "source": "system",
      "code": null
    },
    "status_history": [
      {
        "changed_at": "2019-12-27T18:11:19.117Z",
        "message": "Payment successfully created and awaiting validation.",
        "reason": "insufficient_funds",
        "source": "watchtower",
        "status": "created",
        "code": null
      }
    ],
    "trace_ids": {
      "foo": "string"
    },
    "created_at": "2019-12-27T18:11:19.117Z",
    "customer_details": {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "customer_type": "individual",
      "email": "ron@swanson.com",
      "name": "Ron Swanson",
      "phone": "+1234567890"
    },
    "effective_at": "2019-12-27T18:11:19.117Z",
    "metadata": {
      "foo": "string"
    },
    "paykey_details": {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "customer_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "label": "Bank of America ****1234",
      "balance": 0
    },
    "payment_rail": "ach",
    "processed_at": "2019-12-27T18:11:19.117Z",
    "related_payments": {
      "foo": "original"
    },
    "updated_at": "2019-12-27T18:11:19.117Z"
  },
  "meta": {
    "api_request_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "api_request_timestamp": "2019-12-27T18:11:19.117Z"
  },
  "response_type": "object"
}