EventWebhook
Envelope posted to your webhook URL when an event occurs.
Use event to identify the event type. The event-specific payload is in data, and its shape depends on the event type.
You can parse every webhook type with one request structure that includes the optional fields used by each event type, then use event to handle the fields relevant to that event. Event data shapes are deliberately non-conflicting: when two event types contain a field with the same name, it always has the same data type. Fields not used by an event type are omitted.
Identifier of the event that triggered the webhook.
"transaction.success.v1""transaction.failed.v1""transaction.captured.v1""transaction.refunded.v1""transaction.voided.v1""transaction.renewed.v1""subscription.disabled.v1""subscription-billing.charge-created.v1""subscription-billing.charge-success.v1""subscription-billing.charge-failed.v1""subscription-billing.agreement-active.v1""subscription-billing.agreement-stopped.v1""settlement.transfer-ready.v1"Event-specific payload.
Payload delivered for transaction.success.v1 and transaction.failed.v1 webhooks.
The ID of the transaction
"LDG7M4WW44G"The ID of the associated subscription
uuid"0197c07b-3f6d-7be2-b848-702b08958128"The ID of any associated subscription billing charge. Will be null if the transaction was not an automatic charge made on a billing agreement.
uuid"019a727b-987f-7768-a59e-71af920ef81f"The current state of the transaction. See our Core Concepts page.
"PENDING""PROCESSING""SUCCESS""FAILED"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.
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.
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.
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.
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 approvalCY- Challenged then approvedCN07- Challenged then rejected due to reason07N07- Rejected without a challenge due to reason07
The time of creation
date-timeThe ID of the associated session. This will be null for any MIT transactions.
The ID of the associated payment method
uuidThe type of the payment method.
"CARD""VIPPS_MOBILEPAY""MOBILEPAY_ONLINE""APPLE_PAY""GOOGLE_PAY""SWISH""VIABILL""ANYDAY""KLARNA""CARD"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.
"Visa""Mastercard""Maestro""Dankort""VisaDankort""Discover""UnionPay""Electron""Amex""JCB""Visa"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.
dateA cardholder friendly text to help them identify the payment method. For cards this will be a masked version of the card number.
Contains the entered cardholder name of the optional "name" field. Will be null if the field is not rendered.
The SCA mode of the transaction.
"SKIP""NORMAL""FORCE"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.
The transaction amount in minor units (e.g., 1095 = 10.95 DKK)
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.
The currency of the transaction in ISO 4217 alpha-3. DKK for danish kroner.
The instant capture mode.
"OFF""VOID""NO_VOID"The URL to receive webhook notifications of any transaction attempts. May contain templating variables.
urilength <= 1024The ID of the associated point of sale
uuidThe merchant reference of the transaction, this is often used for the order id.
The text to show on the cardholder bank statement
1 <= length <= 39The list of exemptions to apply when possible. Note that exemptions may shift liability from the issuer to the merchant.
Array [
string
]
A list of pass-through parameters that will be sent back to the merchant for following any webhooks
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.
"52.212.176.122"The detected origin country (Alpha-2) based on the clientIp property. Can be empty.
- Data derived from GeoLite2 by MaxMind.
"DK"The type of transaction.
"PAYMENT""PAYOUT""MOTO"Payload delivered for transaction.captured.v1, transaction.refunded.v1, transaction.voided.v1, and transaction.renewed.v1 webhooks.
The ID of the operation
uuidThe 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.
uuidThe operation amount in minor units (e.g., 1095 = 10.95 DKK)
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. SeeerrorCodefor rejection reason.
"PROCESSING""SUCCESS""FAILED"The ID of the associated transaction
"LDG7M4WW44G"The type of operation.
AUTHORIZATION: Reserve funds on the payment method.CAPTURE: Transfer previously authorized funds.SALE: A combined operation that performs bothAUTHORIZATIONandCAPTUREin 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.
"AUTHORIZATION""SALE""CAPTURE""REFUND""VOID""PAYOUT"When state is equal to FAILED, this will contain the explaining error code.
The time of creation
date-timeThe timestamp when the operation reached a terminal state.
An operation is terminal once it transitions from PROCESSING to either SUCCESS or FAILED.
date-timePayload delivered for subscription.disabled.v1 webhooks.
The ID of the subscription
uuid"01929a94-5fce-7ccc-a7e4-7e9249133b39"The ID of the associated payment method
uuid"01924756-d1f6-738d-8040-90d76cedf01f"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.
^[A-Z]{3}$"DKK"The id of the merchant customer
"User159"The ID of the associated point of sale used during the creation of the subscription
uuid"0192473a-e381-705c-b61c-fc2ac9624afc"The merchant reference for the subscription.
"reference-1"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.
The current state of the subscription. See our Core Concepts page.
"PENDING""ACTIVE""INVALID""DISABLED""ACTIVE"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.
"CLOSED_BY_MERCHANT_API""CLOSED_BY_MERCHANT_BACKOFFICE""CLOSED_BY_CARDHOLDER""CLOSED_BY_EPAY""CLOSED_BY_CARDHOLDER"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.
"SCHEDULED""UNSCHEDULED""SCHEDULED"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.
date"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.
The time unit of the frequency field
"DAY""WEEK""MONTH""YEAR""MONTH"The number of period's between each charge.
1 <= value <= 311The time of creation
date-timePayload delivered for subscription-billing.charge-created.v1, subscription-billing.charge-success.v1, and subscription-billing.charge-failed.v1 webhooks.
Represents a scheduled billing event created from a billing agreement. Tracks processing state, retry schedule, and any linked transactions.
Unique identifier for the billing agreement charge.
uuid"019a72a0-4247-71c4-a4da-62b534d87af6"Current processing state of the charge.
"PROCESSING""FAILED""SUCCESS""PROCESSING"Identifier of the successful transaction created for this charge, when available.
"LDG7M4WW44G"Identifier for the associated billing plan.
uuid"019a729e-41c2-7d16-a1e2-fdb15a8146bb"Identifier for the billing agreement that produced this charge.
uuid"019a729e-2d93-7612-9329-8f783f66f834"Deadline for completing the charge before it is marked as failed.
date-time"2030-09-05T12:00:00Z"Timestamp of the next scheduled retry attempt, when additional retries are pending.
date-time"2030-08-01T12:00:00Z"Timestamp when the billing agreement charge was created.
date-time"2030-07-29T15:51:28.071Z"Payload delivered for subscription-billing.agreement-active.v1 and subscription-billing.agreement-stopped.v1 webhooks.
Represents an automated, recurring payment agreement between a merchant and a cardholder. Links a Subscription to a Billing Plan so ePay can manage scheduled charges and track billing status.
Unique identifier for the billing agreement.
uuid"019a729e-2d93-7612-9329-8f783f66f834"ID of the associated billing plan.
uuid"019a729e-41c2-7d16-a1e2-fdb15a8146bb"ID of the linked subscription.
uuid"019a729e-51ed-7426-b7c9-0e212b2d77d4"Optional session identifier. Is only present when the billing agreement was made using a session.
uuid"019a729e-660a-7a05-90ad-5160ad0decc5"Optional customer identifier.
"user-1"Date and time of the next charge, if scheduled. Will be null if the agreement is not in the ACTIVE state.
date-time"2030-08-29T15:51:28.071Z"Date and time of the last charge, if available.
date-time"2030-07-29T15:51:28.071Z"Preferred day of the month for charging. This is the day of the month ePay will attempt to target for monthly payments. This ensures a consistent billing date across months, which might otherwise vary depending on number of days in the month or leap years. Only available for monthly intervals.
30Current state of the billing agreement.
"PENDING""ACTIVE""STOPPED"Timestamp when the billing agreement last changed state.
date-time"2030-07-29T15:51:28.071Z"Optional reference string.
"agreement-1"Timestamp when the billing agreement was created.
date-time"2030-07-29T15:51:28.071Z"Payload delivered for settlement.transfer-ready.v1 webhooks.
Settlement transfers models the actual bank payouts from the acquirer to your bank.
The ePay ID of the settlement transfer
uuid"019b3130-5d58-716d-8881-9a3ec506017f"Acquirer identifier
"shift4"Name or filename of the settlement report as received by ePay. This is mainly used for logging and debugging purposes.
"settlement.csv"List of MIDs included in the settlement report.
Array [
string
[
"R01234"
]]
The posting date of the transfer as registered by the acquirer
date"2025-01-01"Net amount (After adjustments and fees) as numeric string
"99.01"ISO 4217 currency
"DKK"Reference from acquirer
"acq-123"Array [
The type of adjustment, this tells you reason for the adjust and who the money is paid to.
The types [RESERVE, ADJUSTMENT, FEE] is used for transfer adjustments.
-
RESERVE: The amounts deducted and released from the merchant’s collateral
-
FEE: Fees charged for different services provided by the acquirer (e.g., wire transfer fee).
-
ADJUSTMENT: Amounts debited or credited to the merchant to adjust the merchant balance.
The types [ACQUIRER_FEE, INTERCHANGE_FEE, SCHEME_FEE] is used for transaction adjustments.
-
ACQUIRER_FEE: Fees that is charged by and goes to the acquirer.
-
INTERCHANGE_FEE: Fees that goes to the issuing bank of the paying card.
-
SCHEME_FEE: Fees that goes to the scheme network such as Visa and Mastercard.
"RESERVE""ADJUSTMENT""FEE""ACQUIRER_FEE""INTERCHANGE_FEE""SCHEME_FEE""FEE"Numeric string, negative for fees
"-1.00"Human-readable description
"discount_rate"]
The sum of all adjustments from associated SettlementTransactions
Array [
The type of adjustment, this tells you reason for the adjust and who the money is paid to.
The types [RESERVE, ADJUSTMENT, FEE] is used for transfer adjustments.
-
RESERVE: The amounts deducted and released from the merchant’s collateral
-
FEE: Fees charged for different services provided by the acquirer (e.g., wire transfer fee).
-
ADJUSTMENT: Amounts debited or credited to the merchant to adjust the merchant balance.
The types [ACQUIRER_FEE, INTERCHANGE_FEE, SCHEME_FEE] is used for transaction adjustments.
-
ACQUIRER_FEE: Fees that is charged by and goes to the acquirer.
-
INTERCHANGE_FEE: Fees that goes to the issuing bank of the paying card.
-
SCHEME_FEE: Fees that goes to the scheme network such as Visa and Mastercard.
"RESERVE""ADJUSTMENT""FEE""ACQUIRER_FEE""INTERCHANGE_FEE""SCHEME_FEE""FEE"Numeric string, negative for fees
"-1.00"Human-readable description
"discount_rate"]
date-time"2025-12-18T11:20:11Z"{ "event": "transaction.success.v1", "data": { "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" } }}