Create a payout

PayoutV1 Payouts.Create(, )

POST/v1/payouts

Use payouts to send money to your customers.

ParametersExpand Collapse

PayoutCreateParams parameters

required Int amount

Body param: The amount of the payout in cents.

formatint32

required string currency

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

required string? description

Body param: An arbitrary description for the payout.

required DeviceInfoV1 device

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

required string externalID

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

required string paykey

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

required DateOnly paymentDate

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 config

Body param

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:

IReadOnlyDictionary<string, string>? metadata

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

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:

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

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:

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:

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:

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:

required Status Status

The current status of the charge or payout.

One of the following:

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:

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

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

IReadOnlyDictionary<string, RelatedPaymentsItem>? RelatedPayments

Related payments.

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:

Create a payout

PayoutCreateParams parameters = new()
{
    Amount = 10000,
    Currency = "currency",
    Description = "Vendor invoice payment",
    Device = new("192.168.1.1"),
    ExternalID = "external_id",
    Paykey = "paykey",
    PaymentDate = "2019-12-27",
};

var payoutV1 = await client.Payouts.Create(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"
    ],
    "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

{
  "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"
}