Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.fluveo.com/llms.txt

Use this file to discover all available pages before exploring further.

Payouts transfer your available balance to a linked bank account. This guide covers the full payout flow — from understanding your balance to monitoring funds hitting your bank.

​
How balance works

When a payment succeeds, funds move through two stages before you can pay them out:
  1. Pending — funds have been captured but are not yet available. This covers the risk window while card networks process the transaction.
  2. Available — funds are ready to pay out. Pending funds become available after a rolling T+2 business day settlement window.
Retrieve your current balance at any time: 
curl https://api.leanrails.com/v1/balance \
  -u "sk_test_xxx:"
Response: 
{
  "object": "balance",
  "available": [
    {
      "currency": "usd",
      "amount": 125000
    }
  ],
  "pending": [
    {
      "currency": "usd",
      "amount": 42000
    }
  ],
  "livemode": false
}
All amounts are in the smallest currency unit (cents for USD). 125000 = $1,250.00.

​
External account setup

You must have at least one external account (bank account) linked before you can create a payout. 
curl -X POST https://api.leanrails.com/v1/external_accounts \
  -u "sk_test_xxx:" \
  -d "routing_number=110000000" \
  -d "account_number=000123456789" \
  -d "account_holder_name=Acme Corp" \
  -d "currency=usd"
List your linked accounts: 
curl https://api.leanrails.com/v1/external_accounts \
  -u "sk_test_xxx:"
See the External Accounts API reference for full details.

​
Creating a payout

Once you have available balance and a linked external account, create a payout: 
curl -X POST https://api.leanrails.com/v1/payouts \
  -u "sk_test_xxx:" \
  -d "amount=125000" \
  -d "currency=usd"
Response: 
{
  "id": "po_1abc2def3ghi",
  "object": "payout",
  "amount": 125000,
  "currency": "usd",
  "status": "pending",
  "arrival_date": 1710288000,
  "created": 1710115200,
  "livemode": false
}
The payout starts in pending status and transitions to paid when the funds arrive in your bank account, or failed if the transfer is rejected. To cancel a payout that hasn’t been submitted yet: 
curl -X POST https://api.leanrails.com/v1/payouts/po_1abc2def3ghi/cancel \
  -u "sk_test_xxx:"

​
Settlement batches and timing

Settlement batches group all transactions processed within a given period. Each batch is processed automatically according to your settlement schedule. Retrieve your settlement configuration: 
curl https://api.leanrails.com/v1/settlement/config \
  -u "sk_test_xxx:"
List recent settlement batches: 
curl https://api.leanrails.com/v1/settlement/batches \
  -u "sk_test_xxx:"
Each batch transitions through these states:
StatusDescription
pendingTransactions collected, not yet processed
processingFunds being swept to available balance
completedFunds available for payout

​
Monitoring payout status

Listen for webhook events to track payout lifecycle automatically:
EventTrigger
payout.createdA new payout was initiated
payout.paidFunds successfully arrived at the bank
payout.failedThe payout was rejected by the bank
Configure a webhook endpoint to receive these events: 
curl -X POST https://api.leanrails.com/v1/webhook_endpoints \
  -u "sk_test_xxx:" \
  -d "url=https://example.com/webhooks" \
  -d "enabled_events[]=payout.created" \
  -d "enabled_events[]=payout.paid" \
  -d "enabled_events[]=payout.failed"
See the webhook events reference for full payload examples.