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

# Payment links and hosted checkout

> Create a link to a hosted checkout page, share it, and get paid without building a payment form.

A payment link is a URL to a checkout page that Payve hosts. The payer opens it, chooses how to pay, and pays. The money lands in your wallet and you get a `payin.successful` event.

The checkout URL is built from the link's `slug`:

```text
https://checkout.payvehq.com/pay/{slug}
```

## Create a link

`POST /v1/payment-links` · needs the `payins:write` scope

**title** `string` *required*

Shown to the payer. Also used to build the slug.

**currency** `string` *required*

The currency to collect.

**amount** `integer`

A fixed amount in minor units. Leave it out to let the payer enter the amount.

**description** `string`

More detail for the payer.

**expiresAt** `string`

When the link stops working. ISO 8601.

**redirectUrl** `string`

Where the checkout sends the payer afterwards.

**allowedMethods** `string[]`

Limit how the payer can pay: `bank_transfer`, `card`, `mobile_money`.

**overpaymentTolerance** `integer` (default: 0)

How far above `amount` a payment may be and still count as paid in full. Minor units.

**underpaymentTolerance** `integer` (default: 0)

How far below `amount` a payment may be and still count as paid in full. Minor units.

**metadata** `object`

Your own key-value data.

```bash cURL
curl -X POST "$PAYVE_API_URL/v1/payment-links" \
  -H "x-api-key: $PAYVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Invoice 1042",
    "description": "Design work, November",
    "amount": 5000000,
    "currency": "NGN",
    "expiresAt": "2026-12-01T00:00:00Z",
    "redirectUrl": "https://example.com/thanks",
    "underpaymentTolerance": 10000,
    "overpaymentTolerance": 10000
  }'
```

```javascript Node
const res = await fetch(`${process.env.PAYVE_API_URL}/v1/payment-links`, {
  method: 'POST',
  headers: {
    'x-api-key': process.env.PAYVE_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Invoice 1042',
    description: 'Design work, November',
    amount: 5000000,
    currency: 'NGN',
    expiresAt: '2026-12-01T00:00:00Z',
    redirectUrl: 'https://example.com/thanks',
    underpaymentTolerance: 10000,
    overpaymentTolerance: 10000,
  }),
});
const { data: link } = await res.json();
const checkoutUrl = `https://checkout.payvehq.com/pay/${link.slug}`;
```

```python Python
import os, requests

res = requests.post(
    f"{os.environ['PAYVE_API_URL']}/v1/payment-links",
    headers={"x-api-key": os.environ["PAYVE_API_KEY"]},
    json={
        "title": "Invoice 1042",
        "description": "Design work, November",
        "amount": 5000000,
        "currency": "NGN",
        "expiresAt": "2026-12-01T00:00:00Z",
        "redirectUrl": "https://example.com/thanks",
        "underpaymentTolerance": 10000,
        "overpaymentTolerance": 10000,
    },
)
link = res.json()["data"]
checkout_url = f"https://checkout.payvehq.com/pay/{link['slug']}"
```

```json Response · 201
{
  "data": {
    "id": 77,
    "merchantId": 318,
    "title": "Invoice 1042",
    "description": "Design work, November",
    "amount": "5000000",
    "currency": "NGN",
    "status": "active",
    "slug": "invoice-1042-k3x9qa",
    "redirectUrl": "https://example.com/thanks",
    "expiresAt": "2026-12-01T00:00:00.000Z",
    "overpaymentTolerance": "10000",
    "underpaymentTolerance": "10000",
    "metadata": {},
    "createdAt": "2026-11-18T09:00:00.000Z",
    "updatedAt": "2026-11-18T09:00:00.000Z"
  }
}
```

**id** `integer`

Use this in URLs: `GET /v1/payment-links/{id}`.

**slug** `string`

The last part of the checkout URL.

**status** `string`

`active`, `paid`, `inactive` or `expired`.

**amount** `string | null`

The fixed amount, or `null` for a link where the payer enters the amount.

## Fixed and open amounts

* **Fixed amount.** Set `amount`. The checkout charges exactly that. A payer cannot change it.
* **Open amount.** Leave `amount` out. The payer enters what they want to pay.

## What the payer sees

The hosted checkout shows your title, description and amount, then the payment methods you allowed. For a bank transfer it shows the account to pay into. For a card it collects the card and any PIN or one-time code. When the payment finishes it sends the payer to `redirectUrl` if you set one.

You never handle card numbers.

## Know when you are paid

Each payment through a link is a [pay-in](/guides/payins.md). Its `merchantReference` is `paylink-` followed by the link's slug, so you can match it to the link.

1. Receive `payin.successful`.
2. Match `data.merchant_reference`, for example `paylink-invoice-1042-k3x9qa`, to your link.
3. Fetch the pay-in and check `status` and `subStatus`.
4. Fulfil.

> [!WARNING]
>
> Do not treat the payer arriving at your `redirectUrl` as proof of payment. Anyone can open that
> URL. Fulfil only after the pay-in is `successful`.

## Overpayment and underpayment

A bank transfer can arrive for a different amount than the link asked for. On a fixed-amount link, Payve compares what arrived with `amount` and your two tolerances.

| What arrived | Pay-in result | Your wallet | The payer |
| - | - | - | - |
| Between `amount - underpaymentTolerance` and `amount + overpaymentTolerance` | `successful` | Credited what arrived, less fees | Nothing returned |
| More than `amount + overpaymentTolerance` | `successful`, `subStatus: overpaid` | Credited `amount`, less fees | The excess is refunded |
| Less than `amount - underpaymentTolerance` | `successful`, `subStatus: underpaid` | **Credited nothing** | The whole payment is refunded |

Both tolerances default to `0`: any difference, however small, counts as over or under.

> [!WARNING]
>
> An underpaid payment still reports `status: successful` and still sends `payin.successful`.
> Nothing was credited. Always check `subStatus` before you fulfil an order from a payment link.

> [!NOTE]
>
> The comparison uses the amount received after any transfer levy has been deducted. Set
> `underpaymentTolerance` high enough to cover such deductions, or an exact payment can be treated
> as short.

### How the refund reaches the payer

Payve creates a [refund](/guides/refunds.md) for the excess or for the whole short payment. If the paying account is known, the refund waits for Payve's review and is then sent there. If it is not known, the checkout asks the payer where to send it.

`GET /v1/refunds?payinTransactionId={id}` shows the refund for a pay-in.

Open-amount links have no expected amount, so no payment is over or under.

## Manage links

| Request | Does |
| - | - |
| `GET /v1/payment-links` | Lists your links. Filter with `status`. |
| `GET /v1/payment-links/{id}` | Returns one link. |
| `PATCH /v1/payment-links/{id}` | Changes `title`, `description`, `amount`, `currency`, `status`, `expiresAt`, `metadata` or a tolerance. |
| `DELETE /v1/payment-links/{id}` | Deletes the link. Returns `204`. |

`PATCH` and `DELETE` need the `payins:write` scope.

To stop a link taking payments without deleting it, set its `expiresAt` to a time in the past. An expired link's checkout page returns not found.

> [!WARNING]
>
> Deleting a link cannot be undone. Anyone who still has the URL will see a page that says the link
> was not found.

## Limits on the checkout

The hosted checkout allows 120 payment attempts per link and 20 per payer IP address in any 10 minutes. See [Rate limits](/essentials/rate-limits.md#hosted-checkout-limits).

## When it fails

| Status and code | Cause | Fix |
| - | - | - |
| `403 forbidden` | The key lacks `payins:write`. | Use a key with the scope. |
| `422 validation_missing_field` | `title` or `currency` is missing, or an amount is not a whole number. | Fix the fields named. |
| `404` | The link is not on your account. | Check the id. Use the numeric `id`. |
