NotificationWebhook | ePay documentation

The notification webhook is sent to the merchant’s configured endpoint when a transaction attempt has completed. Successful transaction attempts are always sent. Failed transaction attempts are sent only when reportFailure is true, and expired sessions are sent only when reportExpired is true.

Delivery and Retry Policy

The receiving system must respond with standard HTTP 200 OK.

If no 200 OK is received, the webhook will be retried with exponential backoff.

Retry strategy:
- Attempt 1: immediate (0 seconds).
- Attempt 2: immediate (0 seconds).
- Attempt 3+: delayed by 2^attempt seconds.
- Maximum delay capped at 3 hours.
- Retries stop after 25 attempts.

Each webhook request has a strict timeout of 5 seconds.

Merchants should always acknowledge quickly and process business logic asynchronously. Failure to comply may result in the endpoint being moved to a low-priority queue.

Headers and Authentication

Every webhook includes an Authorization header that must be validated to ensure the request originated from ePay.

By default, ePay issues a random Bearer token at account creation. This token, and the authorization scheme (Bearer vs Basic), can be managed in the ePay Backoffice.

No additional signatures or payload signing is applied. Verification relies exclusively on the Authorization header.

idstring

The ID of the transaction

Example:

"LDG7M4WW44G"

subscriptionIdstring

Nullable

The ID of the associated subscription

Format:

uuid

Example:

"0197c07b-3f6d-7be2-b848-702b08958128"

billingAgreementChargeIdstring

Nullable

The ID of any associated subscription billing charge. Will be null if the transaction was not an automatic charge made on a billing agreement.

Format:

uuid

Example:

"019a727b-987f-7768-a59e-71af920ef81f"

statestring

The current state of the transaction. See our Core Concepts page.

Possible values:

"PENDING""PROCESSING""SUCCESS""FAILED"

errorCodestring

Nullable

If the transaction has failed, this contains the associated error code explaining what went wrong.

A nullable object containing any known external status codes, such as the status code from the acquirer or the network. This can be useful for merchants who want to be able to react to very specific rejection reasons.

terminalstring

The status code from the terminal. The possible values depend on the terminal provider such as SoftPay. The key is only present if the value is known to ePay, and processed on a physical in-person terminal.

acquirerstring

The status code from the acquirer. The possible values depend on processing acquirer. The key is only present if the value is known to ePay.

networkstring

The status code from the scheme network. The field is only used for card based payments but stays consistent between acquirers. The key is only present if the value is known to ePay.

scastring

A unified status code representing the result of the Strong Customer Authentication (SCA) flow, such as 3DS. The code is built by concatenating the challenge status (transStatus) and reason code (transStatusReason) from the two steps of the 3DS protocol.

Code	Meaning
C	Transaction was challenged
N	Transaction was rejected
Y	Transaction was approved
U	Technical issues
I	Informational Only (No authentication performed)

The reason code (transStatusReason) is appended if present, e.g., 07.

Examples:

Y - Frictionless approval

CY - Challenged then approved

CN07 - Challenged then rejected due to reason 07

N07 - Rejected without a challenge due to reason 07

createdAtstring

The time of creation

Format:

date-time

sessionIdstring

Nullable

The ID of the associated session. This will be null for any MIT transactions.

paymentMethodIdstring

The ID of the associated payment method

Format:

uuid

paymentMethodTypePaymentMethodType

The type of the payment method.

Possible values:

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

Example:

"CARD"

paymentMethodSubTypestring

Nullable

The sub type of the associated payment method. For card based payments, this will contain the name of the scheme, such as Visa or Mastercard. The card scheme name formatted with a uppercase starting character. For non-card based payments the field vary depending on the requirements of the payment method.

Possible values:

"Visa""Mastercard""Maestro""Dankort""VisaDankort""Discover""UnionPay""Electron""Amex""JCB"

Example:

"Visa"

paymentMethodExpirystring

Nullable

The expiration date of the associated payment method.
Although payment cards are specified by a month and year (MM/YY), this value is returned as a full date (YYYY-MM-DD) representing the last day of the expiration month. Example: "2030-05-31" for a card expiring in May 2030.

Format:

date

paymentMethodDisplayTextstring

A cardholder friendly text to help them identify the payment method. For cards this will be a masked version of the card number.

paymentMethodHolderNamestring

Nullable

Contains the entered cardholder name of the optional "name" field. Will be null if the field is not rendered.

scaModestring

The SCA mode of the transaction.

Possible values:

"SKIP""NORMAL""FORCE"

customerIdstring

Nullable

The merchant customer id of the transaction. This field is required to enable advanced features such as storing a card for later reuse. Do not use any "guest" customer ids. Customer ids must be unique for each customer and must be protected by authentication.

amountinteger

The transaction amount in minor units (e.g., 1095 = 10.95 DKK)

feeinteger

The applied transaction fee in minor units. The fee is included in the amount field. To get the original amount you must subtract fee from amount. Fees are only applied if surcharge is configured in the ePay backoffice.

Fees are calculated during transaction processing and as such is always 0 when initially created during MIT transactions.

currencystring

The currency of the transaction in ISO 4217 alpha-3. DKK for danish kroner.

instantCapturestring

The instant capture mode.

Possible values:

"OFF""VOID""NO_VOID"

notificationUrlstring

The URL to receive webhook notifications of any transaction attempts. May contain templating variables.

Format:

uri

Length:

length <= 1024

pointOfSaleIdstring

The ID of the associated point of sale

Format:

uuid

referencestring

Nullable

The merchant reference of the transaction, this is often used for the order id.

textOnStatementstring

Nullable

The text to show on the cardholder bank statement

Length:

1 <= length <= 39

The list of exemptions to apply when possible. Note that exemptions may shift liability from the issuer to the merchant.

A list of pass-through parameters that will be sent back to the merchant for following any webhooks

clientIpstring

The ip (ipv4/ipv6) of the cardholder making the transaction. The IP is captured by ePay at the initialization of the transaction client-side. Can be empty.

Example:

"52.212.176.122"

clientCountrystring

The detected origin country (Alpha-2) based on the clientIp property. Can be empty.

Data derived from GeoLite2 by MaxMind.

Example:

"DK"

typestring

The type of transaction.

Possible values:

"PAYMENT""PAYOUT""MOTO"

authorizedinteger

The total amount that has been approved on this transaction.

This is the amount the customer’s bank has set aside for the payment, but it has not necessarily been taken from their account yet.

Range:

0 <= value

Example:

25000

capturedinteger

The total amount that has actually been charged and taken from the customer.

This is the portion of the authorized amount that has been finalized and will be transferred to you.

Range:

0 <= value

Example:

15000

refundedinteger

The total amount that has been returned to the customer after being captured.

This represents money that was previously charged but has since been given back.

Range:

0 <= value

Example:

7500

voidedinteger

The total amount that was canceled before it was charged.

This reduces the authorized amount so that it will never be captured or taken from the customer.

Range:

0 <= value

Example:

3000

remaininginteger

The amount that is still authorized but not yet used.

This is the portion that can still either be captured (charged) or voided (canceled).

Range:

0 <= value

Example:

8000

paidOutinteger

The total amount that has been paid out to a recipient.

This is only used for payout transactions (sending money out), not for regular customer payments.

Range:

0 <= value

Example:

0

Array [

idstring

The ID of the operation

Format:

uuid

referenceTransactionOperationIdstring

Nullable

The ID of another operation that this operation depends on.
For example, a REFUND must reference the CAPTURE it is refunding.
Other operation types may also reference a prior operation if required.

Format:

uuid

amountinteger

The operation amount in minor units (e.g., 1095 = 10.95 DKK)

statestring

The state of the operation.

PROCESSING: The operation has been received and is being handled.

SUCCESS: The operation completed successfully.

FAILED: The operation could not be completed. See errorCode for rejection reason.

Possible values:

"PROCESSING""SUCCESS""FAILED"

transactionIdstring

The ID of the associated transaction

Example:

"LDG7M4WW44G"

typestring

The type of operation.

AUTHORIZATION: Reserve funds on the payment method.

CAPTURE: Transfer previously authorized funds.

SALE: A combined operation that performs both AUTHORIZATION and CAPTURE in a single step.

REFUND: Return funds to the customer.

VOID: Releases previously authorized funds.

PAYOUT: Transfer funds to a recipient.

SALE operations are only available for certain acquirers and will be used when available and instant capture is enabled.

Possible values:

"AUTHORIZATION""SALE""CAPTURE""REFUND""VOID""PAYOUT"

errorCodestring

Nullable

When state is equal to FAILED, this will contain the explaining error code.

createdAtstring

The time of creation

Format:

date-time

finalizedAtstring

Nullable

The timestamp when the operation reached a terminal state.
An operation is terminal once it transitions from PROCESSING to either SUCCESS or FAILED.

Format:

date-time

]

idstring

The ID of the payment session

Format:

uuid

subscriptionIdstring

Nullable

The subscription id related to the session, this can either be a new ID for new subscriptions or the given ID of a previous subscription which needs to be updated.

Format:

uuid

amountinteger

The transaction amount in minor units (e.g., 1095 = 10.95 DKK)

Pass-through data which will be returned back to the merchant in any webhook.

List of exemptions to apply when available. Note exemptions may cause liability shift from the issuer to the merchant.

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.

currencystring

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

Match:

^[A-Z]{3}$

expiresAtstring

The expiration time of the payment session. After this time the session can no longer be used and a new session must be created.

Format:

date-time

instantCapturestring

The instant capture mode.

Possible values:

"OFF""VOID""NO_VOID"

maxAttemptsinteger

The maximum number of transaction attempts allowed for the session

attemptsinteger

The current number of transaction attempts so far.

minimumAgeinteger

The minimum age required. If not null and ePay Verify is enabled on your account, the cardholder will be prompted to verify their age using local online IDs such as MitID in Denmark.

ageVerifiedboolean

Is true once the customers age has been verified to be at least equal to minimumAge parameter.

reportFailureboolean

Boolean flag to enable / disable receiving webhook notifications for failed transactions.

reportExpiredboolean

Boolean flag to enable / disable receiving webhook notifications for sessions that reach the expired state.

dynamicAmountboolean

Boolean flag to enable / disable dynamic amounts, allowing the client to determine the transaction amount. This is generally not recommended for most merchants.

notificationUrlstring

The URL to receive notifications for successful transaction attempts. Failed transaction attempts are sent only when reportFailure is true, and expired sessions are sent only when reportExpired is true.

Format:

uri

preAuthUrlstring

Nullable

Optional URL to receive a webhook just before authorization is attempted. Can be used to update or reject the transaction. This is often used by merchants integrating external risk tooling to trigger 3DS challenges depending on the payment.

Format:

uri

successUrlstring

The URL to redirect the client on successful payment attempts

Format:

uri

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

failureUrlstring

The URL to redirect the client on failed payment attempts when no more attempts are possible.

Format:

uri

retryUrlstring

Nullable

The URL to redirect the client on failed payment attempts when more attempts are possible. If null, then failureUrl is used instead.

Format:

uri

customerIdstring

Nullable

The ID of the cardholder. This field is required to enable stored cards. Do not use any "guest" customer ids. Customer ids must be unique for each customer and secured behind authentication.

pointOfSaleIdstring

The ID of the associated point of sale

Format:

uuid

referencestring

Nullable

The transaction reference - Typically the order id.

statestring

The state of the transaction

Possible values:

"PENDING""PROCESSING""COMPLETED""EXPIRED"

textOnStatementstring

The text to display on the cardholders bank statement

Length:

1 <= length <= 39

scaModestring

The chosen SCA mode. This can be used to control the level of cardholder authentication performed before the transaction is authorized.

Possible values:

"SKIP""NORMAL""FORCE"

timeoutinteger

The number of minutes the session is available.

createdAtstring

The time of creation

Format:

date-time

idstring

The ID of the subscription

Format:

uuid

Example:

"01929a94-5fce-7ccc-a7e4-7e9249133b39"

paymentMethodIdstring

Nullable

The ID of the associated payment method

Format:

uuid

Example:

"01924756-d1f6-738d-8040-90d76cedf01f"

currencystring

The currency of the original transaction which created the subscription. This is used as the default currency for new MIT transactions, if no currency is given.

Match:

^[A-Z]{3}$

Example:

"DKK"

customerIdstring

The id of the merchant customer

Example:

"User159"

pointOfSaleIdstring

The ID of the associated point of sale used during the creation of the subscription

Format:

uuid

Example:

"0192473a-e381-705c-b61c-fc2ac9624afc"

referencestring

Nullable

The merchant reference for the subscription.

Example:

"reference-1"

descriptionstring

Nullable

An optional description which can be assigned to the subscription. Can be used to help human operators to link or understand which subscription it is.

statestring

The current state of the subscription. See our Core Concepts page.

Possible values:

"PENDING""ACTIVE""INVALID""DISABLED"

Example:

"ACTIVE"

statusReasonstring

Nullable

Reason for the current state. Is currently only present for subscriptions reaching the DISABLED state.

If a cardholder closes a subscription from a wallet app, such as VippsMobilePay, the reason will be CLOSED_BY_CARDHOLDER.

Possible values:

"CLOSED_BY_MERCHANT_API""CLOSED_BY_MERCHANT_BACKOFFICE""CLOSED_BY_CARDHOLDER""CLOSED_BY_EPAY"

Example:

"CLOSED_BY_CARDHOLDER"

typestring

The type of subscription. SCHEDULED is used for fixed interval charges such as a monthly subscription fee. UNSCHEDULED is used for varying transaction intervals such as pay-as-you-go solutions such as parking or bike renting.

Possible values:

"SCHEDULED""UNSCHEDULED"

Example:

"SCHEDULED"

expiryDatestring

Nullable

The expiration date of the subscription. ePay does not enforce this expiration, but uses it in the processing of transactions which may improve approval rates.

Format:

date

Example:

"2050-01-01"

Interval configuration. It can only be present when type equal SCHEDULED. A frequency=2 and period=WEEK means one charge for every two weeks.

createdAtstring

The time of creation

Format:

date-time

rejectedboolean

Boolean indicator which is true when the transaction is rejected due to failing SCA such as a 3DS challenge with MitID.

Example:

false

typestring

The type of SCA performed during the transaction.

Possible values:

"3DS""DELEGATED""UNKNOWN"

Example:

"3DS"

verificationstring

The level of verification performed during the transaction. The value will be CHALLENGED if the customer was prompted with challenges such as MitID login.

Possible values:

"NONE""FRICTIONLESS""CHALLENGED""UNKNOWN"

Example:

"FRICTIONLESS"

Info about the card used during the transaction. Is only available for card based payments.

panstring

The masked account number of the paying card. If the transaction is token based, like ApplePay, this will instead contain the TAN (Token PAN).

Example:

"12345678XXXX1234"

expireMonthstring

The month the card expires in. A card expires at the end of the month.

Example:

"07"

expireYearstring

The year the card expires in.

Example:

"35"

parstring

Nullable

The "Primary Account Reference" is a unique non-sensitive reference to the specific card. This will have the same value for any payment made with the same card even across wallets such as ApplePay. This can be used for loyalty systems or fraud prevention systems which needs to uniquely identify cards. The value is not always available. Availability depends on the used acquirer.

Example:

"8F1B7C2QX4Z9N3V6M2R0K8YD5LJTPH"

Issuerstring

Nullable

The name of the card issuer (Bank)

Example:

"Danske Bank"

Schemestring

Nullable

The network scheme such as Visa and Mastercard of the card

Example:

"Visa"

Countrystring

Nullable

The alpha-2 code of the country the card was issued in

Example:

"DK"

Segmentstring

Nullable

The customer segment the card is issued to. This can be used to identify consumer vs business cards.

Possible values:

"consumer""business""payouts"

Example:

"consumer"

Fundingstring

Nullable

The type of funding behind payments made from the card. This can be used identify debit vs credit cards.

Possible values:

"debit""credit""prepaid"

Example:

"debit"

NotificationWebhook

{  "transaction": {    "id": "LDG7M4WW44G",    "subscriptionId": "0197c07b-3f6d-7be2-b848-702b08958128",    "billingAgreementChargeId": "019a727b-987f-7768-a59e-71af920ef81f",    "state": "PENDING",    "errorCode": "string",    "externalStatusCodes": {      "terminal": "string",      "acquirer": "string",      "network": "string",      "sca": "string"    },    "createdAt": "2019-08-24T14:15:22Z",    "sessionId": "string",    "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011",    "paymentMethodType": "CARD",    "paymentMethodSubType": "Visa",    "paymentMethodExpiry": "2019-08-24",    "paymentMethodDisplayText": "string",    "paymentMethodHolderName": "string",    "scaMode": "SKIP",    "customerId": "string",    "amount": 0,    "fee": 0,    "currency": "string",    "instantCapture": "OFF",    "notificationUrl": "http://example.com",    "pointOfSaleId": "be6bff4f-7fac-43c0-9f6b-cf2cd45ed7d1",    "reference": "string",    "textOnStatement": "string",    "exemptions": [      "LVT",      "TRA"    ],    "attributes": {      "property1": null,      "property2": null    },    "clientIp": "52.212.176.122",    "clientCountry": "DK",    "type": "PAYMENT"  },  "aggregates": {    "authorized": 25000,    "captured": 15000,    "refunded": 7500,    "voided": 3000,    "remaining": 8000,    "paidOut": 0  },  "operations": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "referenceTransactionOperationId": "09c60a7b-397b-4797-a5c8-792dc558cbed",      "amount": 0,      "state": "PROCESSING",      "transactionId": "LDG7M4WW44G",      "type": "AUTHORIZATION",      "errorCode": "string",      "createdAt": "2019-08-24T14:15:22Z",      "finalizedAt": "2019-08-24T14:15:22Z"    }  ],  "acquirerAgreement": {    "acquirer": "shift4",    "mcc": "4514"  },  "session": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "subscriptionId": "d079718b-ff63-45dd-947b-4950c023750f",    "amount": 0,    "attributes": {      "property1": null,      "property2": null    },    "exemptions": [      "string"    ],    "allowedPaymentMethods": [      "CARD",      "VIPPS_MOBILEPAY"    ],    "currency": "string",    "expiresAt": "2019-08-24T14:15:22Z",    "instantCapture": "OFF",    "maxAttempts": 0,    "attempts": 0,    "minimumAge": 0,    "ageVerified": true,    "reportFailure": true,    "reportExpired": true,    "dynamicAmount": true,    "notificationUrl": "http://example.com",    "preAuthUrl": "http://example.com",    "successUrl": "http://example.com",    "returnUrl": "http://example.com",    "failureUrl": "http://example.com",    "retryUrl": "http://example.com",    "customerId": "string",    "pointOfSaleId": "be6bff4f-7fac-43c0-9f6b-cf2cd45ed7d1",    "reference": "string",    "state": "PENDING",    "textOnStatement": "string",    "scaMode": "SKIP",    "timeout": 0,    "createdAt": "2019-08-24T14:15:22Z"  },  "subscription": {    "id": "01929a94-5fce-7ccc-a7e4-7e9249133b39",    "paymentMethodId": "01924756-d1f6-738d-8040-90d76cedf01f",    "currency": "DKK",    "customerId": "User159",    "pointOfSaleId": "0192473a-e381-705c-b61c-fc2ac9624afc",    "reference": "reference-1",    "description": "string",    "state": "ACTIVE",    "statusReason": "CLOSED_BY_CARDHOLDER",    "type": "SCHEDULED",    "expiryDate": "2050-01-01",    "interval": {      "period": "MONTH",      "frequency": 1    },    "createdAt": "2019-08-24T14:15:22Z"  },  "sca": {    "rejected": false,    "type": "3DS",    "verification": "FRICTIONLESS"  },  "card": {    "pan": "12345678XXXX1234",    "expireMonth": "07",    "expireYear": "35",    "par": "8F1B7C2QX4Z9N3V6M2R0K8YD5LJTPH",    "Issuer": "Danske Bank",    "Scheme": "Visa",    "Country": "DK",    "Segment": "consumer",    "Funding": "debit"  }}