Developer Documentation

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

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 Billwerk+ subscription.

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.

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

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.

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

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 desktop. When the app completes the payment, the app opens Billwerk + Checkout in a new browser tab which redirects back to 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 recommend to detect device type and use window mode for mobile devices.

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.

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.

MobilePay does not offer a testsystem 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 :