With Verify

Use this guide if you need to verify the customer's age as part of the payment flow.

ePay Verify lets you add age verification directly to ePay Checkout. This is useful when selling age-restricted products where you need to confirm that the customer meets a required minimum age before the payment can be completed.

Verify works as part of the payment session. Your backend creates a payment session with age verification requirements, and ePay handles the verification flow in Checkout.

What you will build

In this guide, you will:

How Verify works

Verify adds an age verification requirement to a payment session.

The basic flow is:

How the verification is handled depends on the selected payment method.

For MobilePay, ePay can use available age information from MobilePay/Vipps. If the customer does not meet the age requirement, the payment is declined in the MobilePay/Vipps flow.

For cards and other payment methods, the customer may be asked to verify their age with MitID in Checkout. If the verification succeeds, the customer can continue the payment. If the verification fails, the payment cannot be completed.

Example: Start age verification before payment

This example creates a payment session with age verification and shows a button that starts the verification flow.

// -------------------------------// 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",  ageVerification: {    minimumAge: 18,    country: "DK",  },};// Setup the fetch optionsconst requestOptions = {  method: "POST",  headers: headers,  body: JSON.stringify(paymentData),  redirect: "follow",};// -------------------------------// Helper: Create Verify Button// -------------------------------function createVerifyButton() {  const button = document.createElement("button");  button.id = "payment-button";  button.textContent = "Verify age and continue to payment";  document.body.appendChild(button);  return button;}// -------------------------------// Helper: Dynamically Load External Module// -------------------------------/** * Dynamically loads an external script module. * * @param {string} scriptUrl - The URL of the external module. * @param {Function} onLoadCallback - A callback function to run once the module loads. */function loadExternalModule(scriptUrl, onLoadCallback) {  const scriptEl = document.createElement("script");  scriptEl.type = "module";  scriptEl.src = scriptUrl;  scriptEl.onload = onLoadCallback;  document.body.appendChild(scriptEl);  console.log("Dynamically loading external script:", scriptUrl);}// -------------------------------// Payment Request & Hosted Fields Initialization// -------------------------------fetch("https://payments.epay.eu/public/api/v1/cit", requestOptions)  .then((response) => response.json())  .then((result) => {    console.log("Payment response:", result);    // Extract session and payment details from the response    const sessionId = result.session.id;    const sessionKey = result.key;    const paymentWindowLink = result.paymentWindowUrl;    const button = createVerifyButton();    // Dynamically load the external payment module using the URL from the response    loadExternalModule(result.javascript, () => {      // Initialize hosted fields with session data and callbacks      epay.setSessionId(sessionId).setSessionKey(sessionKey).init();      button.addEventListener("click", () => {        epay.startAgeVerification({          successUrl: paymentWindowLink,          failureUrl: paymentWindowLink,        });      });    });  })  .catch((error) => {    console.error("Error during payment request:", error);  });

Before you start

You need:

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",  requiresAgeVerification: true,  minimumAge: 18,});

The order should not be marked as paid yet.

Step 2: Create a payment session with age verification

Create a payment session from your backend and include the ageVerification object.

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",  "ageVerification": {    "minimumAge": 18,    "country": "DK"  }})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 own order reference so you can match the ePay payment 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 initializing a payment session.

The ageVerification object tells ePay that the customer must meet a minimum age before the payment can be completed.

Step 4: Understand the age verification object

Use:

• ageVerification.minimumAge for the required minimum age. It must be between 0 and 99.
• ageVerification.country for the delivery country as an ISO 3166 alpha-2 country code such as DK.

The country determines which electronic ID flow is presented to the customer. For Denmark, this is MitID.

Step 5: Redirect the customer to Checkout

The response contains the information needed to open ePay Checkout.

Redirect the customer to the payment window URL returned by ePay.

return redirect(payment.paymentWindowUrl);

The customer now completes the age verification and payment in the ePay-hosted payment page.

Step 6: Complete a test payment

Open Checkout and complete the payment using a test payment method.

If age verification is required, the customer must complete the verification before the payment can continue.

A successful 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

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: Avoid repeated age checks for returning customers

For returning customers, you may want to avoid asking for age verification every time they make a purchase.

There are two common ways to do this:

If you store the result in your own system, associate the verification outcome with the customer's profile and use it when deciding whether future payments require age verification.

If you send a unique customerId, ePay can associate the verification result with that customer and reuse it for future payments with the same customer ID.

{  "customerId": "CUSTOMER-1001",  "ageVerification": {    "minimumAge": 18,    "country": "DK"  }}

Common problems

I get unauthorized when creating the payment

Check that:

The customer is not asked to verify age

Check that:

The payment is declined during age verification

Check that:

The customer returns, but my order is not paid

Check that:

Returning customers are asked to verify age again

Check that:

What you built

You have now created your first ePay Verify payment.

You created a payment session with age verification, redirected the customer to ePay Checkout, completed the verification flow and handled the payment result server-side.

Next steps

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