With Checkout

Use this guide if you want ePay to host the payment window.

Checkout is the simplest custom integration. Your backend creates a payment session, and ePay returns a payment window URL. You redirect the customer to that URL so they can complete the payment.

What you will build

In this guide, you will:

How Checkout works

Checkout uses a hosted payment window.

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

The basic flow is:

Example: Open the hosted Checkout page

This example creates a payment and shows a button that opens the returned Checkout URL.

// -------------------------------// 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, // minor amount  currency: "DKK"};// Setup the fetch optionsconst requestOptions = {  method: "POST",  headers: headers,  body: JSON.stringify(paymentData),  redirect: "follow"};// -------------------------------// Helper: Create Payment Window Button// -------------------------------function ensureCheckoutDemoLayout() {  const existingRoot = document.getElementById("payment-link-root");  if (existingRoot) return existingRoot;  const main = document.createElement("main");  main.className = "checkout-demo";  const card = document.createElement("div");  card.className = "checkout-demo__card";  const eyebrow = document.createElement("p");  eyebrow.className = "checkout-demo__eyebrow";  eyebrow.textContent = "Hosted checkout example";  const root = document.createElement("div");  root.id = "payment-link-root";  card.appendChild(eyebrow);  card.appendChild(root);  main.appendChild(card);  document.body.appendChild(main);  return root;}/** * Creates and appends a payment button to the DOM. * The button text is set dynamically using the converted amount (major) and currency. * * @param {number} amount - The payment amount (in minor units). * @param {string} currency - The currency code. * @param {string} paymentWindowLink - Link to the ePay Payment Window. */function createPaymentLink(amount, currency, paymentWindowLink) {  // Convert minor amount to major amount (e.g., 100 -> 1.00)  const majorAmount = (amount / 100).toFixed(2);  const paymentLink = document.createElement("a");  paymentLink.classList.add("payment-link");  paymentLink.textContent = `Pay ${majorAmount} ${currency}`;  paymentLink.href = paymentWindowLink;  paymentLink.target = "_blank";  const root = ensureCheckoutDemoLayout();  root.appendChild(paymentLink);}// -------------------------------// Payment Request// -------------------------------fetch("https://payments.epay.eu/public/api/v1/cit", requestOptions)  .then((response) => response.json())  .then((result) => {    console.log("Payment response:", result);    // Extract Payment details from the response    const amount = result.session.amount;    const currency = result.session.currency;    const paymentWindowLink = result.paymentWindowUrl;    // Create the payment link using dynamic payment details    createPaymentLink(amount, currency, paymentWindowLink);  })  .catch((error) => {    console.error("Error during payment request:", error);  });

Before you start

You need:

For the standard Checkout redirect flow, your backend authenticates the session creation request with your API key.

Step 1: Create an order in your system

Before creating the payment in ePay, create an order 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 session

Create a payment session 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",  "scaMode": "NORMAL",  "timeout": 60,  "instantCapture": "OFF",  "maxAttempts": 3})fetch("https://payments.epay.eu/public/api/v1/cit", {  method: "POST",  headers: {    "Content-Type": "application/json",    "Authorization": "Bearer <TEST_API_KEY>",    "Idempotency-Key": "<UUID>"  },  body})

Use your actual ePay endpoint and the fields your checkout flow requires.

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 initializing a payment session.

Step 4: Inspect the response

The response contains the values needed to continue the flow.

For Checkout, the important field is paymentWindowUrl, because that is the URL you redirect the customer to. The javascript and key fields are mainly relevant for Blocks or other embedded flows. If you set generateQrCode to true, the response also includes qrCode.

{  "paymentWindowUrl": "https://payments.epay.eu/payment-window?sessionId=0192473a-e382-79a9-bfc2-65da88fe812f&sessionKey=4651656e-f29e-4dfa-a1cd-a65647862011",  "javascript": "https://payments.epay.eu/sessions/0192473a-e382-79a9-bfc2-65da88fe812f/client.js",  "key": "4651656e-f29e-4dfa-a1cd-a65647862011",  "session": {    "id": "0192473a-e382-79a9-bfc2-65da88fe812f",    "subscriptionId": "01929a94-5fce-7ccc-a7e4-7e9249133b39",    "amount": 1000,    "attributes": { "key1": "value1", "key2": "value2" },    "exemptions": ["TRA"],    "currency": "DKK",    "instantCapture": "OFF",    "maxAttempts": 3,    "reportFailure": false,    "dynamicAmount": false,    "pointOfSaleId": "0192473a-e381-705c-b61c-fc2ac9624afc",    "reference": "ORDER-1001",    "state": "PENDING",    "scaMode": "NORMAL",    "timeout": 60,    "notificationUrl": "https://example.com/api/epay/notification",    "preAuthUrl": "https://example.com/pre-auth",    "successUrl": "https://example.com/payment/success",    "failureUrl": "https://example.com/payment/failure",    "textOnStatement": "The text",    "createdAt": "2024-10-01T10:38:14.658688472+02:00",    "expiresAt": "2024-10-01T12:41:14.658688472+02:00"  }}

Step 5: Redirect the customer

The response contains the information needed to open the payment window.

Redirect the customer to the payment window.

return redirect(payment.paymentWindowUrl);

The customer now completes the payment on the ePay-hosted payment page.

Optional: Use URL templating

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

This is especially useful for notificationUrl, successUrl, failureUrl, retryUrl, and returnUrl.

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.reference}"}

Supported template values include:

Unknown template keys are rejected during request validation.

Optional: Override the default payment window

In some cases, you may want to use a specific payment window configuration instead of the default configuration defined on your Point of Sale.

This lets you choose another visual or functional checkout setup for a single payment session without changing the POS defaults in the ePay backoffice.

When you append paymentWindowId to the returned paymentWindowUrl, the payment window configuration associated with that ID is used instead of the POS default, as long as the payment window belongs to the same account as the session.

Common use cases:

• Apply campaign-specific branding or themes
• Use a simplified flow for selected customer groups
• Test a new payment window configuration without updating the POS default

Example:

https://payments.epay.eu/payment-window?sessionId=0192473a-e382-79a9-bfc2-65da88fe812f&sessionKey=4651656e-f29e-4dfa-a1cd-a65647862011&paymentWindowId=01234567-89ab-cdef-0123-456789abcdef

Important notes:

• The provided paymentWindowId must belong to the same account as the Point of Sale used for the payment session.
• If paymentWindowId is invalid or does not exist, the default payment window configuration is used.
• The override happens entirely by modifying the returned paymentWindowUrl; you do not need to change the session initialization request.

Step 6: Complete a test payment

Use a test card to complete the payment.

A successful test payment should redirect the customer to your success URL.

A failed payment should redirect the customer to your failure URL or allow the customer to try again, depending on your setup.

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.

Common problems

I get unauthorized when creating the payment

Check that:

If the request still fails, use the error code and response body to identify whether the issue is authentication, validation, or Point of Sale configuration.

The payment window does not open

Check that:

The customer returns, but my order is not paid

Check that:

What you built

You have now created your first ePay Checkout payment.

You created a payment session from your backend, redirected the customer to ePay and completed a test payment.

Next steps

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