# Payment link sales in your integration (/developers/payment-link-sales)

A merchant's [payment links](/merchants/payment-links) sell through the same hidden application as
their shop, named "Shop". Every press of a link's pay button opens an ordinary checkout session of
that application, so your code sees a link payment the way it sees any session: through webhooks.
Payment links added no v1 endpoint, no webhook event type and no v1 error code, and the SDK
is unchanged.

## The Shop application [#the-shop-application]

Links use the merchant's Shop application, the one described in
[Shop sales in your integration](/developers/shop-sales). If the merchant has none yet, Fianto
creates it at the first accepted press of the pay button on one of their open links, not when a link
is created. So once a payer has pressed Pay on an open link, a merchant with no shop also has an
application named "Shop" in **Developers**. It has
no secret and can't be renamed, disabled or given API keys; its webhook URL can be set.

## What a link session looks like [#what-a-link-session-looks-like]

| Field            | Value                                                                            |
| ---------------- | -------------------------------------------------------------------------------- |
| `order_id`       | `plink_` followed by a random UUID, new for every press of the pay button        |
| mode             | `payment` for a one-time price, `subscription` for a recurring one               |
| `price_id`       | the public ID of the link's price                                                |
| `metadata`       | `{ "source": "payment_link", "payment_link": "<the link's 16-character code>" }` |
| `success_url`    | the merchant's after-payment address, or the link's own page when none is set    |
| `cancel_url`     | the link's page                                                                  |
| expiry           | 30 minutes                                                                       |
| `customer_email` | the email the payer typed on the link's page, when they gave one                 |

A payment-mode order takes the session's metadata, so an order event carries `source: payment_link`
too, and a subscription bought through a link copies the session's metadata. The code in `payment_link` is the last part of
the link's address, `https://checkout.fianto.xyz/l/<code>`.

## Receive link payments [#receive-link-payments]

A link payment sends exactly the events of any checkout session of its mode, to the **Shop
application's** endpoint. Once a merchant has both a shop and links, that one endpoint receives shop
sales and link payments: tell them apart by `metadata.source` (`shop` or `payment_link`), or by the
order ID prefix (`shop_` or `plink_`).

```ts
// app/api/webhooks/fianto-shop/route.ts
import { Webhooks } from '@fianto/nextjs';

export const POST = Webhooks({
  secret: process.env.FIANTO_SHOP_WEBHOOK_SECRET!,
  onOrderPaid: async (event) => {
    if (event.data.metadata?.source === 'payment_link') {
      console.log('payment link sale', event.data.metadata.payment_link, event.data.order_id);
    } else if (event.data.metadata?.source === 'shop') {
      console.log('shop sale', event.data.metadata.shop_slug, event.data.order_id);
    }
  },
});
```

The `plink_` prefix is not reserved: on your own applications, an order ID of yours may start with
`plink_` and works as usual. Only on the Shop application's endpoint does it mean a link payment.

When Fianto suspends a merchant's shop, it expires only the shop's own sessions; link sessions on
the same application are left alone.

## What the API does not show [#what-the-api-does-not-show]

Every v1 read is scoped to the calling application, and the Shop application can never hold a
secret. So no API key can read a link payment through v1: link payments reach you only through the
Shop application's webhooks and the dashboard. There is no v1 endpoint for payment links themselves
either: merchants make and manage them in the dashboard.

## See also [#see-also]

- [Shop sales in your integration](/developers/shop-sales): The Shop application and shop sessions.

- [Event types](/developers/webhooks/events): Every event and its payload.

- [Payment links](/merchants/payment-links): What the merchant creates and shares.