Vipps MobilePay Recurring
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 ofpayment_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.
![Vipps Recurring agreement setup with unscheduled charges activated](https://files.readme.io/4951739-image.png)
Vipps Recurring agreement setup with unscheduled charges activated
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.
Parameter | Value | Description |
---|---|---|
vipps_recurring_amount | Optional | Value to define Vipps Recurring fixed recurring amount in minor unit. Example '1000' will display 10 NOK for the customer in the application. |
vipps_recurring_product_name | Optional | Vipps Recurring product name displayed to the customer. |
vipps_recurring_pricing_type | Optional | Vipps Recurring subscription pricing type. |
vipps_recurring_product_description | Optional | Vipps Recurring additional product description displayed to the customer.` |
vipps_recurring_interval_count | Optional | Vipps Recurring payment interval count to be displayed to the customer. Example 1 combined with vipps_recurring_interval_unit set to month and vipps_recurring_amount set to 1000 will display 10 NOK every 12 month for the customer in the application. |
vipps_recurring_interval_unit | Optional | Vipps Recurring payment interval unit to be displayed to the customer. Can be one of the following values: 'day', 'week', 'month' or 'year'. Combine vipps_recurring_interval_count to specify how often customer will be charged. |
vipps_recurring_initial_payment_description | Optional | Vipps Recurring description for initial payment created in conjunction with subscription signup. |
vipps_recurring_merchant_cancel_url | Optional | Vipps Recurring agreement cancel URL. |
vipps_recurring_campaign_amount | Optional | Amount for Vipps Recurring campaign in minor unit. |
vipps_recurring_campaign_interval_count | Optional | Vipps Recurring campaign interval count to be displayed to the customer. |
vipps_recurring_campaign_interval_unit | Optional | Vipps Recurring campaign interval unit to be displayed to the customer. One of the following values: 'year', 'month', 'week' or 'day'. |
vipps_recurring_campaign_end_date | Optional | Vipps Recurring campaign end date to be displayed to the user, the date must be UTC and cannot be the past. Please note that this parameter cannot be used together with: vipps_recurring_campaign_interval_count and/or vipps_recurring_campaign_interval_unit |
🔢 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:
- Get list of Vipps recurring agreement (mandate) references from old PSP. Consult with old PSP on how to do this.
Then for each customer:
-
Create customer in Billwerk platform → Create customer
-
Use this endpoint to import Vipps Recurring payment method: Import Vipps Recurring payment method
-
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.
Updated 16 days ago