> ## Documentation Index
> Fetch the complete documentation index at: https://docs.layerfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payouts

A [Payout](/api-reference/customer-payouts/payout) represents a processor deposit that moves funds from a payment processor, such as Stripe, to one of your business customers’ bank accounts.

Payouts are used to reconcile bank transactions that represent processor deposits with the underlying processor activity they contain, such as [invoice payments](/api-reference/invoice/payments) and [refunds](/api-reference/refunds/refund). Matching bank transactions to payouts prevents revenue from being double-counted: first from the invoice payment, and second from categorizing the bank transaction as revenue.

## Importing payouts

Create payouts with the [Create Payout](/api-reference/v1/create-payout) endpoint, or use [Bulk Create Payouts](/api-reference/v1/bulk-create-payouts) to create or update multiple payouts in a single request. If `processor` is set (e.g. `STRIPE`), every linked payment and refund must also use this `processor` value. Use the [Update Payout](/api-reference/v1/update-payout) endpoint to modify a payout after it has been created.

`external_id` is your idempotency key. Re-posting the same `external_id` returns the existing payout unchanged. The bulk endpoint uses upsert semantics: if a payout with the same `external_id` already exists, it will be updated; otherwise, a new payout is created.

### Linking payments and refunds

Attach existing invoice payments and refunds by Layer ID or your external ID:

```json theme={null}
{
  "payments": [
    { "invoice_payment_id": "<invoice_payment_id>" }
  ],
  "refunds": [
    { "refund_payment_id": "<refund_payment_id>" }
  ]
}
```

### Other transactions

Use `other_transactions` for line items that are not represented as invoice payments or refunds (e.g. Merchant Cash Advance fees, tax withholding, or other fees).

## Stripe Instant Payouts

Instant payouts from Stripe should be imported as two [Payout](/api-reference/customer-payouts/payout) objects in Layer: one payout for the instant cash movement, and one following payout that reconciles the itemized payment activity when Stripe includes it in a later payout.

Normal Stripe payouts are itemized around the specific transactions included in the payout. Instant payouts are amount-based, so Layer represents the instant transfer separately from the later itemized payout that contains the payment.

### Process Steps

The expected process steps are:

1. Import the invoice and payment.
2. Create the instant payout with no payments or refunds, plus one `CREDIT` transaction to `STRIPE_CLEARING`.
3. Create the following payout with the original payment attached, plus one `DEBIT` transaction from `STRIPE_CLEARING`.

After both payout objects are imported, the `STRIPE_CLEARING` entries will offset each other.

### 1. Import the payment

First, import the sale and its Stripe payment. In the example payout below, there is an invoice for `12500` cents, with one credit card payment for the same amount and no fee.

```json theme={null}
{
  "external_id": "invoice-instant-payout",
  "sent_at": "2023-12-05T00:00:00Z",
  "due_at": "2023-12-05T00:00:00Z",
  "customer_external_id": "customer-instant-payout",
  "line_items": [
    {
      "description": "Test Service",
      "quantity": 1,
      "unit_price": 12500,
      "product": "Test Product"
    }
  ],
  "payments": [
    {
      "external_id": "payment-instant-payout",
      "amount": 12500,
      "fee": 0,
      "processor": "STRIPE",
      "method": "CREDIT_CARD"
    }
  ]
}
```

### 2. Create the instant payout

Create a payout for the instant transfer itself. Note the example payout below has the amount that Stripe deposited, but does not yet attach the invoice payment.

```json theme={null}
{
  "external_id": "payout-instant",
  "paid_out_amount": 12500,
  "fee": 0,
  "processor": "STRIPE",
  "completed_at": "2023-12-05T00:00:00Z",
  "payments": [],
  "refunds": [],
  "other_transactions": [
    {
      "amount": 12500,
      "direction": "CREDIT",
      "account": {
        "type": "StableName",
        "stable_name": "STRIPE_CLEARING"
      },
      "description": "Stripe payout payout-instant",
      "external_id": "pbt-payout-instant-funding"
    }
  ]
}
```

### 3. Create the following payout

When Stripe later reports the itemized payout that includes the payment, create a second payout. In the example payout below, the `paid_out_amount` of `0`, references the invoice payment created earlier and includes the opposite `STRIPE_CLEARING` transaction.

```json theme={null}
{
  "external_id": "payout-following",
  "paid_out_amount": 0,
  "fee": 0,
  "processor": "STRIPE",
  "completed_at": "2023-12-06T00:00:00Z",
  "payments": [
    {
      "invoice_payment_id": "<invoice_payment_id>"
    }
  ],
  "refunds": [],
  "other_transactions": [
    {
      "amount": 12500,
      "direction": "DEBIT",
      "account": {
        "type": "StableName",
        "stable_name": "STRIPE_CLEARING"
      },
      "description": "Stripe payout payout-instant",
      "external_id": "pbt-payout-instant-reconciliation"
    }
  ]
}
```

The example now has both payouts present, with the following payout including the original payment. The `STRIPE_CLEARING` account will net to zero after the `CREDIT` and `DEBIT` transactions are applied.