Setting up MobilePay Subscriptions

After obtaining an agreement with MobilePay the MobilePay Subscriptions agreement can be created in the Reepay Administration under Configuration → Acquiring.

🚧

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

Creating Checkout sessions

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

  1. A recurring session with all payment methods enabled or explicitly defining mobilepay_subscriptions in the list of payment_methods.
  2. 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 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 payment source when creating a Reepay subscription.

Phone number

If the customer phone number is already known it can be prefilled on the MobilePay Subscription signup page. The phone number can be defined in the following ways.

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

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.

Parameter.........................................

Description

mps_amount

Optional value to define MobilePay Subscriptions fixed recurring amount in minor unit. The amount is shown when signing up for the subscription. The default is that MobilePay Subscriptions show Flexible. For subscription sessions this will default to plan amount.

mps_plan

Optional MobilePay Subscriptions plan text shown when signing up. Maximum 30 characters. For subscription sessions this will default to plan name. For other session types default will be shop name set on agreement.

mps_description

Optional MobilePay Subscriptions additional description displayed to the customer. Maximum 60 characters. For subscription sessions this will default to plan description.

mps_next_payment_date

Optional MobilePay Subscriptions next payment date on the form yyyy-MM-dd to be displayed to the user. For subscription sessions this will default to the next payment date.

mps_frequency

Optional MobilePay Subscriptions frequency. Allowed values flexible, yearly, biyearly, quarterly, monthly, biweekly, weekly or daily. For subscription sessions this will default to plan frequency.

mps_external_id

Optional MobilePay Subscriptions id for subscription. Maximum 64 characters. For subscription sessions this will default to subscription handle.

mps_payment_description

Optional MobilePay Subscriptions description for payment created in conjunction with subscription signup. Will be presented if the signup also includes an initial payment. Maximum 60 characters. Defaults to shop name.

mps_cancel_redirect_url

Optional MobilePay Subscriptions merchant cancel redirect URL. If present, user will not be able to cancel within app, but instead will be redirected to this url.

MobilePay Subscriptions as 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 Reepay Checkout window.
If the payment is cancelled by the customer the cancel url/callback is invoked immediately without showing the Reepay Checkout window as it would only show MobilePay Subscriptions in this case.

Manual charging

Charging a saved MobilePay Subscriptions payment method is done with the charge resource using the saved payment method ms_… is given as 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 to offer 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. E.g. if the customer changes the underlying payment method for the subscription in the MobilePay app. See general error handling for charging here: https://reference.reepay.com/api/#create-charge

A MobilePay Subscriptions payment can be given a description shown in the push message sent to the customer on 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.

🚧

No partial settle

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

Refund

MobilePay Subscriptions refunds are asynchronous. The result of a refund operation is a refund with state processing. The result of the refund will subsequently be delivered by webhook. For details see https://reference.reepay.com/api/#create-refund.

❗️

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

Cancel authorization

As for a card can a MobilePay Subscriptions authorization be cancelled with the charge cancel operation: https://reference.reepay.com/api/#cancel-charge

Cancel subscription

A MobilePay Subscriptions payment method can be cancelled (removed in app) and deleted with a call to https://reference.reepay.com/api/#delete-payment-method or done i 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 testsystem for Subscriptions as they do for Online with a test app. To allow testing on a test account, Reepay 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 Reepay mock page allowing to simulate different scenarios when signing up. The following testing is possible:

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