Subscriptions to Recurring

Below, you can find comparison between the existing MobilePay Subscriptions facade API and the Recurring API. The two APIs are very similar catering to an easy switch between the two solutions.

Before you begin make sure to check out how to get started with the migration.

New features

Remember to check out the new features you can utilize to enhance your solution and create more value for your and 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 you switch to Recurring API you must also implement the new webhook solution. 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. 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 request authentication section.

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}

Agreement

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 id have format UUID. Recurring agreement id have format agr_xxx. 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 and 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 → 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.