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. 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.

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. When turned off you will still receive retries of old webhooks if these have not been successful. As soon as all retries have run out you will receive no further callbacks on the old endpoints. 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.

Endpoints

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

List of endpoints

• Fetch Subscriptions provider

  • Subscriptions: GET:/subscriptions/api/merchants/me
  • Recurring: GET:/management/v1/merchants/{scheme}/{id}/sales-units

• Update subscription provider

  • Subscriptions: PATCH:/subscriptions/api/providers/{providerid}
  • Recurring: N/A

• Change REST callback authentication scheme to OAuth2(API Key/Basic)

  • Subscriptions: PUT:/subscriptions/api/providers/{providerid}/auth/...
  • Recurring: Webhook authentication

• Create agreement

  • Subscriptions: POST:/subscriptions/api/providers/{providerid}/agreements
  • Recurring: POST:/recurring/v3/agreements

• Fetch list of agreements

  • Subscriptions: GET:/subscriptions/api/providers/{providerid}/agreements
  • Recurring: GET:/recurring/v3/agreements

• Fetch agreement

  • Subscriptions: GET:/subscriptions/api/providers/{providerid}/agreements/{agreementid}
  • Recurring: GET:/recurring/v3/agreements/{agreementId}

• Update agreement

  • Subscriptions: PATCH:/subscriptions/api/providers/{providerid}/agreements/{agreementid}
  • Recurring: PATCH:/recurring/v3/agreements/{agreementId}

• Cancel agreement

  • Subscriptions: DELETE:/subscriptions/api/providers/{providerid}/agreements/{agreementid}
  • Recurring: PATCH:/recurring/v3/agreements/{agreementId} "status": "STOPPED"

• Payment batch

  • Subscriptions: POST:/subscriptions/api/providers/{providerid}/paymentrequests
  • Recurring: POST:/recurring/v3/agreements/charges

• One-off auto-reserve

  • Subscriptions: POST:/subscriptions/api/providers/{providerid}/agreements/{agreementid}/oneoffpayments
  • Recurring: POST:/recurring/v3/agreements/{agreementId}/charges "type": "UNSCHEDULED"

• Fetch list of payments

  • Subscriptions: GET:/subscriptions/api/providers/{providerid}/agreements/{agreementid}/paymentrequests
  • Recurring: GET:/recurring/v3/agreements/{agreementId}/charges

• Fetch payment

  • Subscriptions: GET:/subscriptions/api/providers/{providerid}/agreements/{agreementid}/paymentrequests/{paymentid}
  • Recurring: GET:/recurring/v3/agreements/{agreementId}/charges/{chargeId}

• Fetch payment by ID

  • Subscriptions: N/A
  • Recurring: GET:/subscriptions/api/agreements/{agreementId}/charges/{chargeId}

• Update pending payment

  • Subscriptions: GET:/subscriptions/api/providers/{providerid}/agreements/{agreementid}/paymentrequests/{paymentid}
  • Recurring: N/A

• Cancel pending payment

  • Subscriptions: DELETE:/subscriptions/apiproviders/{providerid}/agreements/{agreementid}/paymentrequests/{paymentid}
  • Recurring: DELETE:/recurring/v3/agreements/{agreementId}/charges/{chargeId}

• Cancel one-off

  • Subscriptions: DELETE:/subscriptions/api/providers/{providerid}/agreements/{agreementid}/oneoffpayments/{paymentid}
  • Recurring: DELETE:/recurring/v3/agreements/{agreementId}/charges/{chargeId} Only possible with Reserve Capture

• Capture subscriptions payment

  • Subscriptions: N/A
  • Recurring: POST:/recurring/v3/agreements/{agreementId}/charges/{chargeId}/capture Only needed for Reserve Capture

• Capture one-off payment

  • Subscriptions: POST:/subscriptions/api/providers/{providerid}/agreements/{agreementid}/oneoffpayments/{paymentid}/capture
  • Recurring: POST:/recurring/v3/agreements/{agreementId}/charges/{chargeId}/capture Only needed for Reserve Capture

• Refund

  • Subscriptions: POST:/subscriptions/api/providers/{providerid}/agreements/{agreementid}/payments/{paymentid}/refunds
  • Recurring: GET:/recurring/v3/agreements/{agreementId}/charges/{chargeId}

• Fetch refund

  • Subscriptions: GET:/subscriptions/api/providers/{providerid}/agreements/{agreementid}/payments/{paymentid}/refunds
  • Recurring: GET:/recurring/v3/agreements/{agreementId}/charges/{chargeId}

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/A	scope (Space-separated list of the user profile-data scope to require for the agreement)​
N/A	isApp (If merchant is redirecting user from an app or a mobile device)​
N/A	skipLandingPage (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, it is auto-generated. See Recommendations for reference and orderId.)​
Description​	description​
Expiration_timeout_minutes​	N/A
N/A	transactionType (RESERVE_CAPTURE, DIRECT_CAPTURE)​
MOBILEPAY RESPONSE FROM AGREEMENT	VIPPS MOBILEPAY RESPONSE FROM AGREEMENT
Id	agreementId
links["rel", "href"]	vippsConfirmationUrl
one_off_payment_id	chargeId

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.

Cross-border payments

The Recurring API enables merchants to provide payment services to users across Vipps MobilePay market areas, such as enabling a Danish merchant to offer convenient Vipps MobilePay wallet payments to customers in Norway, Finland, or Sweden.

For details, see Offering Vipps MobilePay in the Nordics.

Verification and going live

Merchants

Verification

Before going live with your new Recurring solution you 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. If you have any questions about any of the points in the checklist please feel free to contact us.

If you finalize the integration before the end of Q2 2025, we will provide the option to verify your integration. You can submit the checklist to developer@vippsmobilepay.com (or via your Slack channel), including videos or pictures of the payment flow and any relevant supporting systems.

Go live Once you are satisfied with the integration and the checklist, you can go live.

Please be aware

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

Partners

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.