# Payouts

A Payout is PayMongo sending you the money your customers paid. PayMongo generates payouts on its own, from payments that have cleared, and sends them on your payout schedule, so this service only reads them: to reconcile a payout against your orders, or to show what is coming next.

Every method lives on `Paymongo::payouts()`, and a single payout comes back as a [`Payout`](/data-objects.md#payout). For how clearing and schedules work, see PayMongo's [Payouts guide](https://docs.paymongo.com/docs/money-movement-payouts), and for every field, its [Payouts reference](https://docs.paymongo.com/reference/getpayoutlist).

## List payouts

`list()` returns a page of payouts. Every filter is optional:

```php
use Luigel\Paymongo\Enums\PayoutStatus;
use Luigel\Paymongo\Facades\Paymongo;

$page = Paymongo::payouts()->list([
    'payout_status' => PayoutStatus::Deposited,
    'created_at.between' => '2026-08-01..2026-08-31', // YYYY-MM-DD..YYYY-MM-DD
    'sort_by' => 'net_amount', // or created_at
    'order' => 'desc',
    'limit' => 20,
]);

foreach ($page as $payout) {
    $payout->money()?->format(); // the net amount, e.g. "₱48,550.00"
}

$page->meta['total_records'] ?? null; // totals PayMongo sends with the page
$page->nextCursor;                    // ?string, null on the last page
$page = $page->nextPage();            // ?CursorTokenPage, requested with after = nextCursor

// Or walk every payout, one request per page, as you go:
foreach (Paymongo::payouts()->list()->lazy() as $payout) {
    $payout->status;
}
```

- `payout_status` is a `Luigel\Paymongo\Enums\PayoutStatus` case or its value.
- `created_at.between` takes two dates, `YYYY-MM-DD..YYYY-MM-DD`.
- `search` matches a payout id or merchant id. `provider` is `paymongo_central_hub` or `unionbank`.
- `limit` defaults to 20.

Payout lists page differently from every other list. Instead of `hasMore`, the page is a `Luigel\Paymongo\Pagination\CursorTokenPage`, with an opaque `nextCursor` token that is `null` on the last page, and `meta` with the totals PayMongo sends, such as `total_records`. Iterate it, call `nextPage()`, or `lazy()` to walk every page, just like a `CursorPage`.

## Retrieve a payout

`retrieve()` returns a payout with what went into it:

```php
use Luigel\Paymongo\Enums\PayoutStatus;
use Luigel\Paymongo\Facades\Paymongo;

$payout = Paymongo::payouts()->retrieve('po_2fdKBqNAKMvUXTUAvhZDdXbW');

$payout->status === PayoutStatus::Deposited;
$payout->amount;           // gross, in centavos
$payout->fee;              // deductions, in centavos
$payout->taxAmount;        // and taxAmount, refundAmount, disputeAmount,
$payout->adjustmentAmount; // adjustmentAmount: each in centavos
$payout->netAmount;        // what reaches your account
$payout->bankName;         // e.g. "BDO"
$payout->bankAccountNumber;
```

Every amount is integer centavos. `amount` is the gross, the other amounts are what was taken from it, and `netAmount` is what reaches your account. `money()` formats the net amount.

`$payout->status` is a `Luigel\Paymongo\Enums\PayoutStatus`. PayMongo's guide describes these:

| Case | Value | Meaning |
|:-----|:------|:--------|
| `OnHold` | `on_hold` | Paused, usually for a compliance or risk review. PayMongo emails you what to do. |
| `InTransit` | `in_transit` | Sent, on its way to your account. |
| `Deposited` | `deposited` | Credited to your account. |
| `Returned` | `returned` | Could not be delivered, usually because of wrong bank or wallet details. |

The API reference also lists `pending` and `cancelled` (`Pending` and `Cancelled`), which PayMongo's guide does not describe further.

## See what a payout paid for

`transactions()` returns the payments, refunds, disputes, and adjustments a payout adds up, to match against your orders:

```php
use Luigel\Paymongo\Facades\Paymongo;

foreach (Paymongo::payouts()->transactions('po_2fdKBqNAKMvUXTUAvhZDdXbW', ['limit' => 50])->lazy() as $transaction) {
    $transaction->id;                // "pay_...", "ref_...", ...
    $transaction->transactionType(); // "payment", "refund", "dispute", "adjustment", ...
    $transaction->amount;            // centavos
    $transaction->fee;
    $transaction->netAmount;
}
```

Each one is a [`PayoutTransaction`](/data-objects.md#payouttransaction), and its page is a `CursorTokenPage` too. `transactionType()` says what kind it is.

## See what comes next

`schedule()` takes your organization id (`org_...`) and returns your payout schedule with the payouts lined up on it:

```php
use Luigel\Paymongo\Facades\Paymongo;

$schedule = Paymongo::payouts()->schedule('org_9NxTZ8ZDVQpZC3bDMSKtwEXA'); // your organization id

$schedule->scheduleType;      // your current schedule, e.g. "weekly"
$schedule->options;           // list<string>: the schedules you can switch to
$schedule->attribute('days'); // the weekday(s) or date of month it pays out on

// The next payout: its amount in centavos, receive_at, and a breakdown
// of the payments, refunds, disputes, and adjustments in it.
$upcoming = $schedule->lineup[0] ?? null;
```

It comes back as a [`PayoutSchedule`](/data-objects.md#payoutschedule). The first entry in `lineup` is your next payout, and the second the one after it. Change the schedule itself in the PayMongo Dashboard.