Skip to main content

Subscriptions to Recurring

Migrating from MobilePay Subscriptions to Vipps MobilePay Recurring is a straightforward process thanks to the similarities between the two APIs. This guide provides a comprehensive comparison between the MobilePay Subscriptions facade API and the Vipps MobilePay Recurring API, highlighting the key differences and mapping the endpoints to facilitate a smooth transition.

Before you begin, ensure you review our migration readiness guide to prepare for the switch.

New features

Take advantage of the new features available in the Recurring API to enhance your solution and provide more value to your customers.

Mapping between the APIs​

Differences between Subscriptions and Recurring API​

Authentication​

Instead of OpenId, the Recurring API uses an Access Token solution.

Callbacks​

When transitioning to the Recurring API, you need to adopt the new webhook solution. Upon integration with the new webhook solution, you will receive both the new and old webhooks. You have to notify us about integration to webhooks, in order for us to turn off old MobilePay callbacks for you. 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.

Webhooks have more and different events. Read more in the Webhooks section. The mechanics for verifying webhooks has changed. Find all details in the Webhook authentication section.

Endpoints​

Find the full list of MobilePay Subscriptions endpoints and how they map to the new Recurring endpoints.

List of endpoints

Agreements​

All existing Subscriptions agreements are available through the Recurring API. You do not need to initiate new agreements, and no user action is required.

See: Recurring agreements

Agreement ID​

Subscriptions agreement IDs have UUID format. Recurring agreement IDs have agr_xxx format. When migrating to Recurring, you must fetch all your existing agreements through GET:/recurring/v3/agreements. This will contain the input uuid, which is the Subscriptions agreement ID and id which is the new Recurring agreement ID. Use this in order to map the old agreement ID with the new. Once migrated to Recurring API, you must use the id of format agr_xxx, as this is the end-to-end reference for agreements.

Price type​

Recurring agreements have a price type. Existing Subscriptions agreements are mapped based on these criteria:

  • Agreements with no amount are set to pricing.type = FLEXIBLE
  • Agreements with amount are set to pricing.type = LEGACY
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-redirect] merchantRedirectUrl + merchantAgreementUrl​
Plan​productName​
mobile_phone_number​phoneNumber​
external_id​externalId​
currency​N/A
country_code​N/A
expiration_timeout_minutes​N/A
retention_period_hours​N/A
disable_notification_management​N/A
notifications_on​N/A
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)​

Charges​

See: Charges

MobilePay one-off​Vipps MobilePay initial charge
Amount (kroner.øre) ​amount (øre)​
External_id​orderId (if NULL → auto-generated. See Recommendations for reference and orderId.)​
Description​description​
Expiration_timeout_minutes​N/A
N/AtransactionType (RESERVE_CAPTURE, DIRECT_CAPTURE)​
MOBILEPAY RESPONSE FROM AGREEMENTVIPPS MOBILEPAY RESPONSE FROM AGREEMENT
IdagreementId
links["rel", "href"]vippsConfirmationUrl
one_off_payment_idchargeId

New features​

Now that you are moving to the Recurring solution you can take advantage of some new features to improve your solution and enhance user experience.

Campaigns​

A campaign in Recurring is a period where the price is lower than usual, so you can easily show discounts and price campaigns to your users.

Login​

Need an easy way to log in your users? You don't have to stick with the Recurring API, you are free to use all our APIs including Login that can be used to retrieve user data or as a login option.

Merchant and sales unit data through the API​

There is no need to go through the portal to fetch you merchant-serial-number, you can just use the Management API. This is especially relevant for partners as it can also be used to onboard and fetch information about their merchants.

Verification and going live​

Verification

Before going live with your new Recurring solution we must verify your solution. You do this by going through all the points in the Recurring checklist. Please ensure that you have implemented all endpoints and evaluated the Quality assurance and Avoid integration pitfalls. Once you have filled out the checklist please send it to developer@vippsmobilepay.com (or through your Slack channel) including video or pictures of the payment flow and any relevant supporting systems.

If you complete the integration before the end of Q2 2025, we will provide the option for a more thorough verification of your integration. Please contact developer@vippsmobilepay.com if you are interested in this.

Go live

Once your checklist is approved, you can go live with your merchants according to your own plan. Please let us know how you plan for going live, whether it is all merchants at once or in batches.

Please be aware

Before you go live, you must fetch the new IDs for agreementIds.

Help us improve our documentation

Did you find what you were looking for?