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.
{
"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:
| 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.
| False* |
instantCapture | If the payment should be captured instantly or not.
| 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:
| 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.
| 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.
| 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 |
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.
Acquirer fallback is not yet implemented. Only the first acquirer will be attempted.
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.
{
"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
https://example.com/epay/transaction/${transaction.id}/notification
https://example.com/epay/transaction/01924756-d1f6-7bc6-bb51-2b5f87b43925/notification