New unified Vipps/MobilePay technical platform

📘

Notice

The following sections refer to the old MobilePay Subscriptions technical platform.

As of 12/3 2024 all new agreements for Vipps Recurring / Mobilepay Recurring will be on-boarded to Vipps/Mobilepay's new technical platform. If you are creating a new agreement, please follow the guide to Vipps MobilePay Recurring instead.

🚧

Warning

MobilePay Subscriptions merchant agreement

Notice that the auto-reserve feature must be enabled for the agreement with MobilePay.

🚧

Warning

Charge settle

Notice that MobilePay Subscription authorizations must be settled within 7 days. Settle attempts after 7 days will result in decline with transaction error authorization_expired.

Creating Checkout sessions

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

• A recurring session with all payment methods enabled or explicitly defining mobilepay_subscriptions 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 MobilePay Subscriptions. This operation is atomic, so either both subscription and payment is completed, or both fails.

The result of a successful session is in both cases a saved payment method with prefix ms_. As for card, the payment method can be used for manual subsequent charging or as a payment source when creating a Billwerk+ subscription.

Minimum amounts

📘

Notice

As of 12/3-2024 Vipps / Mobilepay require these minimum amounts for recurring payments:

• 0,1 DKK
• 0,01 EUR

💬 Custom arguments

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

💳 MobilePay Subscriptions as the only payment method

If MobilePay Subscriptions is the only payment method selected by using "payment_methods": ["mobilepay_subscriptions"], some special handling is performed:

• The customer will be redirected directly to MobilePay without showing the Billwerk+ Checkout window.
• If the payment is canceled by the customer, the cancel URL/callback is invoked immediately without showing the Billwerk+ Checkout window as it would only show MobilePay Subscriptions in this case.

📱 MobilePay Subscriptions on mobile devices

When MobilePay Subscriptions is used on a mobile device, the MobilePay page might activate an app switch to the MobilePay app instead of the normal flow as on the desktop. When the app completes the payment, the app opens Billwerk+ Checkout in a new browser tab which redirects back to the accept URL.

This means that the flow stops for the original tab, and the return is in a different tab. To use MobilePay Online on a mobile device with overlay and embedded mode, it is required to use accept and cancel URLs to be able to return. We rec

💰 Manual Charging

Charging a saved MobilePay Subscriptions payment method is done with the create charge using the saved payment method ms_… as the source argument.

Notice that MobilePay Subscriptions 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.

In the case that the underlying payment method in the MobilePay wallet fails, e.g., insufficient funds on a credit card, the user will receive a push notification to update the payment method. By default, the user has ten minutes to complete this update before the payment fails. The duration for which there should be waited for a payment method update can be overridden when a charge is created using the parameters object and setting the mps_ttl attribute. Example with one hour.

...
"amount": 10000,
"parameters": {
    "mps_ttl": "PT1H"
},
...

Notice that charging a saved payment method may only be done in MIT scenarios where the customer is not present due to PSD2 regulations. In customer present CIT scenarios, we recommend offering MobilePay Online as a payment option. For more on PSD2, see Strong Customer Authentication.

If a MobilePay Subscriptions payment method has been cancelled, either by the customer in the app or by you, the merchant, the charge call will fail with error state hard_declined and error credit_card_expired. In this case, the payment method should be removed, as all subsequent uses of the payment method will fail. If the error state is soft_declined with error declined_by_acquirer, the payment was rejected, but it may succeed at a later stage. For example, if the customer changes the underlying payment method for the subscription in the MobilePay app.

See general error handling for charging create charge.

A MobilePay Subscriptions payment can be given a description shown in the push message sent to the customer in the app on the payment. To define the description, the argument text_on_statement can be used. The description defaults to the shop name.

🚧

Caution

No partial settle

Notice that MobilePay Subscriptions does not support partial settles. Only the full amount can be captured.

💵 Refund

MobilePay Subscriptions refunds are synchronous, so the result is instantly available when performing a refund. For details, see create refund. Some special rules apply for MobilePay Subscriptions refunds:

🚧

Warning

Refund not possible with 'instant transfer`

The payout method configured at MobilePay can either be 'daily' or 'instant transfer.' Refunds are only possible with the option Daily. For details see the section 'Subscriptions API - Transfers' here: https://developer.mobilepay.dk/subscriptions-payments

🚧

Warning

Refund possible in 90 days

Refunds are only possible up to 90 days after a payment has been performed.

Cancel authorization

As for a card can a MobilePay Subscriptions authorization be cancelled with the charge cancel operation: cancel charge

Cancel subscription

A MobilePay Subscriptions payment method can be cancelled (removed in app) and deleted with a call to delete payment method or done in the Administration. Potential subsequent charging will fail with the "no payment method found" error.

Subscription cancel from app

If mps_cancel_redirect_url has not been defined, the customer can cancel the subscription from within the app. A cancel will result in the error state of the payment method changed to hard_declined and error to credit_card_expired. Subsequent charges will fail with the same error state and error.

MobilePay Subscriptions Testing

MobilePay does not offer a test system for Subscriptions as they do for Online with a test app. To allow testing on a test account, Billwerk+ has a MobilePay Subscriptions mock system. On a test account, simply create a MobilePay Subscriptions agreement in Configuration → Acquiring → New Acquirer. MobilePay Subscriptions is now available as a payment method.

For signup, there is a Billwerk+ mock page allowing to simulate different scenarios when signing up. The following testing is possible:

• Signup with charge, recurring, or subscription session, and simulating different outcomes.
• Make charges with the saved payment method. The amount 3002 (minor unit) will trigger a declined payment.
• Cancel authorized charges.
• Settle authorized charges.
• Refund settled charges.
• Delete payment method.
• A subscription cancel from the app can be triggered by a link given on the simulated signup page.

🔢 Steps for importing MobilePay Subscriptions:

📘

Notice

This is for "legacy" MobilePay Subscriptions to existing activated MPS agreement in Billwerk.

ALL new agreements will be created on new unified Vipps MobilePay technical platform. Here it is currently not possible to migrate/import subscriptions.

Steps:

0. Get list of MobilePay subscription references from old PSP. Consult with old PSP on how to do this.

For each customer:

1. Create customer in Billwerk platform → Create customer

2. Use this endpoint to import MPS subscription: https://api.reepay.com/v1/pay/v1/payment_method/import_mps. This is only documented in OpenAPI specification: https://api.reepay.com/openapi.json. See definition of ImportMpsPaymentMethodRequest for parameters:

   • customer_handle
   • mobile_pay_id

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

It is possible to create a customer in the same API call as import. If they would like to do this have a look at e.g. Add payment method for an example of the create customer object.