> **Description:** Common questions about recurring payments implementation, subscription management, charge scheduling, and best practices for handling payment cycles.

# Frequently asked questions

See the
[Recurring API](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide.md)
for all the details.

## Core functionality

### Does the user have to pay an initial charge?

No, this is up to the merchant. Vipps MobilePay always verifies the user's payment source,
so even if there is no upfront payment we ensure that the user provides a valid payment source
when entering the agreement.
See:
[How Recurring Agreements works](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/how-it-works/payment-agreement/README.md).

### Does the user have to confirm each payment?

No. When a user has entered a payment agreement, the charges don't require any user action.
Users may choose to be *informed* of payments, but there is no functionality for accepting or rejecting charges.

See:
[Are users notified of every charge?](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-faq.md#are-users-notified-of-every-charge)

### Is there a delay for charges?

No. Charges are processed on the due date specified by the merchant, and payments are
processed without delays.

We do require that charges are created at least 1 day in advance, so the user is able to see the
upcoming charge. This does *not* mean that there is a delay, as the charge is processed on the due date.

```mermaid
flowchart LR
    A[A: Charge created<br>with due date] -->|One day<br>notice| B(B: Charge processed<br>on due date)
    B --> C{C: Charge<br>success?}
    C -->|Yes| D[D: Done]
    C -->|No| E[E: Retry for X days]
    E --> |Notify the user:<br>Push notifications,<br>in-app notifications| B
    D --> |No delay| F[F: Webhook,<br>Report API]
    D --> |T+2| G[G: Settlement<br>payout]
```

Charge processing flow: A charge is created with a due date (A). One day before the due date, the user is notified. On the due date the charge is processed (B). If the charge succeeds (C), it is marked Done (D). Done immediately triggers the Webhooks API and the Report API, and the settlement payout happens at T+2. If the charge fails (C), it enters a retry period (E) where the user is notified via push notifications and in-app messages, and the charge is retried until it succeeds or the retry period expires (back to B).

When a charge is completed the merchant is immediately notified using the
[Webhooks API](https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/README.md),
the charge details can be
[retrieved](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide.md#retrieve-a-charge),
and the settlement data is also available in the
[Report API](https://developer.vippsmobilepay.com/docs/APIs/report-api/README.md).

Unlike for normal card payments ("card on file") the Recurring API enables retries: If the first charge attempt (`C`) fails,
for instance due to insufficient funds, the charge will be retried every day, for as long as the merchant specifies.
Normal card payments would stop at step `E` if the charge attempt fails.

Vipps MobilePay will
[inform the user](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide.md#notifications-to-users-for-failed-charges)
with push notification and in-app messages how to complete the payment, significantly increasing the
success rate compared to normal card payments.

See:

* [Charge retries](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide.md#charge-retries)
* [Charge type](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide.md#charge-type)
* [Notifications to users for failed charges](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide.md#notifications-to-users-for-failed-charges)

## Managing agreements in the app

### Can users stop payment agreements in the Vipps MobilePay app?

Yes, sometimes.

1. All agreements must have a valid
   [agreement URL](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide.md#merchant-agreement-url),
   so users can easily access the merchant's website and manage the agreement.
   We strongly recommend using
   [Vipps MobilePay Login](https://developer.vippsmobilepay.com/docs/APIs/login-api/README.md)
   for users accessing the agreement URL.
   If the agreement URL changes you must
   [update the agreement](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide.md#update-an-agreement).
1. Users can stop payment agreements directly in our app:
   [Stopping an agreement in the Vipps MobilePay app](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide.md#stopping-an-agreement-in-the-vipps-mobilepay-app).
1. KAM merchants (merchants with a Key Account Manager) can "opt out" of this:
   [Opting out of the Stop Payment Agreement feature](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide.md#stopping-an-agreement-in-the-vipps-mobilepay-app).

**INFO**

In extreme cases, where many users contact our customer service because they can't get help
from the merchant to cancel their payment agreement, we may enable the "stop agreement" in our app.
We may also do the same when an agreement has an
[agreement URL](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide.md#merchant-agreement-url)
that does not take the user directly to the page where the agreement can be managed.

### Are users notified of every charge?

Notifications for successful payment of charges are not enabled by default, but users can choose to get notified
when they enter an agreement, and when they manage the agreement.

This is similar to how eFaktura works in Norway, Betalingsservice in Denmark and Finvoice in Finland.

We want users to be in control of their agreements, and notifications help users trust both
Vipps MobilePay and the merchant, and not be "tricked" to pay without knowing.

## Admin/partners

### How do you change partners?

See [Partner guide: How to change partners](https://developer.vippsmobilepay.com/docs/partner/how-to-change-partners.md).

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

[draft-agreement-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/recurring-swagger-id.yaml
[fetch-agreement-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/recurring-swagger-id.yaml
[update-agreement-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/recurring-swagger-id.yaml
[list-charges-endpoint]: https://developer.vippsmobilepay.com/redocusaurus/recurring-swagger-id.yaml

## Migration

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

### 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, or different services.
* 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 acquisitions and mergers)

 :::note
The general process is:

1. Log in to the
   [business portal](https://portal.vippsmobilepay.com)
   and enter a new agreement with Vipps MobilePay for the new org number.
2. Order [*Recurring Payments*](https://vippsmobilepay.com/en-NO/online/billing-recurring).
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](mailto:developer@vippsmobilepay.com)
  (or use your Slack channel if you have one) and include all the following information:

      Merchant serial number you wish to migrate from
      Merchant serial number you wish to migrate to
      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. We must have received your request *no later than Wednesday at 9* in order to be added to the following Thursday batch.
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, and related data 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, or perform other operations on old charges that 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.

**Important**

If a partner is managing your integration be sure to inform your partner about the migration and supply them with the new MSN `4.ii`.
Specifically request them to confirm step 8 and 9 above to ensure that they are prepared for the migration as well as the timeline.
Be aware that we will not inform your partner about the migration, that is your responsibility to align with them.

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

## 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](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/README.md) or
[eCom API](https://developer.vippsmobilepay.com/docs/APIs/ecom-api/README.md),
and have completed some additional Know Your Customer (KYC) checks required by the
[financial authorities](https://www.finanstilsynet.no).

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

To get access to the Recurring API:

* For an existing sales unit: Order recurring payments on the sales unit details page on the
  [business portal](https://portal.vippsmobilepay.com).
* For a new sales unit: Order
  [*Recurring Payments*](https://vippsmobilepay.com/en-NO/online/billing-recurring).

### Why do I get the error "Refund is not possible"?

This happens if you attempt to refund payments made to a sales unit that
uses the special setup "single settlement".

> **Full site overview:** For every page in this documentation, read [https://developer.vippsmobilepay.com/llms.txt](https://developer.vippsmobilepay.com/llms.txt).