> For the complete index of the 402pay docs, see [llms.txt](https://developer.402pay.co/llms.txt).

# Create a link

Create a reusable hosted checkout with a fixed price.

`POST https://dash.402pay.co/api/v1/links`

Returns the link with its hosted checkout at `url`. Every customer who pays it creates a new payment with the link's `link_id`.

### Body

- `amount` (integer, required): The price in minor units of `currency`: `4900` with `USD` is $49.00. From the equivalent of $1.00 up to 1,000,000.00 in the currency.
- `currency` (string): USD, EUR, GBP, CAD, AUD. Defaults to USD.
- `name` (string): What the customer is paying for, up to 80 characters. It becomes the description of each payment made through the link, shown on the receipt.
- `description` (string): More about it, shown in the checkout's details, up to 300 characters.
- `success_url` (string): Where checkout sends the customer after paying, with `payment_id` added to its query. Use `https://`; `http://` works only for `localhost` and `127.0.0.1`. Defaults to the redirect in your checkout settings, then the receipt.

### Errors

- 400 `invalid_request` A field is missing, unknown or out of range. `field` names it.
- 403 `test_mode_unavailable` A test key can't create links on a live business, so use a live key.

Any request can also fail on its key or its body. See [errors](https://developer.402pay.co/api/errors.md).

Request, cURL:

```bash
curl -X POST "https://dash.402pay.co/api/v1/links" \
  -H "Authorization: Bearer $PAY402_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Team plan, monthly",
    "description": "Everything in Pro for up to 10 people.",
    "amount": 19900,
    "currency": "USD"
  }'
```

Request, Node.js:

```js
const response = await fetch("https://dash.402pay.co/api/v1/links", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAY402_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Team plan, monthly",
    description: "Everything in Pro for up to 10 people.",
    amount: 19900,
    currency: "USD"
  }),
});
const { data } = await response.json();
```

Request, Python:

```python
import os

import requests

response = requests.post(
    "https://dash.402pay.co/api/v1/links",
    headers={
        "Authorization": f"Bearer {os.environ['PAY402_SECRET_KEY']}",
    },
    json={
        "name": "Team plan, monthly",
        "description": "Everything in Pro for up to 10 people.",
        "amount": 19900,
        "currency": "USD"
    },
)
data = response.json()["data"]
```

Response, 201 Created:

```json
{
  "data": {
    "id": "lnk_nt842tPNne3lf0ka",
    "kind": "link",
    "code": "v6e4mrczwg",
    "url": "https://checkout.402pay.co/checkout/v6e4mrczwg",
    "name": "Team plan, monthly",
    "description": "Everything in Pro for up to 10 people.",
    "amount": 19900,
    "currency": "USD",
    "success_url": null,
    "status": "active",
    "disabled_at": null,
    "payments_count": 0,
    "volume": {
      "amount": 0,
      "currency": "USD"
    },
    "created_at": "2026-09-26T21:22:46.992Z",
    "updated_at": "2026-09-26T21:22:46.992Z"
  }
}
```