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

# Payment links

> Share a link anyone can open to pay you by card.

A payment link is a hosted page with a fixed amount. Share its URL in an email, a chat or a QR code; whoever opens it pays by card, and the money lands in the account you chose. No code runs on your side when someone pays.

Scopes: `payment_links:write` to create and archive, `payment_links:read` to list and check.

## Create a link

```bash curl theme={null}
curl https://api.talescria.com/v1/payment-links \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: link-workshop-ticket" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acct_01M2P8GP7RSDXN81CXRFM2HFV7",
    "minorUnits": "4500",
    "currency": "GBP",
    "usage": "reusable",
    "description": "Workshop ticket, 6 December",
    "expiresAt": 1765065600000
  }'
```

```python Python theme={null}
resp = requests.post(
    "https://api.talescria.com/v1/payment-links",
    headers={"Authorization": f"Bearer {token}", "Idempotency-Key": "link-workshop-ticket"},
    json={
        "accountId": account_id,
        "minorUnits": "4500",
        "currency": "GBP",
        "usage": "reusable",
        "description": "Workshop ticket, 6 December",
    },
    timeout=30,
)
link = resp.json()["paymentLink"]
print(link["url"])
```

| Field | Notes |
| - | - |
| `accountId` | One of your accounts, in the link's currency, that can take card payments. |
| `minorUnits`, `currency` | The fixed amount. `USD`, `GBP` or `EUR`. |
| `usage` | `single`: closes after one successful payment. `reusable`: takes payments until it expires or you archive it. |
| `description` | Shown to the payer. Plain text, up to 500 characters. |
| `expiresAt` | Optional. Epoch milliseconds, at most a year away. |
| `customerId` | Optional. One of your [customers](https://docs.talescria.com/guides/customers.md), for your records. Never shown to the payer. |

Share `url` (for example `https://pay.talescria.com/pay/pl_…`). The payer sees your business's verified name, the amount and the description, and pays with a card, including 3-D Secure where their bank asks for it.

## Check payments

```bash theme={null}
curl https://api.talescria.com/v1/payment-links/$LINK_ID \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

| Field | Meaning |
| - | - |
| `status` | `active`, `completed` (a single-use link that's been paid), `expired` or `archived`. |
| `paymentsCompleted` | How many payments it has taken. |
| `lastPaidAt` | When the most recent payment completed. |
| `paymentInProgress` | A single-use link someone is paying right now. |

The money is credited to the link's account; it shows in your [balances](https://docs.talescria.com/guides/accounts.md).

## Single-use links

Only one person can pay a single-use link. While someone is paying it, others see that it's being paid. If their payment doesn't complete (a declined card, or they leave), the link opens up again.

## Archive a link

```bash theme={null}
curl -X POST https://api.talescria.com/v1/payment-links/$LINK_ID/archive \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

New payers are refused. A payment already under way isn't interrupted, and a paid link stays paid.

## Errors

| Response | Meaning |
| - | - |
| `404 NOT_FOUND` | The account or customer isn't yours. |
| `422 VALIDATION` | The account holds a different currency, or the expiry is in the past. |
| `422 UNSUPPORTED` | The account can't take card payments, or the currency isn't supported for links. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.