After obtaining an agreement with Vipps/MobilePay, the Vipps MobilePay Recurring agreement can be created in the Billwerk + Administration under Configuration → Payment Methods.

📘

Notice

Vipps MobilePay Recurring refers to the new unified Vipps/MobilePay technical plaform.

As of 12/3 2024 all new agreements for Vipps Recurring / Mobilepay Recurring will be onboarded to Vipps/Mobilepay's new technical platform. If you are creating a new agreement follow this guide.

Creating Checkout Sessions

A recurring Vipps Recurring payment method is created by one of the following Billwerk+ Payments Checkout sessions:

• A recurring session with all payment methods enabled or explicitly defining vipps_recurring in the list of payment_methods.

• A charge session with recurring argument set to true. That is, a one-off payment can be created in conjunction with signing up with Vipps Recurring. This operation is atomic, so either both subscription and payment is completed, or both fails.

📘

Notice

The result of a successful session is in both cases a saved payment method with prefix vr_.

As for card, the payment method can be used for manual subsequent charging or as a payment source when creating a Billwerk+ subscription.

Phone Number

If the customer's phone number is already known, it can be prefilled on the Vipps Recurring signup page. The phone number can be defined in the following ways:

• Phone number can be given as an explicit argument phone when creating a session. If the customer entity has a phone number, that will be used.

Amount

A recurring session requires the usage of vipps_recurring_amount described in custom arguments below. If this parameter is not set, a default amount of 1 NOK will be shown on the agreement in the Vipps app.

Campaign

A campaign can be shown in the Vipps Recurring application when the customer is signing up for the agreement. On a subscription session and if the subscription is in trial, it will be mapped and displayed as a campaign to the customer. The campaign can also be customized using the parameters described below.

Manual Charging

Charging a saved Vipps Recurring payment method is done with the create charge using the saved payment method vr_… as the source argument.

Notice that Vipps Recurring payments are processed asynchronously. The result of the charge operation will be a charge with state pending and the processing flag set to true. The result of the payment can be detected using webhooks. The result will be delivered as event invoice_authorized, invoice_settled, or invoice_failed.

Notice that, if using the default option to schedule Vipps recurring payments, charging needs to be created minimum two days before the due date. Example: to charge the customer on April 1st 2024, create the charge on March 30th 2024.

VIpps recurring also supports an unscheduled charges. Select this option on the agrement to use unscheduled changes. Note that this needs to applied and approved by Vipps before it can be used.

Custom Arguments

Vipps Recurring has some custom parameters that can optionally be defined for a Checkout session. The parameters are given in the optional session_data object.

🔢 Steps for importing VippsMobilePay Subscriptions

📘

Notice

This is for VippsMobilepay's new unified Nordic platform. Requires existing VippsMobilepay agreement setup correctly in Billwerk.

Steps:

Preparation:

1. Get list of Vipps recurring agreement (mandate) references from old PSP. Consult with old PSP on how to do this.

Then for each customer:

1. Create customer in Billwerk platform → Create customer

2. Use this endpoint to import Vipps Recurring payment method: Import Vipps Recurring payment method

3. If successful a reference to a new payment method is returned. This is similar to the response here: Add payment method

It is also possible to create a customer in the same API call as import. For reference, please see Add payment method for an example of the create customer object.

Considerations when migrating VippsMobilePay Recurring

The merchant's agreement with VippsMobilePay is identified by a merchant serial number (MSN). If a merchant has several agreements with VippsMobilepay each will have a different MSN.

A "VippsMobilePay recurring agreement" is an agreement between a customer and the merchant that allows the merchant to deduct money via VippsMobilePay. This is also referred to as a "mandate" or a "payment method".

It is important to know which MSN a customer "VippsMobilePay recurring agreement" is connected to. If a different MSN is used in our administration then we cannot access the customer's recurring agreement and the import endpoint will return an error message.

Often a new VippsMobilePay merchant agreement (with new MSN) is created. This has the benefit that you can verify the implementation and handle new signups independently of the import process. But in this case, before you can do an import, VippsMobilepay support will have to move all the customers recurring agreements so they are attached to the new MSN.

The VippsMobilePay merchant agreement should select Billwerk as partner in VippsMobilePay's web portal. This is necessary for us to access merchant's data and receive payment webhooks.

Important VippsMobilePay only allows a single entity to be registered as a partner. If migrating from another payment gateway note that if you switch to Billwerk as partner it will immediately revoke access for the old payment gateway and they will receive no further payment updates.

This should also be taking into consideration when planning the import of existing customer VippsMobilePay recurring agreements.

Importing MobilePay Subscriptions

Existing MobilePay Subscriptions payment methods can be imported into the new Vipps MobilePay Recurring.

MobilePay has ensured that the old mobilepay identifiers can be used directly with Vipps MobilePay Recurring. The considerations above regarding correct MSN still applies. We can only import the payment method if the proper MSN is configured.

The import should follow the steps described in section "Steps for importing VippsMobilePay Subscriptions".