> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meum.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Merchant `plink_` management and buyer `plpub_` checkout routes.

Payment links use two ID namespaces:

| Prefix   | Use                                    |
| -------- | -------------------------------------- |
| `plink_` | Merchant API resource id               |
| `plpub_` | Buyer-facing URL token (public routes) |

### Public ID format

All public resource IDs use opaque prefixes plus a **32-character lowercase hex** token (128-bit entropy):

| Prefix   | Example                                  |
| -------- | ---------------------------------------- |
| `inv_`   | `inv_cb1e73f508a2abf4ea639f100de14cef`   |
| `plink_` | `plink_961544395accbc1e00c56bbdaa4f07da` |
| `plpub_` | `plpub_c9a9bb730611077574c828af5af5fed1` |

Legacy **12-character** `plpub_` URLs (issued before June 2026) still resolve; the API returns the current 32-char `public_id` in responses.

Buyer responses omit internal UUIDs, settlement wallets, and webhook configuration.

## Authentication (merchant routes)

```
Authorization: Bearer sk_live_...
```

Buyer routes under `/v1/public/payment-links/*` require **no API key**.

***

## Create payment link

`POST /v1/payment-links`

|                 |                                    |
| --------------- | ---------------------------------- |
| **Scope**       | `payment_links:write`              |
| **Idempotency** | `Idempotency-Key` header supported |
| **Rate limit**  | Write bucket                       |

### Request

| Field                       | Notes                                       |
| --------------------------- | ------------------------------------------- |
| `amount_mode`               | `fixed_amount` or `customer_defined_amount` |
| `amount`                    | Required for fixed mode (string)            |
| `min_amount` / `max_amount` | Customer-defined mode                       |
| `allow_multiple_payments`   | `true` = reusable; `false` = single-use     |

### Response `201`

`id` (`plink_...`), `public_id` (`plpub_...`), `public_url`, pricing fields, `usage` (`reusable` / `single_use`).

***

## Retrieve / update

`GET` / `PATCH /v1/payment-links/{id}`

Path id must be `plink_...`. PATCH cannot change pricing after checkout has started.

***

## Activate / deactivate

`POST /v1/payment-links/{id}/activate`\
`POST /v1/payment-links/{id}/deactivate`

Scope: `payment_links:write`.

***

## Public buyer link

`GET /v1/public/payment-links/{public_id}`

|          |                       |
| -------- | --------------------- |
| **Auth** | None (`security: []`) |
| **Path** | `plpub_...`           |

Returns buyer-safe fields only: title, amounts, `store_name`, `merchant_name`. **Does not** expose store UUID, organization id, settlement wallet, webhooks, merchant email, or `store_logo_url` (CDN paths may embed org ids).

### cURL

```bash theme={null}
curl "https://api.meum.io/v1/public/payment-links/plpub_c9a9bb730611077574c828af5af5fed1"
```

***

## Start checkout

`POST /v1/public/payment-links/{public_id}/checkout`

|                |                    |
| -------------- | ------------------ |
| **Auth**       | None               |
| **Rate limit** | Per `plpub_` token |

### Request

```json theme={null}
{
  "amount": "42.50",
  "origin_asset": "usdc.near",
  "refund_to": "alice.near"
}
```

* **Fixed amount:** omit `amount`.
* **Customer-defined:** `amount` required within min/max.
* **Single-use:** reuses open invoice when present; returns `403` when already paid.

### Response `201`

```json theme={null}
{
  "invoice_id": "inv_...",
  "checkout_url": "https://pay.meum.io/...",
  "reused": false
}
```

### Security

Buyer routes are unauthenticated; rely on rate limits and opaque `plpub_` tokens. Never embed `plink_` merchant ids in public pages.