DevelopersAccept payments
Payment link sales in your integration
How payments made through a merchant's payment links reach your server through the Shop application's webhooks, and how to tell them from shop sales.
A merchant's 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
Links use the merchant's Shop application, the one described in Shop sales in your integration. 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
| 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
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_).
// 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
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
Was this page helpful? Tell us