# Classic Links

Classic Links are PayMongo's original payment links API: a PayMongo-hosted payment page for one amount, at a URL you share with the customer. The package still supports them, on `Paymongo::links()`.

For new integrations, use [Payment Links](/payment-links.md) instead. PayMongo has announced that it will deprecate the Classic Links API and recommends moving existing integrations to Payment Links; see its [migration guide](https://docs.paymongo.com/reference/payment-links#migration-from-legacy-links).

A single link comes back as a [`Link`](/data-objects.md#link).

## How they differ from Payment Links

| | Classic Links, `links()` | Payment Links, `paymentLinks()` |
|:--|:--|:--|
| Shareable URL | `$link->checkoutUrl` | `$link->url` |
| `status` | Whether it was paid: `Unpaid`, `Paid`, or `Archived` | Whether it takes payments: `Active` or `Archived` |
| Payments | On the link, as `$link->payments` | Fetched with `payments()` |
| Limit how many times it is paid | No | `restriction.completed_sessions.limit` |
| `metadata` | No | Yes |

## Create a link

`create()` takes the amount in integer centavos and a description. Send the customer the `checkoutUrl` it returns:

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

$link = Paymongo::links()->create([
    'amount' => 150050, // PHP 1,500.50, in centavos
    'description' => 'Invoice INV-1234',
    'remarks' => 'Custom order via Messenger',
]);

$link->checkoutUrl;     // send this to your customer
$link->referenceNumber; // e.g. "WTmSJbV"
```

## Retrieve a link

`retrieve()` finds a link by its id. `retrieveByReference()` finds it by the short reference number at the end of its URL, and returns `null` when no link has that reference:

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

$link = Paymongo::links()->retrieve('link_wWaibr22CzEnficNhQNPUdoo');

$link->status; // ?LinkStatus: Unpaid, Paid or Archived

foreach ($link->payments as $payment) {
    $payment->id; // "pay_..."
}

$linkByReference = Paymongo::links()->retrieveByReference('WTmSJbV'); // null when no link has it
```

## List links

`list()` returns a `CursorPage` of links. Iterate it, or call `lazy()` to walk every page:

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

foreach (Paymongo::links()->list(['limit' => 20]) as $link) {
    $link->description;
    $link->money()?->format(); // "₱1,500.50"
}
```

## Archive and unarchive a link

`archive()` stops a link from being paid, and `unarchive()` opens it again:

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

$link = Paymongo::links()->archive('link_wWaibr22CzEnficNhQNPUdoo');   // can no longer be paid
$link = Paymongo::links()->unarchive('link_wWaibr22CzEnficNhQNPUdoo'); // can be paid again
```

## Know when it was paid

PayMongo sends `link.payment.paid` when a customer pays a link, and the package dispatches it as `Luigel\Paymongo\Events\LinkPaymentPaid`. See [Webhooks](/webhooks.md).