Skip to main content

CreatePaymentLinkRequest

pointOfSaleIduuidrequired

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

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

This is the transaction reference, similar to an order ID.
The reference SHOULD be unique for each payment, as some acquirers enforce per-payment uniqueness.
Using a duplicate reference may result in failed payments or make reconciliation difficult.
Only ASCII alphanumeric characters and dashes are allowed.

Worldline specific: - is removed if present and if the value is longer than 12 position, the left most part is used.

Possible values: non-empty and <= 36 characters, Value must match regular expression ^[A-Za-z0-9-]{1,36}$

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. ISO 4217 alpha-3 (e.g., DKK)

Possible values: Value must match regular expression ^[A-Z]{3}$

Example: DKK
instantCapturestringnullable

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
processorProcessor (string)[]nullabledeprecated

DEPRECATED: This parameter will soon be removed and will no longer have any effect. The functionality has been replaced by routing rules in the ePay back office.

List of processors to use. This is the routing of the payment. The value can be shift4, clearhaus and nets.

Processor priority follows the order in the list. If the first processor fails or declines, the next processor in the list will be attempted, and so on until all processors have been tried. Note that the actual processing order is not guaranteed and may depend on external factors, such as the specific payment card used by the cardholder.

Possible values: [shift4, clearhaus, nets, worldline]

Example: ["shift4"]
textOnStatementstringnullable

This is the text set on the transaction in the bank viewed by the card holder. That can be e.g. "order 123". Defaults to the ePay transaction id. Some providers does not support long texts, ePay will automatically cut the text to fit the providers requirements.

Possible values: non-empty and <= 39 characters

Example: order 123
attributes objectnullable

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

property name*anynullable

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

customerIdstringnullable

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. These data may also be sent to the specific payment provider, if required to complete the payment such as Klarna. It is recommended to send all the info that is available to improve the approval rate.

firstNamestringnullable

The first name of the paying customer.

Possible values: non-empty

Example: Peter
lastNamestringnullable

The last name of the paying customer.

Possible values: non-empty

Example: Nielsen
birthdatedatenullable

The date of birth of the cardholder in YYYY-MM-DD format.

Example: 2000-07-25
emailstringnullable

The email of the paying customer.

Possible values: non-empty

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
shippingAddress objectnullable

The shipping address of the purchase. If no wares are shipped, leave this empty. If billing and shipping address is the same, then fill both properties with identical information.

countryCodestringnullable

ISO 3166-1 alpha-2 country code

Possible values: >= 2 characters and <= 2 characters

Example: DK
postalCodestringnullable

The local postal code of the address

Possible values: non-empty and <= 16 characters

Example: 1400
citystringnullable

The city

Possible values: non-empty and <= 50 characters

Example: København
line1stringnullable

The first address line. Most address only has a singular line.

Possible values: non-empty and <= 50 characters

Example: Torvegade 45
line2stringnullable

Second address line. Only use if address contains multiple lines. Always start with line1.

Possible values: non-empty and <= 50 characters

Example: 2. th.
line3stringnullable

Third address line. Only use if address contains multiple lines. Always start with line1 and line2.

Possible values: non-empty and <= 50 characters

Example: Christianshavn
billingAddress objectnullable

The billing address of the customer. Often the personal address of the customer or the business address of paying company. If billing and shipping address is the same, then fill both properties with identical information.

countryCodestringnullable

ISO 3166-1 alpha-2 country code

Possible values: >= 2 characters and <= 2 characters

Example: DK
postalCodestringnullable

The local postal code of the address

Possible values: non-empty and <= 16 characters

Example: 1400
citystringnullable

The city

Possible values: non-empty and <= 50 characters

Example: København
line1stringnullable

The first address line. Most address only has a singular line.

Possible values: non-empty and <= 50 characters

Example: Torvegade 45
line2stringnullable

Second address line. Only use if address contains multiple lines. Always start with line1.

Possible values: non-empty and <= 50 characters

Example: 2. th.
line3stringnullable

Third address line. Only use if address contains multiple lines. Always start with line1 and line2.

Possible values: non-empty and <= 50 characters

Example: Christianshavn
preAuthUrlurinullable

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

Possible values: non-empty and <= 1024 characters

Example: https://example.com/preAuth
orderLines object[]nullable

The array containing list of line items that are part of this order. Maximum of 1000 line items could be processed in a single order. This is used by some payment methods, such as Klarna.

Possible values: <= 1000

  • Array [
    • descriptionstringrequired

    Descriptive name of the order line item.

    Possible values: non-empty and <= 255 characters

    Example: Running shoe
    imageUrlurlnullable

    URL to an image that can be later embedded in communications between Klarna and the customer. (max 1024 characters). A minimum of 250x250 px resolution is recommended for the image to look good. We recommend using a good sized image (650x650 px or more), however the file size must not exceed 12MB.

    Possible values: non-empty and <= 1024 characters

    quantityintegerrequired

    Quantity of the order line item. Must be a non-negative number.

    Possible values: >= 0

    Example: 2
    totalAmountintegerrequired

    Total amount of the order line. Must be defined as minor units. Includes tax and discount.

    Possible values: >= 0 and <= 200000000

    Example: 20000
    unitPriceintegerrequired

    Price for a single unit of the order line. Must be defined as minor units and exclude any discount. Typically including taxes, however some countries may include specific requirements.

    Possible values: <= 200000000

    Example: 10000
    typestringrequired

    Type of the order line item.

    Possible values: [PHYSICAL, DISCOUNT, SHIPPING_FEE, SALES_TAX, DIGITAL, GIFT_CARD, STORE_CREDIT, SURCHARGE, OTHER]

  • ]
    • subscription object

    Note scaMode is always set to FORCE when initializing a subscription due to EU PSD2 regulations.

    To create a subscription, allowing you to process MIT transactions in the future, you must send the subscription object. To process MIT transactions you must ensure your acquirer agreement has recurring payments enabled.

    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 in minor units (e.g., 1095 = 10.95 DKK) 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.

    billingAgreement objectnullable

    An optional property. When given a automatic scheduled billing agreement will be created. This can be used to sign up customers to automatic subscription billing, such as monthly payments. This field is mutually exclusive with subscription.id and subscription.interval

    billingPlanIduuidrequired

    The id of the billing plan to use for the agreement. The billing plan contains the price and interval used during automatic charging.

    Example: 019a7266-2f3a-7b26-9c93-b950aea9e13c
    referencestringnullable

    An optional reference to be added to the created billing agreement. If not set, the one from the subscription will be used.

    Example: agreement-1
    nextChargeAtdatenullable

    Which date to create the first automatic charge. If left blank the current date plus the plan interval will be used to calculate the next charge. This can be used for introductory campaigns where the first period is free followed by monthly charges.

    Example: 2030-07-22
    transactionTypestringnullable

    The type of transaction to process. Most merchants should use PAYMENT unless they have specific use cases.

    • PAYMENT is for ordinary purchases and the standard type to use for most merchants.
    • MOTO is short for Mail Order & Telephone Order and is typically used by travel agencies who receive payment info over the phone or email. MOTO is exempt from SCA but requires a special acquirer agreement to use.

    Possible values: [PAYMENT, MOTO]

    Default value: PAYMENT
    scaModestringnullable

    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
    timeoutintegernullable

    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
    exemptionsstring[]nullable

    List of exemptions to apply when applicable. Supports [TRA, LVT]. Note: Using exemptions may shift liability for fraud from the issuer to the merchant.

    Possible values: [TRA, LVT]

    Example: []
    maxAttemptsintegernullable

    The maximum allowed number of payment attempts for the session.

    Possible values: >= 1 and <= 25

    Example: 25
    reportFailurebooleannullable

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

    Example: false
    dynamicAmountbooleannullable

    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.. Must be enabled by ePay support.

    Example: false
    notificationUrlurinullable

    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.

    Possible values: non-empty and <= 1024 characters

    Example: https://example.com/notification
    returnUrlurinullable

    The URL to where the browser is returned, when clicking the back button in the Payment Window. This overrides the default defined in the payment window configuration and supports url templating. Max length is 1024.

    Only used in Payment Window integrations.

    Possible values: non-empty and <= 1024 characters

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

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

    Possible values: non-empty and <= 1024 characters

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

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

    Possible values: non-empty and <= 1024 characters

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

    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.

    Possible values: non-empty and <= 1024 characters

    Example: https://example.com/retry
    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. For danish customers this id verified using MitID. Session.minimumAge will be set; transactions may be rejected if age not verified.
    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]

    CreatePaymentLinkRequest
    {
      "pointOfSaleId": "01924737-9c18-71c0-ab1a-88698eaceabf",
      "reference": "reference-1",
      "amount": 100,
      "currency": "DKK",
      "instantCapture": "OFF",
      "textOnStatement": "order 123",
      "attributes": {},
      "customerId": "User159",
      "customer": {
        "firstName": "Peter",
        "lastName": "Nielsen",
        "birthdate": "2000-07-25",
        "email": "email@example.com",
        "phoneNumber": "+45 12345678",
        "shippingAddress": {
          "countryCode": "DK",
          "postalCode": "1400",
          "city": "København",
          "line1": "Torvegade 45",
          "line2": "2. th.",
          "line3": "Christianshavn"
        },
        "billingAddress": {
          "countryCode": "DK",
          "postalCode": "1400",
          "city": "København",
          "line1": "Torvegade 45",
          "line2": "2. th.",
          "line3": "Christianshavn"
        }
      },
      "preAuthUrl": "https://example.com/preAuth",
      "orderLines": [
        {
          "description": "Running shoe",
          "imageUrl": "string",
          "quantity": 2,
          "totalAmount": 20000,
          "unitPrice": 10000,
          "type": "PHYSICAL"
        }
      ],
      "subscription": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "amount": 0,
        "type": "SCHEDULED",
        "reference": "subscription-1",
        "expiryDate": "2024-07-29",
        "interval": {
          "period": "DAY",
          "frequency": 0
        },
        "billingAgreement": {
          "billingPlanId": "019a7266-2f3a-7b26-9c93-b950aea9e13c",
          "reference": "agreement-1",
          "nextChargeAt": "2030-07-22"
        }
      },
      "transactionType": "PAYMENT",
      "scaMode": "NORMAL",
      "timeout": 120,
      "exemptions": [],
      "maxAttempts": 25,
      "reportFailure": false,
      "dynamicAmount": false,
      "notificationUrl": "https://example.com/notification",
      "returnUrl": "https://example.com/success",
      "successUrl": "https://example.com/success",
      "failureUrl": "https://example.com/failure",
      "retryUrl": "https://example.com/retry",
      "ageVerification": {
        "minimumAge": 0,
        "country": "DK"
      }
    }