2. Server side initialization

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

Initializing a new payment session is done by making an HTTP request to the Epay Payments API. This can be done using any http client.

Making the initialization request

Initializing a new payment session requires a valid ApiKey, and must be done as a server-side request to make sure the ApiKey is never exposed client-side.

Below is an example of the JSON data, which needs to be transmitted to ePay to initialize a new payment session.

POST /public/api/v1/cit
{
  "pointOfSaleId": "01924737-9c18-71c0-ab1a-88698eaceabf",
  "reference": "reference-1",
  "amount": 1000,
  "currency": "DKK",
  "scaMode": "SKIP",
  "timeout": 60,
  "instantCapture": "OFF",
  "processor": ["shift4", "clearhaus", "nets"],
  "exemptions": ["TRA"],
  "textOnStatement": "The text",
  "attributes": { "key1": "value1", "key2": "value2" },
  "customerId": "User159",
  "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",
  "subscription": {
    "type": "SCHEDULED",
    "reference": "subscription-1",
    "expiryDate": "2050-01-01",
    "interval": {
      "period": "MONTH",
      "frequency": 1
    }
  }
}

Name	Description	Required
`pointOfSaleId`	Id of the point of sale to associate the payment with.	True
`amount`	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`	The currency code of the payment. For Danish Kroner defined as DKK.	True
`reference`	This is the order reference like an order id.	False
`scaMode`	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`	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`	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`	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`	List of exemptions to apply when applicable. Valid values: `TRA` - Transaction Risk Analysis	False
`textOnStatement`	This is the text set on the transaction in the bank viewed by the card holder. That can be e.g. "order 123".	False
`attributes`	A list of pass through attributes that is sent back to the merchant on webhooks.	False
`customerId`	An optional merchant defined customer id used to uniquely identify a user in the merchant system. This field is required to enable stored payment methods and enhanced age verification.	False
`maxAttempts`	The maximum allowed number of payment attempts for the session. Minimum value `1` Maximum value is `25`	False*
`reportFailure`	If true: Enables webhooks to the `notificationUrl` for failed transactions. Otherwise only successful transactions are reported.	False
`dynamicAmount`	If true: Enables the cardholder to define the transaction amount. Otherwise, the amount from the session is used for transactions. Can be used in conjunction with pre-auth webhooks to reject transactions with unacceptable amounts. NOTE: This gives client side control over the payment amount. Only use if necessary.	False
`notificationUrl`	The URL to where ePay notifies about payment statuses.	False*
`preAuthUrl`	If not null then pre-authorization webhook are enabled for all transaction attempts for the session.	False
`successUrl`	The URL the client is redirected to on a successful payment.	False*
`failureUrl`	The URL the client is redirected to when no more payment attempts are allowed.	False*
`subscription`	Optional object. Is required to initialize a subscription for later MIT transactions. Note `scaMode` is always set to `FORCE` when initializing a subscription.	False
`subscription.id`	An optional subscription ID can be used to update an existing active subscription with new payment details, such as a new card or a completely different payment method.	False
`subscription.amount`	An optional amount that can be used to differentiate the recurring subscription amount from the current transaction amount. This is useful if customers are not expected to pay today, but must pay a monthly fee going forward - In this case set amount=0 and subscription.amount=XXX. Defaults to the transaction amount if not given.	False
`subscription.type`	The type of subscription. `UNSCHEDULED` Pay-as-you-go type subscriptions with no fixed interval for charges. `SCHEDULED` Fixed interval charges like a subscription paid monthly.	True
`subscription.reference`	An optional merchant defined reference for the subscription. If none is given, then the session reference will be used as a fallback.	False
`subscription.expiryDate`	An optional field indicating the expiry of the subscription. This date is used during 3DS, and may improve conversion rates. ePay does not reject payments after this date.	False
`subscription.interval`	An optional subscription schedule for `SCHEDULED` type subscriptions. Must be omitted for `UNSCHEDULED` type subscriptions. Is required by some payment methods such as Vipps-Mobilepay. Is used during 3DS - May improve conversion rates.	False
`subscription.interval.period`	The period unit between charges: `DAY`, `WEEK`, `MONTH`, `YEAR`.	True
`subscription.interval.frequency`	The number of period units between each charge. `1-31`. Example: `Frequency: 3, Period: DAY` One charge every 3 days.	True

*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

Making the initialization request​

URL Templating​

Example​

Making the initialization request

URL Templating

Example