> **Description:** Complete list of available webhook events, their structure, and when they are triggered across different Vipps MobilePay services.

> **AI agent:** Read [https://developer.vippsmobilepay.com/docs/knowledge-base/ai-tools.md](https://developer.vippsmobilepay.com/docs/knowledge-base/ai-tools.md) first. It covers keeping API keys and secrets out of generated code.

> **Full site overview:** For every page in this documentation, read [https://developer.vippsmobilepay.com/llms.txt](https://developer.vippsmobilepay.com/llms.txt).

# Event types

## ePayment API event types

We support up to 25 webhook registrations per event per MSN.
For more details, see [webhook limits](https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/api-guide.md#webhook-limits).

| Name       | Event Type                        |
| ---------- | --------------------------------- |
| Created    | `epayments.payment.created.v1`    |
| Aborted    | `epayments.payment.aborted.v1`    |
| Expired    | `epayments.payment.expired.v1`    |
| Cancelled  | `epayments.payment.cancelled.v1`  |
| Captured   | `epayments.payment.captured.v1`   |
| Refunded   | `epayments.payment.refunded.v1`   |
| Authorized | `epayments.payment.authorized.v1` |
| Terminated | `epayments.payment.terminated.v1` |

The payload format is:

For more details, see [ePayment webhooks](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/webhooks.md).

## Login API event types

We support up to 25 webhook registrations per event per MSN.

| Name | Event Type                         |
|------|------------------------------------|
| Ping | `login.merchant-initiated.ping.v1` |

The payload will contain:

| Name | Type | Description |
| ---- | ---- | ----------- |
| `auth_req_id` | String | The `auth_req_id` that identifies the login. |

For more details, see [Login webhooks](https://developer.vippsmobilepay.com/docs/APIs/login-api/api-guide/merchant-initiated-login-integration.md#webhook-events).

## QR API event types

We support up to one webhook registration per event per MSN.
For more about these limits, see [webhook limits](https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/api-guide.md#webhook-limits).

| Name       | Event Type                      |
| ---------- | ------------------------------- |
| CheckedIn  | `user.checked-in.v1`            |

The payload format is:

| Name | Type | Description |
| ---- | ---- | ----------- |
| `customerToken` | Base64 string | A reference to the customer. Should be used when initiating a payment through the ePayment API. Token is valid for 15 minutes. |
| `merchantQrId` | string | The ID of the QR code that has been scanned which is defined by the merchant when the QR was created. |
| `msn` | string | Merchant serial number. A unique ID of the sales unit to which the scanned QR belongs. |
| `initiatedAt` | UTC Timestamp in ISO 8601 format | The timestamp of when the customer scanned the QR. |

For more details, see [QR webhooks](https://developer.vippsmobilepay.com/docs/APIs/qr-api/api-guide/webhooks.md).

## Recurring API event types

We support up to 25 webhook registrations per event type per MSN.
For more about these limits, see [webhook limits](https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/api-guide.md#webhook-limits).

### Agreement webhook event types

| Name                      | Event Type                             |
| ------------------------- | -------------------------------------- |
| Agreement accepted        | `recurring.agreement-activated.v1`     |
| Agreement rejected        | `recurring.agreement-rejected.v1`      |
| Agreement stopped         | `recurring.agreement-stopped.v1`       |
| Agreement expired         | `recurring.agreement-expired.v1`       |

Payload properties may include:

| Field name            | Type              | Description        | Possible values                        |
|---------------------- |-------------------|--------------------|----------------------------------------|
| `agreementId`         | string            | ID of an agreement | `agr_kFW4chk`                          |
| `agreementUUID`       | UUID              | ID of an agreement | `82ce990f-d08a-448c-bd26-ee6be8418d06` |
| `agreementExternalId` | nullable string   | Merchant provided external ID of agreement | `ExtId123`     |
| `eventType`           | enum              | Indicates what has happened to an agreement | Values provided in a table above |
| `occurred`            | ISO 8601 UTC date | When change has occurred | `2023-10-10T13:30:36.0690000Z` |
| `actor`               | nullable enum     | Indicates who has initiated action. Applicable only for `recurring.agreement-stopped.v1` webhook. | `MERCHANT`, `USER`, `ADMIN`|
| `msn`                 | string            | Merchant Serial Number (MSN) | `119145` |

### Charge webhook event types

| Name                      | Event Type                             |
| ------------------------- | -------------------------------------- |
| Charge reserved           | `recurring.charge-reserved.v1`         |
| Charge captured           | `recurring.charge-captured.v1`         |
| Charge cancelled          | `recurring.charge-canceled.v1`         |
| Charge refunded           | `recurring.charge-refunded.v1`         |
| Charge failed             | `recurring.charge-failed.v1`           |
| Charge failed on creation | `recurring.charge-creation-failed.v1`  |

Payload properties may include:

| Field name                 | Type              | Description                                       | Possible values                        |
|----------------------------|-------------------|---------------------------------------------------|----------------------------------------|
| `agreementId`              | string            | ID of an agreement                                | `agr_kFW4chk`                          |
| `chargeId`                 | string            | ID of a charge                                    | `82ce990f-d08a-448c-bd26-ee6be8418d06` |
| `chargeExternalId`         | nullable string   | Merchant provided external ID of charge           | `ExtId123`                             |
| `transactionId`            | nullable string   | ID for a specific payment operation on a charge   | `2893200077`                           |
| `amount`                   | number            | Amount of charge in øre (NOK, DKK) or cents (EUR) | 300                                    |
| `chargeType`               | enum              | Indicates type of charge                          | `RECURRING`, `INITIAL`, `UNSCHEDULED`  |
| `eventType`                | enum              | Indicates what has happened to a charge           | Values provided in a table above       |
| `currency`                 | enum              | Currency of charge                                | `DKK`, `NOK`, `EUR`                    |
| `occurred`                 | ISO 8601 UTC date | When change has occurred                          | `2026-01-02T10:36:43.4880000Z`         |
| `amountCaptured`           | number            | Amount of payment that was captured               | 100                                    |
| `amountCanceled`           | number            | Amount of charge that was canceled                | 200                                    |
| `amountRefunded`           | number            | Amount of charge that was refunded                | 100                                    |
| `failureCode`              | nullable number   | Code of an error during async creation            | Listed below                           |
| `failureText` (deprecated) | nullable string   | Explanation of an error during async creation     | Listed below                           |
| `failureReason`            | nullable string   | Explanation of an error                           | Listed below                           |
| `msn`                      | string            | Merchant Serial Number (MSN)                      | `119145`                               |

Possible `failureCode` values with explanation.
This field is only present if the charge has failed async validation and
was created using the multiple charge creation endpoint:
[`POST:/recurring/v3/agreements/charges`][create-multiple-charges-endpoint].

| Failure code | Explanation                                                          |
|--------------|----------------------------------------------------------------------|
| 50003        | Charge is requested for non-active agreement                         |
| 50004        | Trying to create charge with same idempotency key more than once     |
| 50005        | Charge is requested for agreement that does not exist                |
| 50006        | Unspecified exception during charge creation                         |
| 70001        | Charge amount is 5 times higher than fixed amount agreement's amount |
| 70003        | Trying to create charge of type not allowed by merchant              |
| 70004        | Due date is too far in the future                                    |
| 70005        | Due date is too soon                                                 |

[create-multiple-charges-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/recurring-swagger-id.yaml

Possible `failureReason` values

| Failure reason           | Explanation                                                                   |
|--------------------------|-------------------------------------------------------------------------------|
| `user_action_required`   | The user has to fix something on their agreement, e.g. their payment source   |
| `charge_amount_too_high` | Charge amount exceeds the users allowed max amount                            |
| `technical_error`        | Something went wrong                                                          |
| `non_technical_error`    | E.g. user no longer exist                                                     |

For more details, see:
[Recurring webhooks](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide.md#webhooks-integration).

## Donations API event types

We support up to 25 webhook registrations per event per merchant.
Partners can register `donations.*` webhooks too, with an independent partner-level quota. See [webhook limits](https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/api-guide.md#webhook-limits) and [Partner webhooks](https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/api-guide.md#partnerpsp-webhooks).

| Event type | Description |
|------------|-------------|
| `donations.agreement.started.v1` | Donation agreement has been started |
| `donations.agreement.stopped.v1` | Donation agreement has been stopped |
| `donations.agreement.withdrawal-day-changed.v1` | Donation agreement withdrawal day has been changed |
| `donations.agreement.amount-changed.v1` | Donation agreement amount has been changed |

#### Started event payload

When a donation agreement is started, you will receive the following payload:

| Field name | Type | Description | Example |
|------------|------|-------------|---------|
| `agreementId` | string | ID of the donation agreement | `2518f497-bfad-43a6-8914-fd0168a6c221` |
| `startedAt` | ISO 8601 UTC date | When the agreement was started | `2026-01-31T17:26:50.8789251+00:00` |

Example payload:

```json
{
  "agreementId": "2518f497-bfad-43a6-8914-fd0168a6c221",
  "startedAt": "2026-01-31T17:26:50.8789251+00:00"
}
```

#### Stopped event payload

When a donation agreement is stopped, you will receive the following payload:

| Field name | Type | Description | Example |
|------------|------|-------------|---------|
| `agreementId` | string | ID of the donation agreement | `2518f497-bfad-43a6-8914-fd0168a6c221` |
| `stoppedAt` | ISO 8601 UTC date | When the agreement was stopped | `2026-01-31T17:26:50.8789251+00:00` |

Example payload:

```json
{
  "agreementId": "2518f497-bfad-43a6-8914-fd0168a6c221",
  "stoppedAt": "2026-01-31T17:26:50.8789251+00:00"
}
```

#### Withdrawal day changed event payload

When the withdrawal day of a donation agreement is changed, you will receive the following payload:

| Field name | Type | Description | Example |
|------------|------|-------------|---------|
| `agreementId` | string | ID of the donation agreement | `34580d79-0628-4ed5-bb0a-75a6f2a6fae1` |
| `changedAt` | ISO 8601 UTC date | When the withdrawal day was changed | `2026-02-15T17:00:22.1234567Z` |
| `withdrawalDay` | integer | New withdrawal day (1-28) | `12` |
| `nextPeriodKey` | string (optional) | Billing period key for the next withdrawal. Format: `YYYY-MM` (e.g. March 2026 is `2026-03`). Omitted or null when the next billing period is not yet determined (e.g. before the first schedule has been initialized). | `2026-03` |

Example payload (when next period is known):

```json
{
  "agreementId": "34580d79-0628-4ed5-bb0a-75a6f2a6fae1",
  "changedAt": "2026-02-15T17:00:22.1234567Z",
  "withdrawalDay": 12,
  "nextPeriodKey": "2026-03"
}
```

When the next billing period is not yet determined, `nextPeriodKey` may be omitted or `null`.

#### Amount changed event payload

When the amount of a donation agreement is changed, you will receive the following payload:

| Field name | Type | Description | Example |
|------------|------|-------------|---------|
| `agreementId` | string | ID of the donation agreement | `34580d79-0628-4ed5-bb0a-75a6f2a6fae1` |
| `changedAt` | ISO 8601 UTC date | When the amount was changed | `2026-02-15T17:00:22.1234567Z` |
| `amount` | object | New amount | See below |
| `amount.value` | integer | Amount in minor units (e.g. øre/cents) | `20000` |
| `amount.currency` | string | ISO 4217 currency code | `DKK` |

Example payload:

```json
{
  "agreementId": "34580d79-0628-4ed5-bb0a-75a6f2a6fae1",
  "changedAt": "2026-02-15T17:00:22.1234567Z",
  "amount": {
    "value": 20000,
    "currency": "DKK"
  }
}
```

For more details, see [Donations webhooks](https://developer.vippsmobilepay.com/docs/APIs/donations-api/api-guide.md#agreement-webhook-events).