2. Server side initialization

Base url: https://payments.epay.eu

Making the initialization request

To start a new payment session, make a server-side HTTP request to the ePay Payments API using a valid ApiKey. This ensures your key is never exposed to the client.

Some session parameters can be predefined in the ePay backoffice under Advanced Point of Sale Settings, allowing you to manage defaults without changing your code. Values sent in the API request will always override these defaults.

Below is an example of the JSON data required to initialize a new payment session.

To view all available fields, visit the API documentation.

POST /public/api/v1/cit
{
  "pointOfSaleId": "01924737-9c18-71c0-ab1a-88698eaceabf",
  "amount": 1000,
  "currency": "DKK",
  "scaMode": "SKIP",
  "timeout": 60,
  "instantCapture": "OFF",
  "processor": ["shift4", "clearhaus", "nets"],
  "exemptions": ["TRA"],
  "maxAttempts": 10,
  "notificationUrl": "https://example.com/notification",
  "successUrl": "https://example.com/success",
  "failureUrl": "https://example.com/failure"
}

Name	Type	Description	Required
`pointOfSaleId`	uuid	Id of the point of sale to associate the payment with.	True
`amount`	int	This is the amount of the payment. The amount must be defined in minor units. E.g. 2,50 DKK must be set as 250. If amount is set to 0 a token will be created only and returned to the integrator.	True
`currency`	string	The currency code of the payment, represented using the ISO 4217 alpha-3 standard (e.g., DKK for Danish Kroner).	True
`scaMode`	string	How 3D secure is handled: `SKIP` 3DS is not tried and full liability is put at merchant. `NORMAL` 3DS flow is attempted as normal guidelines suggests - Both challenge and frictionless can occur. `FORCE` A challenge flow is forced. Note: Third parties in the 3DS flow might ignore this instruction.	False*
`timeout`	int	The session is valid for the specified number of minutes. If a timeout occurs, the session expires and not more payment attempts are possible. Minimum value `1` Max value is `120`	False*
`instantCapture`	string	If the payment should be captured instantly or not. `OFF` indicates that the payment should not be captured instantly. `VOID` indicates that the payment should be captured instantly and if somehow the instant capture fails the payment is voided. `NO_VOID` indicates that the payment should be captured instantly and if the capture fails the authorization is kept (no void is made)	False*
`processor`	string array	List of processors to use. This is the routing of the payment. The value can be `shift4`, `clearhaus` and `nets`. The priority of the processors is made on the order. That means that if the first processor fails / declines then the next in the list will be used and so on until all processors in the list have been tried.	False*
`exemptions`	string array	List of exemptions to apply when applicable. Supports [TRA, LVT]. Note: Using exemptions may shift liability for fraud from the issuer to the merchant.
`maxAttempts`	int	The maximum allowed number of payment attempts for the session. Minimum value `1` Maximum value is `25`	False*
`notificationUrl`	uri	The URL to where ePay notifies about payment statuses.	False*
`successUrl`	uri	The URL the client is redirected to on a successful payment.	False*
`failureUrl`	uri	The URL the client is redirected to when no more payment attempts are allowed.	False*

*Required fields

In the ePay backoffice in the advanced Point of Sale settings you can set the default for many of the session initialization parameters, allowing you to change your setup from the interface without updating your code. Properties must be defined in either the point of sale settings or the API request. The API request takes precedence and overwrites any point of sale settings if present.

info

Acquirer fallback is not yet implemented. Only the first acquirer will be attempted.

warning

Many acquirers does not accept payments without any 3DS data. For this reason it is strongly discouraged to use scaMode: "SKIP".

Only use for tests.

Response
{
  "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",
    "expiresAt": "2024-10-01T12:41:14.658688472+02:00",
    "instantCapture": "OFF",
    "maxAttempts": 10,
    "reportFailure": false,
    "dynamicAmount": false,
    "notificationUrl": "https://example.com/notification",
    "preAuthUrl": "https://example.com/pre-auth",
    "successUrl": "https://example.com/success",
    "failureUrl": "https://example.com/failure",
    "pointOfSaleId": "0192473a-e381-705c-b61c-fc2ac9624afc",
    "reference": "reference-1",
    "state": "PENDING",
    "textOnStatement": "The text",
    "scaMode": "SKIP",
    "timeout": 60,
    "createdAt": "2024-10-01T10:38:14.658688472+02:00"
  }
}

Name	Description
`paymentWindowUrl`	This is the direct url to access an ePay supplied payment window for your payment session.
`javascript`	This is the JavaScript client source to include in the merchant payment window.
`key`	The session unique client secret used to authenticate client side calls to the payment system.
`session`	Representation of the session created within the ePay system.

URL Templating

All URL properties support dynamic templating with session and transaction data, allowing merchants to define URLs that include ePay-generated resource ID's.

This feature can be particularly helpful for some merchants, especially with success and failure URLs, as it simplifies fetching order information upon transaction completion.

Unknown template keys will be rejected during request validation.

Key	Description
`${transaction.id}`	The primary id of the associated transaction.
`${transaction.reference}`	The merchant supplied reference from session init.
`${session.id}`	The primary id of the associated session.

Example

Before

https://example.com/epay/transaction/${transaction.id}/notification

After

https://example.com/epay/transaction/01924756-d1f6-7bc6-bb51-2b5f87b43925/notification

Overriding the default Payment Window

In some cases, you might want to use a specific payment window configuration instead of the default configuration defined on your Point of Sale (POS). This allows you to dynamically choose a different visual or functional setup for individual payment sessions without changing your POS settings in the ePay backoffice.

To override the default payment window, you can include a paymentWindowId query parameter in the paymentWindowUrl returned from the session initialization response.

How it works

When you append the paymentWindowId query parameter to the paymentWindowUrl, and set it to the ID of a valid payment window belonging to the same account as the payment session, the payment window configuration associated with that ID will be used instead of the POS’s default configuration.

This enables you to tailor the checkout experience on a per-session basis, for example to:

Apply special branding or themes for certain campaigns.
Use a simplified payment flow for recurring customers.
Test new payment window designs without updating your POS configuration.

Example usage

Receive the paymentWindowUrl from your initialization response, e.g.:

https://payments.epay.eu/payment-window
?sessionId=0192473a-e382-79a9-bfc2-65da88fe812f
&sessionKey=4651656e-f29e-4dfa-a1cd-a65647862011

Append your desired paymentWindowId:

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

In this example, 01234567-89ab-cdef-0123-456789abcdef is the ID of the payment window you want to use for this specific session.

Important notes

The provided paymentWindowId must belong to the same account as the POS used for the payment session. Otherwise, the override will be ignored and the default POS configuration will apply.
If the paymentWindowId is invalid or does not exist, the default payment window will be used.
This feature requires no changes to your session initialization request — the override happens entirely by modifying the returned paymentWindowUrl.

Making the initialization request​

URL Templating​

Example​

Overriding the default Payment Window​

How it works​

Example usage​

Important notes​