With Link

Use this guide if you want to create a payment link that can be sent to a customer or displayed as a QR code.

Link is a fast way to accept payments without building a full checkout flow. Your backend creates a payment link, and ePay returns a unique URL and a base64-encoded QR code that opens ePay Checkout.

You can also create a Link directly from the ePay backoffice for manual payment flows.

You can send the link by email, SMS, invoice, chat, or show the QR code on-screen.

What you will build

In this guide, you will:

How Link works

Link creates a hosted payment session that can be opened through a URL or QR code.

Your system creates the payment link. ePay handles the payment page.

The basic flow is:

Example: Send a payment link or show it as a QR code

This is a simple example of how the returned payment link can be presented to the customer.

// -------------------------------// Payment Request Setup// -------------------------------// Create headers for the payment requestconst headers = new Headers();const demoApiKey = "test_93dc98ae-ff87-4671-a821-cda33fdfc26e"; // Demo API key: NEVER use this client-side in productionheaders.append("Content-Type", "application/json");headers.append("Accept", "application/json");headers.append("Authorization", `Bearer ${demoApiKey}`);// Define the payment payload dataconst paymentData = {  pointOfSaleId: "0195a362-5bf4-7bb9-a419-2367fda11e6f",  amount: 100, // amount in minor units (e.g. øre)  currency: "DKK",};// Setup the fetch optionsconst requestOptions = {  method: "POST",  headers: headers,  body: JSON.stringify(paymentData),  redirect: "follow",};// -------------------------------// Helper: Render Link + QR Code// -------------------------------/** * Renders a clickable link and a QR code inside a container. * * @param {string} url - The payment URL. * @param {string} qrBase64 - The QR code as a Base64 string. */function renderPaymentLinkAndQr(url, qrBase64) {  // Create a wrapper div  const container = document.createElement("div");  container.classList.add("payment-container");  // Create the link element  const linkEl = document.createElement("a");  linkEl.classList.add("payment-link");  linkEl.href = url;  linkEl.target = "_blank";  linkEl.textContent = url; // display the URL itself (you can customize to 'Pay Here' if you prefer)  container.appendChild(linkEl);  // Create the QR code image element  const imgEl = document.createElement("img");  imgEl.classList.add("payment-qr");  imgEl.src = `data:image/png;base64,${qrBase64}`;  imgEl.alt = "Payment QR Code";  container.appendChild(imgEl);  // Append the entire container to the body  document.body.appendChild(container);}// -------------------------------// Request to /payment-links// -------------------------------fetch("https://payments.epay.eu/public/api/v1/payment-links", requestOptions)  .then((response) => {    if (!response.ok) throw new Error(`HTTP ${response.status}`);    return response.json();  })  .then((result) => {    console.log("Payment-links response:", result);    // Expect result to have { url: "...", qrCode: "base64..." }    const { url, qrCode } = result;    // Render the payment link and QR code    renderPaymentLinkAndQr(url, qrCode);  })  .catch((error) => {    console.error("Error during payment-links request:", error);    // Optionally display an error message in the UI  });

Before you start

You need:

Step 1: Create an order in your system

Before creating the payment link in ePay, create an order or payment request in your own system.

Set the order status to pending.

const order = await createOrder({  amount: 10000,  currency: "DKK",  status: "pending",});

The order should not be marked as paid yet.

Step 2: Create a payment link

Create a payment link from your backend.

const body = JSON.stringify({  "pointOfSaleId": "<POINT_OF_SALE_ID>",  "amount": 10000,  "currency": "DKK",  "reference": "ORDER-1001",  "notificationUrl": "https://example.com/api/epay/notification",  "successUrl": "https://example.com/payment/success",  "failureUrl": "https://example.com/payment/failure"})fetch("https://payments.epay.eu/public/api/v1/payment-links", {  method: "POST",  headers: {    "Content-Type": "application/json",    "Authorization": "Bearer <TEST_API_KEY>",    "Idempotency-Key": "<UUID>"  },  body})

Use your own order reference so you can match the ePay payment link to the order in your system.

Step 3: Understand the request body

pointOfSaleId, amount, and currency are always required in the request body.

The full schema below also includes advanced fields such as customer, orderLines, subscription, allowedPaymentMethods, returnUrl, retryUrl, generateQrCode, reportExpired, dynamicAmount, and ageVerification.

The table below covers the request fields used when creating a payment link.

The reference should make it easy to match the payment link to the order in your own system.

Step 4: Inspect the response

The response contains the created payment link and a QR code.

{  "id": "KSNMWEWZPPA",  "sessionId": "01975f11-329f-7c14-a03a-3739d8b48ef3",  "url": "https://payments.epay.eu/link/KSNMWEWZPPA",  "qrCode": "/9j/2wCEAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDA..."}

You can now send the url to the customer or display the qrCode.

Step 5: Send or display the payment link

How you use the payment link depends on your flow.

Common examples:

• Send the link by email
• Send the link by SMS
• Add the link to an invoice
• Show the link in your own admin system
• Display the QR code on-screen
• Print the QR code on a document or receipt

Example:

await sendPaymentEmail({  to: customer.email,  orderReference: order.reference,  paymentUrl: paymentLink.url,});

If you display the QR code, decode the base64 value and render it as an image in your frontend.

<img  src={`data:image/png;base64,${paymentLink.qrCode}`}  alt="Scan to pay"/>

Step 6: Complete a test payment

Open the payment link and use a test card to complete the payment.

A successful test payment should redirect the customer to your success URL if one was provided.

A failed payment should redirect the customer to your failure URL when no more payment attempts are allowed.

Step 7: Handle the payment result

The customer may close the browser before returning to your website.

Use your notification URL or webhook to update the order in your backend.

Do not mark the order as paid only because the customer lands on your success page.

Recommended order flow:

Step 8: Show the final status to the customer

Your success page should show the customer that the payment was completed or is being confirmed.

If your backend has not processed the payment result yet, show a neutral message such as:

Your payment has been received and is being confirmed.

Avoid showing a final paid state before your backend has confirmed the payment result.

Optional: Set a custom expiry

Payment links expire after 60 days by default.

You can define a custom timeout in minutes.

{  "timeout": 1440}

The example above makes the payment link valid for 24 hours.

The minimum timeout is 10 minutes.

If the customer opens the payment window and leaves it open, the active checkout session can expire before the payment link itself expires. If that happens, the customer can open the payment link again as long as the payment link is still valid.

Optional: Use URL templating

Redirect and notification URLs can include dynamic values from the session or transaction.

Example:

{  "successUrl": "https://example.com/payment/success/${transaction.id}",  "failureUrl": "https://example.com/payment/failure/${session.id}",  "notificationUrl": "https://example.com/api/epay/notification/${transaction.id}"}

Supported template values include:

Unknown template keys are rejected during request validation.

Optional: Advanced payment link settings

The payment link API supports additional settings for more advanced payment flows.

Examples include:

For your first payment link, start with the required fields and add advanced settings only when your payment flow needs them.

Common problems

I get unauthorized when creating the payment link

Check that:

The payment link does not open

Check that:

The QR code does not work

Check that:

The customer returns, but my order is not paid

Check that:

The payment link expires too soon

Check that:

What you built

You have now created your first Link payment.

You created a payment link from your backend, received a payment URL and QR code, and completed a test payment through ePay Checkout.

Next steps

• Test successful and failed payments
• Handle payment results
• Go live