Skip to content
straddle API Docs
Get started
API Reference
Payouts

Upload a proof-of-authorization document for a payout.

PayoutV1 Payouts.UploadAuthorizationDocument(PayoutUploadAuthorizationDocumentParamsparameters, CancellationTokencancellationToken = default)
POST/v1/payouts/{id}/authorization

Uploads a document as proof of authorization for a payout. Uploading again adds another entry to documents rather than replacing the previous one.

ParametersExpand Collapse
PayoutUploadAuthorizationDocumentParams parameters
required string id

Path param

formatuuid
required string file

Body param: The document file to upload as proof of authorization for this payout.

string correlationID

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

string idempotencyKey

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

maxLength40
minLength10
string requestID

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

string straddleAccountID

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

formatuuid
ReturnsExpand Collapse
class PayoutV1:
required Data Data
required string ID

Unique identifier for the payout.

formatuuid
required Int Amount

The amount of the payout in cents.

formatint32
required Config Config

Configuration for the payout.

Boolean? AutoHold

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

string? AutoHoldMessage

The reason the payout is being automatically held on creation.

SandboxOutcome SandboxOutcome

Payment will simulate processing if not Standard.

One of the following:
"standard"Standard
"paid"Paid
"on_hold_daily_limit"OnHoldDailyLimit
"cancelled_for_fraud_risk"CancelledForFraudRisk
"cancelled_for_balance_check"CancelledForBalanceCheck
"failed_insufficient_funds"FailedInsufficientFunds
"reversed_insufficient_funds"ReversedInsufficientFunds
"failed_customer_dispute"FailedCustomerDispute
"reversed_customer_dispute"ReversedCustomerDispute
"failed_closed_bank_account"FailedClosedBankAccount
"reversed_closed_bank_account"ReversedClosedBankAccount
"failed_not_authorized"FailedNotAuthorized
"reversed_not_authorized"ReversedNotAuthorized
required string Currency

The currency of the payout. Only USD is supported.

required string? Description

An arbitrary description for the payout.

required DeviceInfoV1 Device

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

required string IPAddress

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
required string ExternalID

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

required IReadOnlyList<string> FundingIds

Funding Ids

required Boolean HasResubmit

Has the payout been resubmitted.

required Boolean IsRefund

Is the payout a refund of an original charge.

required Boolean IsResubmit

Is the payout a resubmit of an original payout.

required string Paykey

Value of the paykey used for the payout.

required DateOnly PaymentDate

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
required Status Status

The current status of the payout.

One of the following:
"created"Created
"scheduled"Scheduled
"failed"Failed
"cancelled"Cancelled
"on_hold"OnHold
"pending"Pending
"paid"Paid
"reversed"Reversed
"validating"Validating
required StatusDetailsV1 StatusDetails

Details about the current status of the payout.

required DateTimeOffset ChangedAt

The time the status change occurred.

formatdate-time
required string Message

A human-readable description of the current status.

required Reason Reason

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

One of the following:
"insufficient_funds"InsufficientFunds
"closed_bank_account"ClosedBankAccount
"invalid_bank_account"InvalidBankAccount
"invalid_routing"InvalidRouting
"disputed"Disputed
"payment_stopped"PaymentStopped
"owner_deceased"OwnerDeceased
"frozen_bank_account"FrozenBankAccount
"risk_review"RiskReview
"fraudulent"Fraudulent
"duplicate_entry"DuplicateEntry
"invalid_paykey"InvalidPaykey
"payment_blocked"PaymentBlocked
"amount_too_large"AmountTooLarge
"too_many_attempts"TooManyAttempts
"internal_system_error"InternalSystemError
"user_request"UserRequest
"ok"Ok
"other_network_return"OtherNetworkReturn
"payout_refused"PayoutRefused
"cancel_request"CancelRequest
"failed_verification"FailedVerification
"require_review"RequireReview
"blocked_by_system"BlockedBySystem
"watchtower_review"WatchtowerReview
"validating"Validating
"auto_hold"AutoHold
required Source Source

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"Watchtower
"bank_decline"BankDecline
"customer_dispute"CustomerDispute
"user_action"UserAction
"system"System
string? Code

The status code if applicable.

required IReadOnlyList<StatusHistory> StatusHistory

History of the status changes for the payout.

required DateTimeOffset ChangedAt

The time the status change occurred.

formatdate-time
required string Message

A human-readable description of the status.

required Reason Reason

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

One of the following:
"insufficient_funds"InsufficientFunds
"closed_bank_account"ClosedBankAccount
"invalid_bank_account"InvalidBankAccount
"invalid_routing"InvalidRouting
"disputed"Disputed
"payment_stopped"PaymentStopped
"owner_deceased"OwnerDeceased
"frozen_bank_account"FrozenBankAccount
"risk_review"RiskReview
"fraudulent"Fraudulent
"duplicate_entry"DuplicateEntry
"invalid_paykey"InvalidPaykey
"payment_blocked"PaymentBlocked
"amount_too_large"AmountTooLarge
"too_many_attempts"TooManyAttempts
"internal_system_error"InternalSystemError
"user_request"UserRequest
"ok"Ok
"other_network_return"OtherNetworkReturn
"payout_refused"PayoutRefused
"cancel_request"CancelRequest
"failed_verification"FailedVerification
"require_review"RequireReview
"blocked_by_system"BlockedBySystem
"watchtower_review"WatchtowerReview
"validating"Validating
"auto_hold"AutoHold
required Source Source

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"Watchtower
"bank_decline"BankDecline
"customer_dispute"CustomerDispute
"user_action"UserAction
"system"System
required Status Status

The current status of the charge or payout.

One of the following:
"created"Created
"scheduled"Scheduled
"failed"Failed
"cancelled"Cancelled
"on_hold"OnHold
"pending"Pending
"paid"Paid
"reversed"Reversed
"validating"Validating
string? Code

The status code if applicable.

required IReadOnlyDictionary<string, string> TraceIds

Trace Ids.

DateTimeOffset? CreatedAt

The time the payout was created.

formatdate-time
CustomerDetailsV1 CustomerDetails

Information about the customer associated with the payout.

required string ID

Unique identifier for the customer

formatuuid
required CustomerType CustomerType

The type of customer

One of the following:
"individual"Individual
"business"Business
required string Email

The customer's email address

required string Name

The name of the customer

required string Phone

The customer's phone number in E.164 format

IReadOnlyList<Document>? Documents

Documents uploaded for this payout (e.g. proof of authorization), in the order they were uploaded.

required string DocumentID

Unique identifier for this document.

formatuuid
required string DocumentName

The file name of this document as uploaded.

required Long DocumentSize

The size of this document in bytes.

formatint64
required DocumentType DocumentType
required DateTimeOffset UploadedAt

The UTC timestamp when this document was uploaded.

formatdate-time
DateTimeOffset? EffectiveAt

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

formatdate-time
IReadOnlyDictionary<string, string>? Metadata

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

PaykeyDetailsV1 PaykeyDetails

Information about the paykey used for the payout.

required string ID

Unique identifier for the paykey.

formatuuid
required string CustomerID

Unique identifier for the customer associated with the paykey.

formatuuid
required string Label

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

Int? Balance

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

formatint32
PaymentRail PaymentRail

The payment rail used for the payout.

DateTimeOffset? ProcessedAt

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

formatdate-time

Related payments.

The ID of the related payment.

formatuuid

The type of payment.

One of the following:
One of the following:
DateTimeOffset? UpdatedAt

The time the payout was last updated.

formatdate-time
required ResponseMetadata Meta

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

required string ApiRequestID

Unique identifier for this API request, useful for troubleshooting.

formatuuid
required DateTimeOffset ApiRequestTimestamp

Timestamp for this API request, useful for troubleshooting.

formatdate-time
required ResponseType ResponseType

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"Object
"array"Array
"error"Error
"none"None

Upload a proof-of-authorization document for a payout.

PayoutUploadAuthorizationDocumentParams parameters = new()
{
    ID = "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    File = Encoding.UTF8.GetBytes("Example data"),
};

var payoutV1 = await client.Payouts.UploadAuthorizationDocument(parameters);

Console.WriteLine(payoutV1);
{
  "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"
    ],
    "has_resubmit": true,
    "is_refund": true,
    "is_resubmit": true,
    "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"
    },
    "documents": [
      {
        "document_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "document_name": "document_name",
        "document_size": 0,
        "document_type": "payment_authorization",
        "uploaded_at": "2019-12-27T18:11:19.117Z"
      }
    ],
    "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": [
      {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "payment_type": "charge",
        "relationship": "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
{
  "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"
    ],
    "has_resubmit": true,
    "is_refund": true,
    "is_resubmit": true,
    "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"
    },
    "documents": [
      {
        "document_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "document_name": "document_name",
        "document_size": 0,
        "document_type": "payment_authorization",
        "uploaded_at": "2019-12-27T18:11:19.117Z"
      }
    ],
    "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": [
      {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "payment_type": "charge",
        "relationship": "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"
}