Create Payment Link

Test this endpoint live

Open the same request directly in API Explorer.

Server URL

Creates a new payment link with the ePay Payments API. This endpoint requires a valid ApiKey and must be called from the server side to ensure the ApiKey is never exposed client-side.

We recommend a minimum timeout of 5 seconds.

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.

These fields are:

scaMode
timeout
instantCapture
processor
maxAttempts
notificationUrl
successUrl
failureUrl

Creates a new payment link with the ePay Payments API. This endpoint requires a valid ApiKey and must be called from the server side to ensure the ApiKey is never exposed client-side. *We recommend a minimum timeout of 5 seconds.* :::info 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. These fields are: - `scaMode` - `timeout` - `instantCapture` - `processor` - `maxAttempts` - `notificationUrl` - `successUrl` - `failureUrl` :::

Authorization

BearerAuth

AuthorizationBearer <token>

In: header

Header Parameters

Idempotency-Keystring

If a response is replayed due to using the same key, the response will include the header Idempotent-Replayed: true.
Idempotency keys are scoped by [Key, Endpoint, HTTP Verb]; the same key on a different endpoint or method will not replay the original response.
Responses are cached for 24 hours. After that, the cache is cleared, so idempotency is only guaranteed within 24 hours of the initial request.

Ensures that a request can be safely retried without causing duplicate operations. Typically used for actions like payment creation and operations such as refund and void to prevent accidental double processing. - If a response is replayed due to using the same key, the response will include the header `Idempotent-Replayed: true`. - Idempotency keys are scoped by **[Key, Endpoint, HTTP Verb]**; the same key on a different endpoint or method will not replay the original response. - Responses are cached for **24 hours**. After that, the cache is cleared, so idempotency is only guaranteed within 24 hours of the initial request.

Request Body

application/json

Create payment link initialization payload.

TypeScript Definitions

Use the request body type in TypeScript.

pointOfSaleIdstring

Required

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

Format:

uuid

Example:

"01924737-9c18-71c0-ab1a-88698eaceabf"

referencestring

Nullable

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.

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.

Match:

^[A-Za-z0-9-]{1,36}$

Length:

1 <= length <= 36

Example:

"reference-1"

amountinteger

Required

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

currencystring

Required

The currency code of the payment. For Danish Kroner defined as DKK. ISO 4217 alpha-3 (e.g., DKK)

Match:

^[A-Z]{3}$

Example:

"DKK"

instantCapturestring

Nullable

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"

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.

**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`.<br/><br/>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.

Example:

[
  "shift4"
]

[index]Processor

Identifier of a payment processor. This value determines which payment gateway(s) are used to process a payment.

Possible values:

"shift4""clearhaus""nets""worldline"

textOnStatementstring

Nullable

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.

Length:

1 <= length <= 39

Example:

"order 123"

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

[key: string]unknown

customerIdstring

Nullable

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 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.

Example:

{
  "firstName": "Peter",
  "lastName": "Nielsen",
  "email": "email@example.com"
}

Example:

{
  "firstName": "Peter",
  "lastName": "Nielsen",
  "email": "email@example.com"
}

nullnever

preAuthUrlstring

Nullable

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

Format:

uri

Length:

1 <= length <= 1024

Example:

"https://example.com/preAuth"

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.

Items:

items <= 1000

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.

idstring

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.

Format:

uuid

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.

typestring

Required

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"

expiryDatestring

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.

Format:

date

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.

periodstring

Required

The period unit between charges

Possible values:

"DAY""WEEK""MONTH""YEAR"

frequencyinteger

Required

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

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

transactionTypestring

Nullable

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.

Default:

"PAYMENT"

Possible values:

"PAYMENT""MOTO"

scaModestring

Nullable

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

Nullable

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

Range:

1 <= value <= 120

Example:

120

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

Example:

[]

[index]string

Possible values:

"TRA""LVT"

List of allowed payment methods to use for this session. If left empty, all payment methods will be allowed.

This is useful for controlling which payment methods are visible in the payment window. If only 1 payment method is allowed and it is redirect-based, such as VIPPS_MOBILEPAY, the user will be automatically redirected from the payment window to the MobilePay payment page, without the user having to click anything. If the user then cancels the MobilePay payment, they will be redirected back to the returnUrl (Or the failureUrl if the returnUrl is not specified) instead of going back to the payment window.

List of allowed payment methods to use for this session. If left empty, all payment methods will be allowed. This is useful for controlling which payment methods are visible in the payment window. If only 1 payment method is allowed and it is redirect-based, such as `VIPPS_MOBILEPAY`, the user will be automatically redirected from the payment window to the MobilePay payment page, without the user having to click anything. If the user then cancels the MobilePay payment, they will be redirected back to the `returnUrl` (Or the `failureUrl` if the `returnUrl` is not specified) instead of going back to the payment window.

Example:

[
  "CARD",
  "VIPPS_MOBILEPAY"
]

[index]PaymentMethodType

The type of the payment method.

Possible values:

"CARD""VIPPS_MOBILEPAY""MOBILEPAY_ONLINE""APPLE_PAY""GOOGLE_PAY""SWISH""VIABILL""ANYDAY""KLARNA"

Example:

"CARD"

maxAttemptsinteger

Nullable

The maximum allowed number of payment attempts for the session.

Range:

1 <= value <= 25

Example:

25

generateQrCodeboolean

Nullable

If set to true the response property qrCode will be filled with a Base64 encoded QR code, which can be displayed for quick device-to-device link sharing such as from a POS device where the customer can scan the code and complete the payment on their own phone

Default:

false

Example:

false

reportFailureboolean

Nullable

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

Example:

false

reportExpiredboolean

If true: Enables webhooks to the notificationUrl for sessions that reach the expired state.

Default:

false

dynamicAmountboolean

Nullable

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

notificationUrlstring

Nullable

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.
- ${subscription.id}: The primary id of the associated subscription.

The URL to where ePay notifies about payment statuses. Max length is `1024`. <div class="theme-admonition theme-admonition-info alert alert--info"> <p style="margin-bottom:8px;">All URL properties support dynamic templating with session and transaction data, allowing merchants to define URLs that include ePay-generated resource ID's.</p> <p style="margin-bottom:8px;">This feature can be particularly helpful for some merchants, especially with success and failure URLs, as it simplifies fetching order information upon transaction completion.</p> <p style="margin-bottom:8px;">Unknown template keys will be rejected during request validation.</p> - `${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. - `${subscription.id}`: The primary id of the associated subscription. </div>

Format:

uri

Length:

1 <= length <= 1024

Example:

"https://example.com/notification"

returnUrlstring

Nullable

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.

Format:

uri

Length:

1 <= length <= 1024

Example:

"https://example.com/success"

successUrlstring

Nullable

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

Format:

uri

Length:

1 <= length <= 1024

Example:

"https://example.com/success"

failureUrlstring

Nullable

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

Format:

uri

Length:

1 <= length <= 1024

Example:

"https://example.com/failure"

retryUrlstring

Nullable

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.

Format:

uri

Length:

1 <= length <= 1024

Example:

"https://example.com/retry"

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.

minimumAgeinteger

Required

Range:

0 <= value <= 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"

Response Body

`application/json`

curl -X POST "https://example.com/public/api/v1/payment-links" \  -H "Idempotency-Key: c4f5e8d2-1234-5678-90ab-cdef12345678" \  -H "Content-Type: application/json" \  -d '{    "pointOfSaleId": "01924737-9c18-71c0-ab1a-88698eaceabf",    "amount": 100,    "currency": "DKK"  }'

{  "id": "KSNMWEWZPPA",  "sessionId": "01975f11-329f-7c14-a03a-3739d8b48ef3",  "url": "https://payments.epay.eu/link/KSNMWEWZPPA",  "qrCode": "/9j/2wCEAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4n...."}

{  "errorCode": "SERVER_ERROR",  "message": "An unexpected system error"}

{  "errorCode": "VALIDATION_ERROR",  "message": "Input validation errors",  "errors": {    "amount": [      "[required]: Is a required non-nullable field",      "[int]: Must be an integer",      "[min:0]: Must be greater than 0",      "[max:999999999]: Must be less than 999999999"    ]  }}

{  "errorCode": "SERVER_ERROR",  "message": "An unexpected system error"}

Authorization

Header Parameters

Request Body

Response Body

200application/json

400application/json

422application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`