> For the complete documentation index, see [llms.txt](https://plexo.gitbook.io/rest-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://plexo.gitbook.io/rest-api/api-reference/payment-links.md).

# Payment Links

Payment Links let you create shareable URLs that direct payers to a Plexo-hosted checkout page. You create a Payment Link through the API, share it via any channel (email, SMS, messaging apps, QR codes), and Plexo handles the checkout experience when the payer opens the link.

For a step-by-step integration walkthrough, see the [Payment Links Guide](/rest-api/payment-links/payment-links.md).

## Key concepts

**Payment Link** — A persistent, shareable payment resource. Each link has a unique `externalId` used in the public URL and an internal `id` (GUID) used in the authenticated API.

**Link types** — A Payment Link has a `type` that controls its behavior:

| Type        | Description                                                                                         |
| ----------- | --------------------------------------------------------------------------------------------------- |
| `regular`   | Multi-use link. Stays active for multiple payments until manually disabled or expired.              |
| `one-time`  | Single-use link. Becomes inactive after the first successful payment.                               |
| `quick-pay` | On-the-fly payment session created without a pre-stored link. Requires merchant quick-pay settings. |

**Amount modes** — The `settings.amountMode` field controls whether the amount is fixed or flexible:

| Mode       | Description                                                                        |
| ---------- | ---------------------------------------------------------------------------------- |
| `fixed`    | The payer pays the exact amount set on the link.                                   |
| `flexible` | The payer enters the amount at checkout, optionally constrained by min/max limits. |

**Status values** — A Payment Link moves through the following statuses:

| Status      | Description                                |
| ----------- | ------------------------------------------ |
| `active`    | The link is available for payments.        |
| `expired`   | The link has passed its `validUntil` date. |
| `completed` | A one-time link that has been paid.        |
| `deleted`   | The link has been soft-deleted.            |

**Split destinations** — Any Payment Link (regardless of type) can have `splitDestinations` to distribute the payment amount across multiple destination merchants using percentage, fixed, or residual allocation rules. See [Split Payments](/rest-api/payment-links/split-payments.md).

## Endpoints overview

### Authenticated endpoints

All authenticated endpoints require Basic Auth or Bearer Token and are scoped to your client.

| Method   | Path                                                   | Description                                                                                                          |
| -------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| `POST`   | `/v1/payment-links`                                    | [Create a Payment Link](/rest-api/api-reference/payment-links/create.md)                                             |
| `GET`    | `/v1/payment-links/{paymentLinkId}`                    | [Get a Payment Link](/rest-api/api-reference/payment-links/get.md)                                                   |
| `GET`    | `/v1/payment-links/{paymentLinkId}/qr.svg`             | Generate a QR SVG for a Payment Link                                                                                 |
| `GET`    | `/v1/payment-links/query`                              | [List Payment Links](/rest-api/api-reference/payment-links/list.md)                                                  |
| `PUT`    | `/v1/payment-links/{paymentLinkId}`                    | [Update a Payment Link](/rest-api/api-reference/payment-links/update.md)                                             |
| `DELETE` | `/v1/payment-links/{paymentLinkId}`                    | [Delete a Payment Link](/rest-api/api-reference/payment-links/delete.md)                                             |
| `GET`    | `/v1/payment-links/{paymentLinkId}/split-destinations` | [Get split destinations](/rest-api/api-reference/payment-links/split-destinations.md)                                |
| `PUT`    | `/v1/payment-links/{paymentLinkId}/split-destinations` | [Replace split destinations](/rest-api/api-reference/payment-links/split-destinations.md#replace-split-destinations) |
| `GET`    | `/v1/payment-links/settings`                           | [Get merchant settings](/rest-api/api-reference/payment-links/settings.md)                                           |
| `PUT`    | `/v1/payment-links/settings`                           | [Update merchant settings](/rest-api/api-reference/payment-links/settings.md#update-merchant-settings)               |

### Public endpoints

Public endpoints require no authentication. They are used by payers opening Payment Links.

| Method | Path                                                    | Description                                                                                                        |
| ------ | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `GET`  | `/v1/public/payment-links/{externalId}`                 | [Resolve a Payment Link](/rest-api/api-reference/payment-links/public-endpoints.md)                                |
| `GET`  | `/v1/public/payment-links/{externalId}/qr.svg`          | [Get a Payment Link QR Code](/rest-api/api-reference/payment-links/public-endpoints.md#get-a-payment-link-qr-code) |
| `POST` | `/v1/public/payment-links/{externalId}/sessions`        | [Start a checkout session](/rest-api/api-reference/payment-links/public-endpoints.md#start-a-checkout-session)     |
| `POST` | `/v1/public/payment-links/quick-pay/sessions`           | [Start a quick-pay session](/rest-api/api-reference/payment-links/public-endpoints.md#start-a-quick-pay-session)   |
| `GET`  | `/v1/public/payment-links/businesses/{businessUrlName}` | [Resolve business settings](/rest-api/api-reference/payment-links/public-endpoints.md#resolve-business-settings)   |

## Typical integration flow

```mermaid
sequenceDiagram
  participant Merchant as Your backend
  participant Plexo as Plexo API
  participant Links as Plexo Hosted Links
  participant Checkout as Plexo Hosted Checkout
  participant Payer as Payer

  Merchant->>Plexo: POST /v1/payment-links (create link)
  Plexo-->>Merchant: PaymentLinkDto with externalId
  Merchant->>Payer: Share link URL (email, SMS, QR, etc.)
  Payer->>Links: Opens links.plexo.com.uy/{externalId}
  Links->>Plexo: Resolve link & create session (internal)
  Links-->>Payer: Pre-checkout page (or instant redirect)
  Payer->>Checkout: Redirected to hosted checkout
  Payer->>Checkout: Enters payment details & confirms
  Checkout->>Plexo: Process payment
  Plexo-->>Checkout: Payment result
  Checkout-->>Payer: Confirmation page
  Plexo-->>Merchant: Payment callback notification
```

The hosted experience at `links.plexo.com.uy` handles link resolution and session creation securely server-side. Payers never interact with the public API directly — the hosted page manages the full flow from link opening through checkout redirect.

## Authentication

All `/v1/payment-links` endpoints require authentication. Use Basic Auth or Bearer Token as described in the [Authentication guide](/rest-api/getting-started/authentication.md).

Public endpoints under `/v1/public/payment-links` are anonymous and require no credentials.

## Related guides

* [Payment Links Overview](/rest-api/payment-links/payment-links.md)
* [Integration Guide](/rest-api/payment-links/integration-guide.md)
* [Split Payments](/rest-api/payment-links/split-payments.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://plexo.gitbook.io/rest-api/api-reference/payment-links.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.