Skip to main content

Subscriptions to Recurring

Below, you can find comparison between the existing MobilePay Subscriptions API and the new Recurring API replacing MobilePay Subscriptions.

Stay Updated

API documentation:


If you didn't make the integration yourself, talk with your partner.

Authentication and management

We will have a joint authentication solution across our API platform and introduce a Management API to retrieve merchant data. Read more here.


See: Agreements

MobilePay Agreement ​Vipps MobilePay Agreement
Description ​productDescription​
Amount​pricing: { "type"("LEGACY" => amount ,"VARIABLE" => suggestedMaxAmount), "currency"("NOK") }
Frequency​interval: { "unit"("YEAR" "MONTH" "WEEK" "DAY"), "count"([1..31]) }
Links: [user-redirect, success-callback, cancel-callback, cancel-redirectmerchantRedirectUrl + merchantAgreementUrl​
N/Ascope (Space-separated list of the user profile-data scope to require for the agreement)​
N/AisApp (If merchant is redirecting user from an app or a mobile device)​
N/AskipLandingPage (true = skip landing page by sending a push notification directly to the user)​


See: Charges

MobilePay one-off​Vipps MobilePay initial charge
Amount (kroner.øre) ​amount (øre)​
External_id​orderId (if NULL → autogenerated. See Recommendations for reference and orderId.)​
links["rel", "href"]vippsConfirmationUrl

Refunds & Captures

Refunds and captures for payments and one off payments made before Nordic Wallet Launch must be handled by utilizing the OLD Subscriptions API.


If you are planning to reintegrate, you will have to start using new callback (webhook) solution. By default, even after reintegration you will receive webhooks in the old MobilePay format, but there is no possibility to change callback URL or authentication method. It is important to notice that after integrating towards new webhook solution you will be receiving both new and old webhooks. You have to notify us about integration to webhooks, in order for us to turn of old MobilePay callbacks for you.

These are the available fields of payment webhook we will be sending

Field nameTypeDescriptionPossible values
agreementIdstringID of an agreement"agr_kFW4chk"
chargeExternalIdnullable stringMerchant provided external ID of payment"ExtId123"
chargeIdstringID of payment"82ce990f-d08a-448c-bd26-ee6be8418d06"
amountnumberAmount of payment in cents300
chargeTypeenumIndicates if it is recurring, or agreement's initial one off payment"RECURRING", "INITIAL"
eventTypeenumIndicates what has happened to a chargeValues provided in a table below
currencyenumCurrency of payment"DKK", "NOK", "EUR"
occurredISO 8601 UTC dateWhen change has occurred2023-10-10T13:30:36.079765975Z
amountCapturednumberAmount of payment that was captured100
amountCancelednumberAmount of payment that was canceled200
amountRefundednumberAmount of payment that was refunded100

These are the possible event types in payment callback

Event typeDescription
"recurring.charge-reserved.v1"Payment was reserved. Event is not sent for recurring payments with transaction type "DIRECT_CAPTURE"
"recurring.charge-captured.v1"Payment was fully or partially captured
"recurring.charge-canceled.v1"Payment was fully or partially cancelled
"recurring.charge-failed.v1"Payment failed and will no longer be retried
"recurring.charge-creation-failed.v1"Payment failed to be created. Sent when merchants are using charge batch creation endpoint and charges are created asynchronously

This is an example of new payment callback

"agreementId": "agr_kFW4chk",
"chargeExternalId": "extId",
"chargeId": "82ce990f-d08a-448c-bd26-ee6be8418d06",
"amount": 300,
"chargeType": "RECURRING",
"eventType": "recurring.charge-canceled.v1",
"currency": "NOK",
"occurred": "2023-10-10T13:30:36.079765975Z",
"amountCaptured": 0,
"amountCanceled": 300,
"amountRefunded": 0

These are the available fields of agreement webhook we will be sending

Field nameTypeDescriptionPossible values
agreementIdstringId of an agreement"agr_kFW4chk"
agreementUUIDUUIDId of an agreement"82ce990f-d08a-448c-bd26-ee6be8418d06"
agreementExternalIdnullable stringMerchant provided externalId of agreement"ExtId123"
eventTypeenumIndicates what has happened to an agreementValues provided in a table below
occurredISO 8601 UTC dateWhen change has occurred2023-10-10T13:30:36.079765975Z
actornullable enumIndicates who has initiated action. Applicable only for agreementStopped webhook"MERCHANT", "USER"

These are the possible event types in agreement callback

Event typeDescription
"recurring.agreement-activated.v1"User has accepted agreement
"recurring.agreement-rejected.v1"User has rejected agreement
"recurring.agreement-stopped.v1"Agreement was stopped either by merchant either by user
"recurring.agreement-expired.v1"Agreement has expired

This is an example of the new agreement callback:

"agreementId": "agr_hXbXJUN",
"occurred": "2023-10-11T09:51:04.562829303Z",
"agreementExternalId": null,
"eventType": "recurring.agreement-expired.v1",
"agreementUUID": "c81bf516-7972-488e-bbf1-146dcd8592f9",
"actor": null

"agreementId": "agr_hXbXJUN",
"occurred": "2023-10-11T09:51:04.562829303Z",
"agreementExternalId": null,
"eventType": "recurring.agreement-stopped.v1",
"agreementUUID": "c81bf516-7972-488e-bbf1-146dcd8592f9",
"actor": "MERCHANT"

Test environment

The test environment is called Merchant Test (MT) and is now open for test. MT currently only allows Norwegian phone numbers, currency and merchants, but you can test the API and payment flow. Please see the details of limitations of the test environment.


Management API and Report API is not available in MT and can only be tested in production.

In order to request access to the test environment, please use the following links:

We will e-mail you with the information you need to get started. This is also needed even though you are an existing MobilePay integrator or merchant, since we need your information registered on our new joint platform.

Help us improve our documentation

Did you find what you were looking for?