Frequently asked questions

See the Recurring API for all the details.

For general information and questions, please check in the Knowledge base.

Migration

How do I migrate from the Recurring API v2 to v3?

See the migration guide for the differences between the Recurring API v2 and v3. Also, check the V3 API definitions.

How do I migrate from the MobilePay subscription solution?

See: Migration guide.

Can I manage agreements and charges created with v2 API using v3 API?

Yes. All agreements and charges created with the v2 API can be retrieved and managed using the v3 API and vice-versa. Also, if an agreement was created with v2 API, it is possible to create a charge for this agreement with v3 API and vice-versa.

Charges/Payments

Do I need to store card data?

No. We handle all payment details. Merchants don't need to know how the users pay.

Do you automatically create charges for an agreement?

No. We do not create charges based on the agreement, every charge must be created by the merchant.

When a merchant creates a charge, we attempt to charge the customer, starting on the due date, and for as long after that as specified in retryDays.

For more details, see our call-by-call guide

When are charges processed?

See:

• Charge attempts
• Charge retries

I don't want a charge to fail the first time the transaction fails (insufficient funds, networking issues, etc.)

The field retryDays in a charge allows for this functionality. See: Charge retries.

How can I require an initial payment from the user for setting up the agreement?

You need to use Initial charge.

Can the charge amount be different from the agreement price?

Yes. See Are there any limits on charging a user?.

Are there any limits on charging a user?

Yes. Within the interval period of the agreement, the merchant can charge at most 5 times the agreement price cumulatively. There is no limit on the number of charges which can be sent in the interval period.

It is, however, recommended that you update the agreements pricing if there is a price change. In case of a more significant change, we recommend creating a new Agreement.

It is the merchant's responsibility to make sure the user is informed and understands the price of the Agreement.

When can I send charges to a user?

You can create charges once the user's agreement is ACTIVE.

See How do I check my customer's status?.

Can I change the charge interval?

Yes, it is possible to change the charge interval. Here are two examples of update interval requests :

Update request for changing the interval from RECURRING to FLEXIBLE:

{
  "interval": {
    "type": "FLEXIBLE"
  }
}

Update request for changing the period of the interval:

{
  "interval": {
    "type": "RECURRING",
    "period": {
      "count": 1,
      "unit": "MONTH"
    }
  }
}

See: PATCH:/recurring/v3/agreements/{agreementId}.

A charge failed, but the customer did not receive any warning

The customer may not have push notifications turned on for the app.

We always send push notifications to the user in the app when a charge processing attempt is not successful, and the user gets a more detailed message when looking at the charge/agreement in the app.

Merchants should always ask the user to check the status of charges in the app. We are not able to manually check charges unless there is a clear indication that there is an error on our end.

What happens to charges if the corresponding agreement is canceled?

All charges in a PENDING, DUE or RESERVED state will be canceled if the Agreement is stopped.
Note: This also includes the initial charge if it's currently RESERVED. So if the merchant needs to charge the user for the initial charge; then this needs to be done before the agreement is stopped.
Note: Charges with status RESERVED will not be cancelled if the stop of the agreement comes from the user side.

If a user's card expires: What happens on the next charge?

The user is responsible for keeping their payment cards updated.

If a payment fails the user will receive a push notification, informing them to update their card.

We don't automatically select a new card if a card expires, as users may have multiple cards registered in the app. There are also regulatory requirements: The user must actively choose a card.

We automatically send the user a push notification when a card that is not used for recurring payments expires.

What happens to pending charges if the user deletes the payment card?

See If a user's card expires: What happens on the next charge?

How does a user see the charges I create?

The charge will be visible to the user in the app when it goes into the DUE state. A charge will remain in PENDING state until the due date is less than 30 days away.

You can retrieve all relevant charges through the GET:/recurring/v3/agreements/{agreementId}/charges endpoint.

If a user adds or updates a card in the Vipps or MobilePay app, will new recurring charges be made to that card?

No, currently the payment card tied to an agreement will not be updated automatically. Users may want to charge different Agreements to different cards, and we do not want to automatically make changes to payment sources.

When the user adds or changes a card in Vipps, they get a prompt to change the card on their agreement as well. If the user skip this step, the user will be notified as described in What happens to pending charges if the user deletes the payment card?

For how long is a payment reserved?

See For how long is a payment reserved?.

How can I make refunds?

Refunds must always be done using the API, through the merchant's administration solution.

From the API checklist:

Make sure your customer service, etc. have all the tools and information they need available in your system, through the APIs listed in the first item in this checklist, and that they do not need to visit portal.vippsmobilepay.com for normal work.

Important: If you do manual refunds on portal.vippsmobilepay.com, the API may return incorrect details for charges until the same refund operation is done using the API.

Can users cancel pending payments?

No, the user cannot cancel pending payments. It may be possible for the user to cancel the agreement instead which will then cancel any pending payments.

Unscheduled charges

Why does the charge fail with "Cannot create a charge with type 'UNSCHEDULED'"?

If the sales unit is not approved for 'UNSCHEDULED' charges the charges will fail with:

"title": "Charge not creatable",
 "status": 400,
 "detail": "Cannot create a charge with type 'UNSCHEDULED'"

To be able to create UNSCHEDULED charges, the sales unit must be added to the allow list.

Variable amount

Can I decide the user's suggested max amount list

No. The suggested amount list from which the user can choose a maximum amount is automatically generated based on the suggestedMaxAmount sent in.

If the suggestedMaxAmount is changed, the suggested amount list will also be different the next time the user goes to change the maximum amount.

Agreements and users

Why do you allow drafting multiple agreements for the same user?

There are cases where one merchant might want to draft multiple subscriptions at the same time for the same user (i.e., the user subscribes to multiple services from the merchant), and there are also cases where one person might pay for multiple subscriptions for other reasons (family/relationships/guardianship).

It is the merchant's responsibility to know which of their users each drafted agreement belongs to, and to prevent drafting multiple agreements if that is not desirable.

How do I prevent drafting multiple agreements for the same user?

In order to prevent drafting multiple agreements for the same user, you need to keep track of which of your users any drafted agreement belongs to. Then, when a user does something that triggers a draft, you should first check if they already have an agreement that is PENDING, and inform the user that they should finish the agreement activation in the app or the landing page.

There might be some cases where the process fails in such a way that the user cannot complete activation and the agreement is stuck as PENDING for an extended period of time. Because of this, it might be a good idea to allow the user to choose to draft a new agreement regardless, but then you need to keep track of that "abandoned" agreement in case you might need to manage it later (stop and issue a refund if it gets undesirably activated or similar).

How do I check my customer's status?

Check the status of the user's agreement: Retrieve an agreement.

Can I look up a user's information?

We can provide a user's information with the user's consent. The merchant must ask the user for consent when creating the agreement using Profile sharing with the correct scope. The requested information is only available for a limited amount of time after the consent is given.

Can I look up which user owns an agreement?

No. See: Can I look up a user's information? and Is there an API for retrieving information about a Vipps MobilePay user?.

How can I convert existing agreements to Vipps MobilePay agreements?

If you have existing agreements or subscriptions that use eFaktura, AvtaleGiro, PDF invoices by email, or other payment methods, you can allow your customers to change to Vipps MobilePay in the following ways:

• Email: Email your customers and inform them that they can change to Vipps MobilePay. The email should contain a unique URL that leads directly to a webpage with a Vipps MobilePay payment for that customer. The customer may have to log in, so the Log in product may be useful for this.
• PDF invoice: Include a unique URL for the customer, same as above. You can use both a URL and a QR code containing the same URL. Keep in mind that some users will see the PDF invoice on their phone, and can't easily scan the QR.
• Paper invoice: Include a QR code with a unique URL for the customer, same as above.

How can I delete an agreement?

Stop an agreement by calling the PATCH:/recurring/v3/agreements/{agreementId} endpoint.

Can a user cancel the agreement through the Vipps or MobilePay app?

The MobilePay app allows users to cancel their payment agreements.

The Vipps app doesn't currently allow the user to cancel a payment agreement. They need to contact the merchant who can then cancel or modify the agreement as they see fit. The merchant must provide a link to the "my page" on the merchant's website when creating the agreement. See Create an agreement. On this "my page", the merchants must provide an easy way to cancel the agreement for the users.

Coming soon

Users will be able to cancel payment agreements in the Vipps app.

Can we opt out of showing Stop payment agreement in the app?

In the MobilePay app, merchants can't restrict users from stopping a payment agreement.

The Vipps app doesn't currently have the Stop payment agreement feature, but this will change soon.

Coming soon

Merchants are able to opt out of the feature to allow users to cancel the payment agreement in the app. We discourage this, but if the merchants have a very strong reason, they can request to opt out, provided they meet the below requirements. By opting out, the merchants will miss the future functionalities we build on managing agreements. In the future, there might be a fee that the merchant has to pay to be on the opt-out list.

Requirements:

• Provide a valid merchantAgreementUrl as per the API specification requirement while creating every agreement
• Provide us a screenshot or video of how their merchantAgreementUrl works.
• Agree that, if we receive numerous calls from users wanting to terminate their agreements due to difficulties using the merchant's My Page and unhelpful customer service from the merchant, we will take them off the opt-out list.

The request should be sent to developer@vippsmobilepay.com with the following information:

• Merchant serial number(s) to be configured for opt-out of cancelling agreement in Vipps app
• Reason for opting out
• Screenshot or video of how their merchantAgreementUrl works

We will review the request and communicate the decision.

How is the merchant notified when a user stops their agreement in the app?

We send the recurring.agreement-stopped.v1 webhook event to inform merchants that the users have stopped their agreement in the app. Merchants must listen to this event. The actor field in the payload will indicate if it was stopped by the merchant or the user. In addition, merchants can poll and get the status of the agreement, when needed.

What happens to the charges when a user stops their agreement in the app?

Existing RESERVED charges are not cancelled; merchants have the option to either capture or cancel the reservation. All DUE/PENDING charges are cancelled.

How can I move agreements between merchants and sales units?

Merchants sometimes need to move customer agreements from one merchant to another, or from one sales unit to another.

Clarification of terms:

• Merchant: A juridical unit, typically called a business or company, identified with organization number (also called, "org number" or "orgno").
• Sales unit: A merchant can have one or more sales units. It may be different brands, different physical locations, different services, etc.
• MSN: The unique ID of a sales unit. MSN is short for "Merchant Serial Number" which identifies a sales unit.

The following are the scenarios for moving agreements

• from one MSN to another, and both MSNs are under the same org number
• from one org number to another, and both org numbers are owned by the same parent org numbers
• from one org number to another, and the org numbers are not owned by a parent company (due to acquisition and mergers)

note

The general process is:

1. Log in on portal.vippsmobilepay.com and enter a new agreement with Vipps MobilePay for the new org number.

2. Order Billing and Recurring Payments.

3. Inform all of your existing customers about the change. If it's a new org number or there is a change of sales unit name. send us a confirmation that you have informed your end-users that the agreement is being transferred.

4. Email us at developer@vippsmobilepay.com (or use your Slack channel if you have one) and include all the following information:

   1. Merchant serial number you wish to migrate from
   2. Merchant serial number you wish to migrate to
   3. Copy of the letter/mail to users about the change to confirm that all customers have been informed as stated in point 3

5. The migration requests will be performed every Thursday, except on public holidays.

6. As part of the migration

   • All PENDING and DUE charges of agreements under 4.i will be cancelled
   • All agreements under 4.i will be stopped
   • Agreements identical to the old ones will be created under 4.ii with new agreement ID

7. After the migration, you will get a file that maps old agreement ID to the new agreement ID. This is a CSV where each line is an agreement, and the columns are old ID and new ID.

8. You then need to update your systems, so you start using the new agreement IDs to manage the agreement, perform new charges. We recommend keeping track of all agreements a customer has ever been associated with, so that you have the opportunity to retrieve previous agreements, charges, etc., if needed. Use the respective agreement ID and MSN in your API requests.

9. After the migration,

   • The new MSN 4.ii would not have the authority to capture/refund/etc. on old charges those were associated with 4.i. This means that, you need to use the old MSN 4.i and the old agreement ID in the API requests to perform the changes.
   • It will not be possible to make new charges on agreements under old MSN 4.i.
   • The user will still be able to see the old agreement in the app, under Stopped agreements and find the payment history up to the time of migration.
   • If the merchant deactivates an MSN that has active agreements, it will no longer be possible to perform any operations on the agreements and charges of that MSN.

Please note: The downtime experienced by end-users hinges on how effectively your systems manage the absence of agreement data from existing customers during migration. If your systems handle this transition smoothly, end-users may not encounter any downtime.

Can I look up an agreementId if I have the chargeId?

Yes. See Retrieve a charge.

Why is agreement not cancelled if user click cancel on the Vipps MobilePay landing page?

When a user clicks cancel on the landing page, they are redirected to the merchant site. If the user didn't insert their phone number on the landing page, the agreement will be cancelled. But if they did input their number before cancelling, the agreement will not be cancelled, but will stay in the pending state. This is because a push message has been sent to the phone and the agreement is still pending in the app. Potentially, the user could click cancel on landing page and accept in the app at the same time, causing a race condition. To avoid this, the only way to cancel the agreement is through the app. If the user doesn't take action, the agreement will instead expire. Since the user is redirected to merchant page after cancelling on the landing page, but the agreement is still pending, the merchant must handle this scenario by either cancelling the agreement or urging the user to check their Vipps or MobilePay app to complete the agreement.

Common problems/errors

Why do I get the error merchant.not.allowed.for.recurring.operation?

The merchant.not.allowed.for.recurring.operation error indicates that the Recurring API is not yet activated for this sales unit.

The Recurring API is available for existing customers that have Payment Integration, a direct integration with the ePayment API or eCom API, and have completed some additional Know Your Customer (KYC) checks required by Finanstilsynet.

Vipps MobilePay is required to perform some extra compliance checks before activating the Recurring API.

Please order Billing and Recurring Payments to get access to the Recurring API in production.

Is there an API for retrieving information about a Vipps MobilePay user?

Yes. We offer the possibility for merchants, as part of the payment flow, to request the user's information.

For details, see Userinfo API.

Error messages

Why do user get error "Something went wrong, please try again later." in the app when accepting agreement?

This error can be due to operational issues with Vipps MobilePay. Please check the status page for current status. It can also be caused by the MSN configuration. If merchant have not yet confirmed their bank account it will not be possible to accept agreements. Merchants can check this in the merchant portal under the relevant sales units.

Admin/partners

How do you change partners?

See Partner guide: How to change partners.

Important

On each agreement there is a merchantAgreementUrl which is the link each user clicks on to be able to change their subscription (e.g., a "My page" for the user). If the link structure is not the same in both solutions, you must update all existing agreements with a new URL as soon as possible after the move, so that the customers can manage the agreements further without coming to a blank page.

note

The Merchant Serial Number value (e.g., 281014) does not change when changing partners.