Skip to main content

PaymentSessionInitializationRequest

pointOfSaleIduuidrequired

Id of the point of sale to associate the payment with.

Example: 01924737-9c18-71c0-ab1a-88698eaceabf
referencestring

This is the order reference like an order id.
The reference id SHOULD be unique for each payment as some acquirers enforce unique reference numbers, you risk failed payments or hard to reconcile payments if duplicate references is used.

Example: reference-1
amountintegerrequired

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.

Example: 100
currencystringrequired

The currency code of the payment. For Danish Kroner defined as DKK.

Example: DKK
scaModestring

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.

Possible values: [SKIP, NORMAL, FORCE]

Example: NORMAL
timeoutinteger

The session is valid for the specified number of minutes. If a timeout occurs, the session expires and no more payment attempts are possible.

Possible values: >= 1 and <= 120

Example: 120
instantCapturestring

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)

Possible values: [OFF, VOID, NO_VOID]

Example: OFF
processorstring[]

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.

Possible values: [shift4, clearhaus, nets]

Example: ["shift4"]
exemptionsstring[]

List of exemptions to apply when applicable.

Example: []
textOnStatementstring

This is the text set on the transaction in the bank viewed by the card holder. That can be e.g. "order 123".

Example: order 123
attributes object

A list of pass through attributes that is sent back to the merchant on webhooks. Max size is 1kb.

property name*string
customerIdstring

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.

Example: User159
customer object

Customer info. These data points are used during SCA/3DS and is required for some schemes. It is recommended to send all the info that is available to improve the approval rate.

firstNamestringnullable
Example: Peter
lastNamestringnullable
Example: Nielsen
emailstringnullable
Example: email@example.com
phoneNumberstringnullable

E.164 phone number format with a single space between country code and local number. No additional spaces allowed.

Format: "+[countryCode] [number]".

Possible values: Value must match regular expression ^\+\d{1,3} \d+$

Example: +45 12345678
maxAttemptsinteger

The maximum allowed number of payment attempts for the session.

Possible values: >= 1 and <= 25

Example: 25
reportFailureboolean

If true: Enables webhooks to the notificationUrl for failed transactions. Otherwise only successful transactions are reported.

Example: false
dynamicAmountboolean

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.

Example: false
notificationUrluri

The URL to where ePay notifies about payment statuses. Max length is 1024.

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.

  • ${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/notification
preAuthUrluri

If not null then pre-authorization webhook are enabled for all transaction attempts for the session. Max length is 1024.

Example: https://example.com/preAuth
successUrluri

The URL the client is redirected to on a successful payment. Max length is 1024.

Example: https://example.com/success
failureUrluri

The URL the client is redirected to when no more payment attempts are allowed. Max length is 1024.

Example: https://example.com/failure
retryUrluri

An optional URL the client is redirected to when a payment attempt fails but more attempts are still allowed. If the retryUrl is not provided then the client will be redirected to the failureUrl. Max length is 1024.

Example: https://example.com/retry
subscription object
iduuid

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.

amountinteger

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.

typestringrequired

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.

Possible values: [UNSCHEDULED, SCHEDULED]

Example: SCHEDULED
referencestring

An optional merchant defined reference for the subscription. If none is given, then the session reference will be used as a fallback.

Example: subscription-1
expiryDatedate

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.

interval object

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.

periodstringrequired

The period unit between charges

Possible values: [DAY, WEEK, MONTH, YEAR]

frequencyintegerrequired

The number of period units between each charge. 1-31. Example: Frequency: 3, Period: DAY One charge every 3 days.

ageVerification object

Specifies age verification requirements for the purchase.

  • If not provided or set to null, no age verification will be performed.
  • If provided, the customer must verify their age to be at least the value specified in the minimumAge property.
minimumAgeintegerrequired

Possible values: >= 0 and <= 99

countrystring

Country code for the delivery country (ISO 3166 alpha-2 country codes). This code determines which electronic ID (eID) is presented to the user (e.g., MitID in Denmark).

Possible values: [DK]

PaymentSessionInitializationRequest
{
  "pointOfSaleId": "01924737-9c18-71c0-ab1a-88698eaceabf",
  "reference": "reference-1",
  "amount": 100,
  "currency": "DKK",
  "scaMode": "NORMAL",
  "timeout": 120,
  "instantCapture": "OFF",
  "processor": [
    "shift4"
  ],
  "exemptions": [],
  "textOnStatement": "order 123",
  "attributes": {},
  "customerId": "User159",
  "customer": {
    "firstName": "Peter",
    "lastName": "Nielsen",
    "email": "email@example.com",
    "phoneNumber": "+45 12345678"
  },
  "maxAttempts": 25,
  "reportFailure": false,
  "dynamicAmount": false,
  "notificationUrl": "https://example.com/notification",
  "preAuthUrl": "https://example.com/preAuth",
  "successUrl": "https://example.com/success",
  "failureUrl": "https://example.com/failure",
  "retryUrl": "https://example.com/retry",
  "subscription": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "amount": 0,
    "type": "SCHEDULED",
    "reference": "subscription-1",
    "expiryDate": "2024-07-29",
    "interval": {
      "period": "DAY",
      "frequency": 0
    }
  },
  "ageVerification": {
    "minimumAge": 0,
    "country": "DK"
  }
}