# Payments

A Payment is the money a customer actually paid: its amount, PayMongo's fee, what you keep, and how they paid. PayMongo creates it when a [payment intent](/payment-intents.md), [checkout session](/checkout-sessions.md), or [link](/payment-links.md) is paid, so you only read it. The one exception is the deprecated Sources flow, where `payments()->create()` charges a chargeable source; see [Sources](/sources.md#charge-a-chargeable-source).

Every method lives on `Paymongo::payments()`, and a single payment comes back as a [`Payment`](/data-objects.md#payment). For every attribute PayMongo returns, see its [List all Payments reference](https://docs.paymongo.com/reference/list-all-payments).

## Retrieve a payment

`retrieve()` returns one payment. Take its id from the `payment.paid` webhook, or from `$intent->payments` on the intent it paid:

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

$payment = Paymongo::payments()->retrieve('pay_i7tdqnmwdszWo5B4Xqk2ogX5');

$payment->status === PaymentStatus::Paid;
$payment->money()?->format(); // "₱1,500.50"
$payment->fee;                // PayMongo's fee, in centavos
$payment->netAmount;          // what you keep, in centavos
$payment->paymentIntentId;    // "pi_...", the intent it paid
$payment->billing?->email;
$payment->paidAt();           // ?CarbonImmutable
$payment->attribute('source.type'); // "card", "gcash", ...
```

- Every amount is integer centavos. `money()` wraps `amount` in a `Luigel\Paymongo\Support\Money` for display.
- How the customer paid (the card's brand and last four digits, or the e-wallet) is in the raw `source`, which `attribute()` reads by dot-notation key.

## Statuses

`$payment->status` is a `Luigel\Paymongo\Enums\PaymentStatus`:

| Case | Value | Meaning |
|:-----|:------|:--------|
| `Pending` | `pending` | Not paid yet. |
| `Paid` | `paid` | Paid. It can be [refunded](/refunds.md). |
| `Failed` | `failed` | The attempt failed. |
| `Refunded` | `refunded` | Refunded in full. |
| `PartiallyRefunded` | `partially_refunded` | Part of it was refunded. |

## List payments

`list()` returns a page of payments:

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

$page = Paymongo::payments()->list(['limit' => 25]);

foreach ($page as $payment) {
    $payment->id;
}

if ($page->hasMore) {
    $page = $page->nextPage(); // the next 25, after the last payment on this page
}

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

The page is a `Luigel\Paymongo\Pagination\CursorPage`. Iterate it for its payments, check `hasMore`, and call `nextPage()` for the next one, or `lazy()` to walk every page. `limit` defaults to 10. PayMongo also documents `status` and `created_at` filters on this endpoint, which `list()` passes through as they are.

## Know when a payment happens

Rather than polling `list()`, let PayMongo tell you. It sends `payment.paid` and `payment.failed`, which the package dispatches as `Luigel\Paymongo\Events\PaymentPaid` and `PaymentFailed`. See [Webhooks](/webhooks.md).