# Payment Links

A payment link is a reusable URL. Anyone with the link can pay the amount you set. Create, list, read, and soft-delete links with your API key.

## Endpoints

All routes use the same authentication as the rest of `/v1`: a Bearer token from `POST /v1/auth/token` and the header `x-fluxis-api-key`. See [API Credentials](/docs/developers/api-credentials).

| Method | Path | Role |
| ------ | ---- | ---- |
| `POST` | `/v1/payment-links` | `write` |
| `GET` | `/v1/payment-links` | `read` |
| `GET` | `/v1/payment-links/:id` | `read` |
| `DELETE` | `/v1/payment-links/:id` | `write` |

The point of sale must belong to the credential and must be an online fixed point of sale. A foreign point of sale returns 403.

## Create

`POST /v1/payment-links` returns `201`.

| Field | Required | Notes |
| ----- | -------- | ----- |
| `point_of_sale_id` | yes | UUID of an online point of sale the key can use |
| `name` | yes | Shown to the buyer as the merchant name |
| `amount` | yes | Positive decimal string with at most 2 places, for example `"25.00"` |
| `currency` | yes | `USD` or `ARS` |
| `external_id` | no | Your internal order or invoice reference. The buyer does not see this as the product title |
| `expiration` | no | Unix time in seconds, UTC. Omit it and the link does not expire |
| `payment_options` | no | Subset of the point of sale options. Empty uses the point of sale options |
| `image` | no | `http` or `https` URL, at most 255 characters |

Optional header `Idempotency-Key`: 8 to 64 letters, digits, `_`, or `-`. The same key and the same body return the original `201` for 24 hours. The same key with a different body returns `409`.

Status is `deleted`, then `disabled`, then `expired`, otherwise `active`. `never_expires` is `true` when `expiration` was omitted.

## List and read

`GET /v1/payment-links` accepts `page` (default 1), `page_size` (default 20, max 100), `point_of_sale_id`, and `status` (`active`, `expired`, `disabled`, `deleted`, or `all`). The default status is `active`.

`GET /v1/payment-links/:id` returns the link, payment stats, and the five most recent payments. A soft-deleted link is still readable.

## Delete

`DELETE /v1/payment-links/:id` soft-deletes the link and returns `200`. Deleting a link that is already deleted succeeds and sets `already_deleted` to `true`. Existing payments are kept.

The [merchant MCP](/docs/developers/mcp) deletes in two steps. This REST endpoint deletes in one request.