6. Webhook

When the payment is completed a webhook HTTP request is sent to the merchant with the payment data:

Webhook
{
  "sca": {
    "rejected": false,
    "type": "3DS",
    "verification": "NONE"
  },
  "session": {
    "id": "0192473a-e382-79a9-bfc2-65da88fe812f",
    "subscriptionId": "01929a94-5fce-7ccc-a7e4-7e9249133b39",
    "amount": 1000,
    "attributes": { "key1": "value1", "key2": "value2" },
    "exemptions": ["TRA"],
    "createdAt": "2024-10-01T10:38:14.658688472+02:00",
    "currency": "DKK",
    "expiresAt": "2024-10-01T12:41:14.658688472+02:00",
    "instantCapture": "OFF",
    "maxAttempts": 10,
    "reportFailure": false,
    "dynamicAmount": false,
    "notificationUrl": "https://example.com/notification",
    "preAuthUrl": "https://example.com/pre-auth",
    "successUrl": "https://example.com/success",
    "failureUrl": "https://example.com/failure",
    "pointOfSaleId": "0192473a-e381-705c-b61c-fc2ac9624afc",
    "reference": "reference-1",
    "state": "COMPLETED",
    "textOnStatement": "The text",
    "scaMode": "SKIP",
    "timeout": 60
  },
  "transaction": {
    "id": "01924756-d1f6-7bc6-bb51-2b5f87b43925",
    "subscriptionId": "01929a94-5fce-7ccc-a7e4-7e9249133b39",
    "state": "SUCCESS",
    "errorCode": null,
    "createdAt": "2024-10-01T09:08:45.174774Z",
    "sessionId": "01924756-badd-71d4-be55-da367f434da4",
    "paymentMethodId": "01924756-d1f6-738d-8040-90d76cedf01f",
    "paymentMethodType": "CARD",
    "paymentMethodSubType": "Visa",
    "paymentMethodExpiry": "2050-01-01",
    "paymentMethodDisplayText": "40000000XXXX0003",
    "scaMode": "SKIP",
    "amount": 1000,
    "currency": "DKK",
    "customerId": "User159",
    "instantCapture": "OFF",
    "notificationUrl": "https://example.com/notification",
    "pointOfSaleId": "0192473a-e381-705c-b61c-fc2ac9624afc",
    "reference": "reference-1",
    "textOnStatement": "The text",
    "exemptions": ["TRA"],
    "attributes": { "key1": "value1", "key2": "value2" },
    "clientIp": "1.2.3.4",
    "type": "PAYMENT"
  },
  "subscription": {
    "id": "01929a94-5fce-7ccc-a7e4-7e9249133b39",
    "paymentMethodId": "01924756-d1f6-738d-8040-90d76cedf01f",
    "currency": "DKK",
    "customerId": "User159",
    "pointOfSaleId": "0192473a-e381-705c-b61c-fc2ac9624afc",
    "reference": "subscription-1",
    "state": "ACTIVE",
    "type": "SCHEDULED",
    "expiryDate": null,
    "interval": {
      "period": "MONTH",
      "frequency": 1
    },
    "createdAt": "2024-10-01T10:38:14.658688472+02:00"
  },
  "acquirerAgreement": {
    "acquirer": "shift4",
    "mcc": "4514"
  }
}

Name	Description
`sca`	A nullable object describing the type of strong customer authentication (SCA) that occurred and the level of assurance, e.g., whether it was challenged or not.
`sca.rejected`	A boolean indicating if the SCA verification caused the rejection. A value of `false` does not imply that a successful SCA was performed.
`sca.type`	The type of SCA scheme used. Possible values: `3DS` or `DELEGATED`.
`sca.verification`	The level of verification performed. Possible values: `NONE`, `FRICTIONLESS`, `CHALLENGED`, or `UNKNOWN`.
`session`	The ePay session object representation.
`transaction`	The ePay transaction object representation.
`acquirerAgreement`	The ePay acquirer agreement object representation.

The webhooks expects that the receiving system replies by standard HTTP 200 as ok. Otherwise the webhook will be retried periodically with an exponential backoff strategy.

The first 2 attempts are sent immediately. Thereafter, exponential backoff begins according to the formula: 2^attempts seconds. With a maximum delay between attempts of 3 hours. After 25 attempts no more attempts will be made.

Example:

Attempt	Delay
1	0 seconds
2	0 seconds
3	4 seconds
4	8 seconds
5	16 seconds
...	...
14	3 hours
...	...
25	3 hours

warning

The webhook has a strict timeout of 5 seconds.

Merchants must not implement any long computations or integrations on the webhook url. Instead receive the webhook and quickly respond with a 200 OK status. Then handle your business logic in the background.

Merchants risk being moved to the low-priority queue if this is not respected. This is to ensure fair usage of ePay resources across all merchants.

Webhook Authentication

All webhooks are sent with an Authorization header which must be used to verify the webhook was sent by ePay.

By default, ePay generates a random Bearer token on account creation. This Bearer token along with the authorization scheme (Bearer vs Basic) can be modified in the ePay Backoffice.

Webhook Authentication​

Webhook Authentication