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

# Pay links API

> Create and manage checkout

A pay link stores payment terms for repeat Lightning checkout through Cash App. These endpoints are not in the OpenAPI spec; this page is the reference. See [Pay links](/orchestra/pay-links) for the flow.

## Endpoints

Management requires a server key; `POST` and `DELETE` require `X-Idempotency-Key`.

* `POST /v1/pay-links`: `201 { payLink }`.
* `GET /v1/pay-links`: `{ payLinks }`. `limit` defaults to 200, clamps to 1..1000; `offset` defaults to 0. Use `includeDisabled=true` to include disabled links.
* `GET /v1/pay-links/:id`: `{ payLink }`.
* `DELETE /v1/pay-links/:id`: `{ ok: true }`; disables the URL without cancelling existing orders.

Public `GET /pay/:shortId` serves HTML: mobile handoff or desktop navigation to `/go?n=...`. `/go` returns a mobile 302 to Cash App or desktop QR HTML. The same completed nonce reuses its order and invoice. These links do not extend invoice expiry. Onramp short URLs reuse one order and do not support `/go`.

## Request body

* `destinationChain`, `destinationAsset`: required. Assets: `USDB`, `USDC`, `USDT`, `PathUSD`. Chains: Spark, Solana, configured CCTP-forward destinations, excluding Hedera. The pair must have a configured `lightning:BTC` route.
* `recipientAddress`: required destination address.
* Exactly one of `amountOut` or `amountFiatUsd`; [amount modes](/orchestra/pay-links#amount-modes) determine fees and delivery. `amountOut` is a positive integer string in destination smallest units representing whole cents; fractional cents return `400 invalid_request`. `amountFiatUsd` is `"1.00"` to `"50000.00"`.
* Optional `affiliateId`: registered affiliate. Optional `label`: up to 255 characters, returned as webhook `payLinkLabel`.

Fiat-capped exact-out requires an eligible USD-stablecoin route, a positive partner-invoiced platform fee, and no app or affiliate fee plan. Other fiat links use exact-in.

## Example

Create a link targeting 25 USDC on Base:

```bash theme={null}
curl -X POST "https://orchestration.flashnet.xyz/v1/pay-links" \
  -H "Authorization: Bearer SERVER_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d '{
    "destinationChain": "base",
    "destinationAsset": "USDC",
    "recipientAddress": "RECIPIENT_ADDRESS",
    "amountOut": "25000000",
    "label": "Coffee fund"
  }'
```

<Info>
  Replace `SERVER_KEY` with your `fn_...` key. Use a new `X-Idempotency-Key` for each operation and reuse it when retrying that same request. Amounts are integer strings in the asset's smallest unit: `"100000"` is 0.001 BTC; `"50000000"` is 50 USDC on Base. Read each asset's `decimals` from `/routes`.
</Info>

Response excerpt:

```json theme={null}
{
  "payLink": {
    "id": "pl_01j7qn4a2b3c4d5e6f7g8h9j0k",
    "shortId": "k3f9x2",
    "destinationChain": "base",
    "destinationAsset": "USDC",
    "recipientAddress": "RECIPIENT_ADDRESS",
    "amountOut": "25000000",
    "label": "Coffee fund",
    "shortUrl": "https://orchestration.flashnet.xyz/pay/k3f9x2"
  }
}
```

Orders carry `payLinkId` and `payLinkLabel` in webhooks. History has no pay-link filter; query by `recipientAddress` and match webhook `payLinkId`.