Skip to main content

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.

A 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 and refunds. 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 endpoint. If processor is set (e.g. STRIPE), every linked payment and refund must also use this processor value. Use the 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.

​
Linking payments and refunds

Attach existing invoice payments and refunds by Layer ID or your external ID: 
{
  "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 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. 
{
  "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. 
{
  "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. 
{
  "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.