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

# Take a Payment with a Payment Link

> Create a link, send it to the customer, and follow its payment transactions

A payment link is a page that takes payment without an integration, by URL or by QR code. You send the link to the customer yourself.

| # | Step | Who |
| - | - | - |
| 1 | Create the link | API |
| 2 | Send `checkout.url` to the customer | You |
| 3 | The customer opens the link and pays | **Customer** |
| 4 | List the link's payment transactions | API, polling |
| 5 | Read the link | API |

Payment transactions through a payment link send no webhook events, so step 4 polls.

## 1. Create the Link

```bash theme={null}
curl -X POST 'https://api.quidkey.com/v1/merchants/m_1/payment-links' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Idempotency-Key: "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f"' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": { "value": 4200, "currency": "EUR" },
    "type": "single_use",
    "statement_descriptor": "Example Store",
    "order": { "order_id": "INV-2042" }
  }'
```

The answer is 201, with the link at `status: active`, its `checkout` page and a `qr_code` of the page's URL, usable in a plain `<img>`.

* `type` is `single_use`, which is paid once, or `reusable`.
* `expires_at` defaults to 7 days from now, and can be from 60 seconds to 1 year ahead.
* `success_url` and `failure_url` are optional, as a pair.
* Without `is_test: true`, the link is live, which answers 409 `LIVE_PAYMENTS_NOT_ALLOWED` for a merchant that isn't live yet.
* Make one `Idempotency-Key` for each link you mean to send, and store it with the invoice or order before you send the request. A retry with a new key makes a second link, which a customer can also pay. See [Idempotency](https://docs.quidkey.com/api-v1/standards/idempotency.md#choosing-a-key).

Unlike a payment transaction's checkout, a link's `checkout` and `qr_code` can be read again while the link is open, so you can print or resend them. Treat them as secrets all the same: anyone holding the URL can pay.

## 2. Send the Link

Send `checkout.url` to the customer, by email or message, or show the QR code.

## 3. The Customer Pays

The customer opens the link, gives their details, chooses their bank and pays. **Customer.**

## 4. List the Link's Payment Transactions

```bash theme={null}
curl 'https://api.quidkey.com/v1/merchants/m_1/transactions?payment_link_id=pl_1' \
  -H 'Authorization: Bearer ACCESS_TOKEN'
```

The list holds every attempt through the link, including abandoned and cancelled ones, newest first. For a test link, add `is_test=true`. Each payment transaction carries the link's `order`.

## 5. Read the Link

```bash theme={null}
curl 'https://api.quidkey.com/v1/payment-links/pl_1' \
  -H 'Authorization: Bearer ACCESS_TOKEN'
```

| `status` | Meaning |
| - | - |
| `active` | Open for payment. |
| `used` | A single-use link that took a payment transaction. `checkout` and `qr_code` are `null`. The payment transaction can still be in progress, so read the link's transactions for how it went. |
| `expired` | Past `expires_at`. A payment transaction started before then can still finish, and a single-use link it pays then reads `used`. |

`view_count` and `first_viewed_at` say whether the customer has opened the page.


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