Skip to main content
POST
/
businesses
/
{id}
/
payouts
Create an instant payout for the given business
curl --request POST \
  --url https://api.guile.app/businesses/{id}/payouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "amount": "456.78",
  "destination": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "occuredAt": "2023-11-07T05:31:56Z",
  "amount": "456.78",
  "currencyCode": "USD",
  "method": "standard",
  "state": "pending",
  "destination": {
    "routingNumber": "<string>",
    "type": "checking",
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "maskedAccountNumber": "<string>",
    "eligiblePayoutMethods": [
      "standard"
    ],
    "financialInstitutionName": "<string>"
  },
  "createdAt": "2023-11-07T05:31:56Z",
  "fee": "456.78",
  "referenceId": "<string>",
  "failureCode": "<string>",
  "failureReason": "<string>"
}

Headers

​
Idempotency-Key
string
required

A client-generated idempotency key to ensure operations are only processed once even if a client retries the operation. The V4 UUID format, as defined in RFC 4122, is recommended to avoid collisions but is not required.

Path Parameters

​
id
string<uuid>
required

The identifier of the business to create the payout for. The unique, opaque system identifier for a resource. This case-sensitive ID is also used as path parameters in URLs or in other properties or parameters that reference a resource by ID rather than URL.

Body

application/json

Properties for creating an Instant Payout.

​
amount
string<decimal>
required

The amount of money to transfer in the instant payout, excluding fees.

Example:

"456.78"

​
destination
string<uuid>
required

A reference to the destination account for funds to be transfered to. Not every account or card may be eligible for Instant Payouts. Check eligiblePayoutMethods on the account or card to determine eligibility.

Response

Ok. The operation succeeded.

A payout is a representation of a transfer from the payment processor financial account to the financial account of another entity, such as a barber or shop owner.

​
id
string<uuid>
required

The identifier of the payout resource.

​
occuredAt
string<date-time>
required

The date-time when this payment occurred, in RFC 3339 date-time YYYY-MM-DDThh:mm:ss.sssZ format, UTC. This is derived and immutable.

​
amount
string<decimal>
required

The amount of money associated with this payout.

Example:

"456.78"

​
currencyCode
string
required

The ISO 4217 currency code for this monetary value.

Required string length: 3
Example:

"USD"

​
method
enum<string>
required

The method used for the payout. Standard typically means T+2 days through ACH batch processing. Instant expediates payments for an additional processing fee. Instant payouts be be limited based on availability and other factors.

Available options:
standard,
instant
​
state
enum<string>
required

The processing state for a payout.

Available options:
pending,
paid,
failed,
canceled
​
destination
object
required

The destination account for the payout.

  • Option 1
  • Option 2
​
createdAt
string<date-time>
required

The date-time when this payout was created, in RFC 3339 date-time YYYY-MM-DDThh:mm:ss.sssZ format, UTC. This is derived and immutable.

​
fee
string<decimal>
default:0.00
required

The fee associated with this payout.

Example:

"456.78"

​
referenceId
string

The value, if included, assigned by the financial institution for tracking purposes.

​
failureCode
string

When state is failed, this is the payment processor reason code.

​
failureReason
string

When state is failed, this is the human-readable reason.