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

# Creating a payment link and sending a buyer to pay

> Create a payment link, send a buyer to pay it, and optionally create a buyer session that returns the buyer to your site.

You always need one session to create a payment link. You need a second session only if you want Meridian to send the buyer back to your site after paying. Both come from [Create a Session](https://docs.mnai.com/products/realtime-collections/api-reference/sessions/create-session.md), and the fields you send decide what each one can do.

| Session | Fields | What it can do |
| :- | :- | :- |
| Creation session (always) | `operatorId`, `operatorName` | Create payment links |
| Buyer session (only for a redirect) | `operatorId`, `operatorName`, `paymentLinkId`, `redirectUrl` | Let a buyer pay one link, then send them to `redirectUrl` |

> [!NOTE]
>
> Without a redirect, skip step 3 and send the buyer to the link URL with no `sessionKey`. The payment page creates its own 15-minute session.

Make every call from your backend, signed as described in [Authentication](https://docs.mnai.com/products/realtime-collections/authentication.md).

## Why two sessions

You put the buyer session key in the URL you send the buyer to. That puts it in the buyer's browser, so Meridian limits what it can do:

* **It pays one link only.** The session is tied to the `paymentLinkId` you set. It cannot create payment links or pay a different link.
* **It expires after 15 minutes.** The buyer must pay within that time. A copied or leaked key stops working soon after.

The creation session stays on your backend, so it is the only one that can create links.

This is also why `redirectUrl` cannot go on the creation session. `redirectUrl` requires `paymentLinkId`, and the link does not exist until you create it.

## Create and send a link

**1. Create a session**

Call [Create a Session](https://docs.mnai.com/products/realtime-collections/api-reference/sessions/create-session.md) with your operator details only.

```json Request theme={null}
POST /v1/payment-links/sessions

{
  "operatorId": "op-123",
  "operatorName": "Carlos Tester"
}
```

```json Response theme={null}
{
  "sessionKey": "ussandbox-b1x2k0dzsbpc4cz8c8xrvfel",
  "expiresAt": "2026-07-02T20:45:50Z"
}
```

The key lasts 15 minutes. You can create more than one link with it before it expires.

**2. Create the link**

Call [Create a Payment Link](https://docs.mnai.com/products/realtime-collections/api-reference/payment-links/create-payment-link.md) with the creation session's `sessionKey` in the body.

```json Request theme={null}
POST /v1/payment-links

{
  "recurrenceType": "SINGLE",
  "referenceId": "REF-ONEOFF-2",
  "referenceLabel": "One-off USD",
  "creditAmount": "100.50",
  "debitCurrency": "USD",
  "creditCurrency": "USD",
  "endDate": "2027-01-31",
  "sessionKey": "ussandbox-b1x2k0dzsbpc4cz8c8xrvfel"
}
```

```json Response theme={null}
{
  "paymentLink": {
    "id": "usmer-kiqt7rz1qvwqnryhvbqf463q",
    "linkToken": "de4261dd-548a-4cbc-9f48-9d13924e3d7d",
    "status": "ACTIVE",
    "referenceId": "REF-ONEOFF-2",
    "...": "..."
  }
}
```

Store the link's `id` and `linkToken`. You need both in the next steps.

> [!NOTE]
>
> Create a Payment Link does not take `redirectUrl`. You set it on the buyer session in the next step.

**3. Create a buyer session (optional)**

Skip this step if you do not need a redirect.

When the buyer clicks Pay on your site, call Create a Session again. Set `paymentLinkId` to the link's `id`, and `redirectUrl` to the page the buyer returns to.

```json Request theme={null}
POST /v1/payment-links/sessions

{
  "operatorId": "op-123",
  "operatorName": "Carlos Tester",
  "paymentLinkId": "usmer-kiqt7rz1qvwqnryhvbqf463q",
  "redirectUrl": "https://portal.merchant.com/payments/return"
}
```

```json Response theme={null}
{
  "sessionKey": "ussandbox-x9f4m2qtv7kd3wz8n5hrc6ya",
  "expiresAt": "2026-07-02T21:02:10Z"
}
```

`redirectUrl` must be an `https` URL of at most 2048 characters. It is optional.

Meridian checks `paymentLinkId` only when the buyer opens the payment page. A wrong or inactive link ID still returns `201`, and the payment page then rejects the session.

Create the buyer session at the moment the buyer clicks Pay, not when you create the link. The 15 minutes start when you create the session.

**4. Send the buyer to pay**

Build the payment URL from your payment domain and the link's `linkToken`. Your Solutions Engineer gives you the payment domain for Sandbox and production.

> [tab] Without a redirect
>
> ```text theme={null}
> https://<payment-domain>/de4261dd-548a-4cbc-9f48-9d13924e3d7d
> ```

> [tab] With a redirect
>
> Add the buyer session key from step 3:
>
> ```text theme={null}
> https://<payment-domain>/de4261dd-548a-4cbc-9f48-9d13924e3d7d?sessionKey=ussandbox-x9f4m2qtv7kd3wz8n5hrc6ya
> ```
>
> After the buyer pays, Meridian sends them to `redirectUrl`.

**5. Confirm the payment**

The redirect does not mean the payment completed. Wait for the `payment_link_transaction_succeeded` webhook before you mark the order paid. See [Track payments](https://docs.mnai.com/products/realtime-collections/tracking-payments-with-webhooks.md).

## Session expiry

If the buyer does not pay within 15 minutes of you creating the buyer session, the payment page rejects it. The payment link is not affected. When the buyer clicks Pay again, create a new buyer session for the same link and send them to the new URL.
