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