# Payment Links

A payment link is a URL or QR code that opens a secure checkout page.
This checkout page is where customers complete the payment.
A payment link can be shared with a customer by texting or emailing the link URL directly.
This  hands the customer to the hosted checkout page.
That means the link itself never processes a payment directly.
This page is created by Flute automatically.
When a customer opens it, Flute auto-generates a short-lived payment session from the link's stored configuration.
The merchant themselves do not need to build the checkout page, the user interface, its dialog, or embed any checkout flow.
No POS terminal or custom integration are required.
However, the checkout page may be customized by the client to match their branding  look and feel.
It may be set up as a one-time payment or as a standing "pay us" page for repeat use.
Merchants choose between:
* `SingleUse`, a link tied to a specific invoice or order, which closes itself out after that one payment.
* `MultiUse`, a link that keeps accepting payments from the same or different customers indefinitely.

Every link moves through statuses.
A payment link may be:
* `Active`, able to accept new a new payment.
* `Completed` a `SingleUse` payment link having already successfully accepted a payment.

A payment link may be:
`Inactive`, a payment link that has been explicitly deactivated, and so, not capable to accepting new payments.
`Expired`, a payment link that has expired because of a time limitation imposed on it during its creation.
Flute tracks how many payments it's received and the total collected.
This allows the merchant to always knows how any specified link is performing.
The following endpoints are available.
| Method | Endpoint | Explanation |
|  --- | --- | --- |
| POST | /v2/payment-links | Creates a new payment link. Accepts amount, currency, link type, customer, reference ID, name, description, and expiration; returns the full link record including its `shortUrl`. |
| GET | /v2/payment-links | Lists payment links for the authenticated merchant. Returns a paginated set, filterable by search string, link type, and status, and sortable by `sortBy`/`sortOrder`. |
| GET | /v2/payment-links/{paymentLinkId} | Retrieves a single payment link by its identifier. |
| PATCH | /v2/payment-links/{paymentLinkId} | Partially updates a payment link (JSON Merge Patch-style). Only the fields sent are changed; an omitted field is left as-is, and a field explicitly set to `null` clears it. Returns the full updated link. |
| DELETE | /v2/payment-links/{paymentLinkId} | Deletes (soft-deletes) a payment link. Returns `204 No Content` on success. |
| POST | /v2/payment-links/{paymentLinkId}/share | Shares an `Active` payment link with a customer by SMS or email, sending the link's URL to the given recipient. Requires the customer's consent to receive the message. |

 - [GET /v2/payment-links](https://developer.flute.com/api-reference/v2/payment-links/flute-v2-get-payment-links.md): GET {{baseURL}}/v2/payment-links This endpoint lists payment links for the authenticated merchant. The response is a paginated set of payment links. Results are returned in pages of `pageSize` items,
 - [POST /v2/payment-links](https://developer.flute.com/api-reference/v2/payment-links/flute-v2-post-payment-links.md): POST {{baseURL}}/v2/payment-links This endpoint creates a new payment link. A `paymentMethods` entry without `processorId` is pinned to the merchant's default active processor of that type at creation
 - [GET /v2/payment-links/{paymentLinkId}](https://developer.flute.com/api-reference/v2/payment-links/flute-v2-get-payment-links-paymentlinkid.md): GET {{baseURL}}/v2/payment-links/{{paymentLinkId}} This endpoint retrieves a payment link by ID. This endpoint requires a merchant API token. A partner API token will result in a permissions error inc
 - [PATCH /v2/payment-links/{paymentLinkId}](https://developer.flute.com/api-reference/v2/payment-links/flute-v2-patch-payment-links-paymentlinkid.md): PATCH {{baseURL}}/v2/payment-links/{{paymentLinkId}} This endpoint updates a payment link. `paymentMethods` is replaced wholesale when present. A type absent from the new array stops being accepted. A
 - [DELETE /v2/payment-links/{paymentLinkId}](https://developer.flute.com/api-reference/v2/payment-links/flute-v2-delete-payment-links-paymentlinkid.md): DELETE {{baseURL}}/v2/payment-links/{{paymentLinkId}} This endpoint deletes a payment link. This marks the payment link as `Inactive`. This in contrast to permanently erasing the link and its history.
 - [POST /v2/payment-links/{paymentLinkId}/share](https://developer.flute.com/api-reference/v2/payment-links/flute-v2-post-payment-links-paymentlinkid-share.md): POST {{baseURL}}/v2/payment-links/{{paymentLinkId}}/share This endpoint shares a payment link with a customer by SMS or email. This sends the link's URL to the recipient over the selected channel. Onl