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

# Event-Driven Payouts

> Automate payments to drivers, creators, and partner businesses.

Monigo's payout system lets you define rules that automatically calculate what each recipient is owed based on the events you send. This eliminates manual reconciliation.

## How it works

1. You ingest events (e.g., `ride_completed`, `sale_made`)
2. Monigo applies your payout rules to calculate amounts owed
3. Payout slips are generated per recipient
4. You trigger a batch transfer (or configure automatic triggers)
5. Monigo submits the transfers via your payment provider

## Configuring payout rules

Payout rules are defined on your Plan and map event fields to recipient IDs and amounts.

Example: a ride-hailing platform paying drivers 80% of each fare

```json theme={null}
{
  "payout_rules": [
    {
      "trigger_event": "ride_completed",
      "recipient_field": "driver_id",
      "amount_expression": "fare * 0.80",
      "currency": "NGN"
    }
  ]
}
```

## Triggering payouts

**On demand** — trigger a payout batch manually from the dashboard or via API:

```bash theme={null}
curl -X POST https://api.monigo.co/v1/payouts/trigger \
  -H "Authorization: Bearer mk_live_..."
```

**Scheduled** — configure automatic triggers (daily, weekly, or on a cron schedule) in Dashboard → Settings.

## Recipient bank accounts

Recipients must have a bank account registered with your payment provider. You can link accounts via:

```bash theme={null}
curl -X POST https://api.monigo.co/v1/customers/{id}/payout-accounts \
  -d '{
    "provider": "paystack",
    "account_number": "0123456789",
    "bank_code": "058"
  }'
```

## Payout slip lifecycle

| Status       | Meaning                           |
| ------------ | --------------------------------- |
| `pending`    | Calculated, awaiting trigger      |
| `processing` | Submitted to payment provider     |
| `paid`       | Transfer confirmed                |
| `failed`     | Transfer failed — retry available |

## Webhooks

Subscribe to payout events to update your records:

* `payout.batch.submitted` — batch sent to provider
* `payout.slip.paid` — individual transfer confirmed
* `payout.slip.failed` — individual transfer failed