Event types

View as Markdown (opens in a new tab)

Install AI tools

Our plugin gives your assistant up-to-date guidance for payments and login. Full instructions

Claude Code

Run both commands, in order.

claude plugin marketplace add vippsas/agent-toolkit
claude plugin install vipps@agent-toolkit

Cursor

Open Settings, then Plugins.

Add vippsas/agent-toolkit as a plugin marketplace, then install the "vipps" plugin.

Codex

See the Codex plugin docs at developers.openai.com/codex.

Add vippsas/agent-toolkit as a plugin marketplace, then install the "vipps" plugin.

Any editor

No plugin needed. Paste this into your assistant.

Read https://developer.vippsmobilepay.com/llms.txt for the Vipps MobilePay developer documentation.

ePayment API event types

We support up to 25 webhook registrations per event per MSN. For more details, see 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:

msn required	string (MSNType) [ 4 .. 10 ] characters ^[0-9]{4,10}$ The merchant serial number (MSN) for the sales unit.
reference required	string (ReferenceType) [ 8 .. 64 ] characters ^[a-zA-Z0-9-]{8,64}$ The reference is the unique identifier for the payment, specified when initiating the payment. The reference must be unique for the sales unit (MSN), but is not globally unique, so several MSNs may use the same reference. See the recommendations.
pspReference required	string (PspReference) Each payment operation (i.e., create, capture, refund, cancel) will have a unique pspReference, defined by Vipps MobilePay. One of: The Get event log response contains each event and its unique pspReference value. The Get payment response contains the pspReference for the payment creation event. The Adjustment response, returned by Cancel, Capture, and Refund requests, contains the pspReference for the payment creation event.
name required	string (PaymentEventName) Enum: "CREATED" "ABORTED" "EXPIRED" "CANCELLED" "CAPTURED" "REFUNDED" "AUTHORIZED" "TERMINATED" The name of the payment event. Possible values are: CREATED AUTHORIZED CAPTURED CANCELLED REFUNDED ABORTED EXPIRED TERMINATED
required	object (Amount) Amount object, containing a value and a currency.
timestamp required	string <date-time>
idempotencyKey	string or null A unique key that prevents duplicate requests from being processed more than once. See idempotency
success required	boolean The outcome of this payment operation: true means that the operation was successful.
	object (Shipping Details) Shipping details for the order.
	object (User Details) User details for the payment.
sub	string If profile.scope was requested in createPayment, this value will be populated once state is AUTHORIZED. This can be used towards the Userinfo endpoint to fetch required user data.
captureGuaranteedUntil	string <date-time> The merchant is guaranteed to be able to capture the payment until this timestamp.

For more details, see ePayment webhooks.

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.

QR API event types

We support up to one webhook registration per event per MSN. For more about these limits, see 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.

Recurring API event types

We support up to 25 webhook registrations per event type per MSN. For more about these limits, see 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.

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

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.

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 and Partner 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:

{
  "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:

{
  "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):

{
  "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:

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

For more details, see Donations webhooks.