MobilePay Subscriptions

Agreements

An agreement is used to provide subscription service to sell to Customers.

MobilePay Subscriptions is a flexible service, that allows merchant to tailor the user experience to their needs by using normal agreements, agreement with an initial one-off payment, agreements with a period where the price is lower than usual, and existing agreements where the customer wants to buy an add-on.

Once the user is given to choose the payment method on the merchant’s signup flow, an “Pay with MobilePay” button should be shown for the user to be able to click on. The MobilePay button must adhere to our branding guidelines here. When user clicks on this button, merchant’s back-end system must call the POST /api/providers/{providerId}/agreements endpoint in order to create a Pending Subscription Agreement, which can only be activated by the MobilePay user through the app. After agreement confirmation, user is redirected to merchant success page, and the Merchant logo is shown under Active Agreements in the MobilePay app. If user did not manage to confirm agreement, the customer sees a timeout screen if they are on dual device. If they are on app, nothing is displayed.

When the user has accepted the agreement in the MobilePay app, then the Merchant can charge Subscription payments POST /api/providers/{providerId}/paymentrequests and One-Off payments POST /api/providers/{providerId}/agreements/{agreementId}/oneoffpayments.

Create agreement request

{
  "external_id": "AGGR00068",
  "amount": "10",
  "currency": "DKK",
  "description": "Monthly subscription",
  "frequency": 12,
  "links": [
    {
      "rel": "user-redirect",
      "href": "https://example.com/1b08e244-4aea-4988-99d6-1bd22c6a5b2c"
    },
    {
      "rel": "success-callback",
      "href": "https://example.com/1b08e244-4aea-4988-99d6-1bd22c6a5b2c"
    },
    {
      "rel": "cancel-callback",
      "href": "https://example.com/1b08e244-4aea-4988-99d6-1bd22c6a5b2c"
    },
    {
      "rel": "cancel-redirect",
      "href": "https://example.com/1b08e244-4aea-4988-99d6-1bd22c6a5b2c"
    }
  ],
  "country_code": "DK",
  "plan": "Basic",
  "expiration_timeout_minutes": 5,
  "mobile_phone_number": "4511100118",
  "retention_period_hours": 0,
  "disable_notification_management": false,
  "notifications_on": true
}

mobile_phone_number is not required. Neither for agreement creation, or one-off creation. If you choose to add it, the phone number will be prefilled on our landing page. So that the user will not have to type the phone number on the landing page, which makes it more convenient for the user, if you add mobile_phone_number. We cannot enclose any phone number updates (if any) to the Merchant. We do not notify the merchant if the prefilled number was used / not used.

cancel-redirect

cancel-redirect makes it possible for customers to cancel the agreement in merchants own environment, and the merchant gets more flexibility on terms of retention strategies for their possible leaving customers.

The cancel-redirect is not mandatory, since the Merchant should only use cancel-redirect if they have a self-service environment, where a cancel or unsubscribe button is visible. The Merchant should ensure that the customer can easily cancel the agreement on their own self-service environment. To ensure the best ustomer experience, a clear “Unsubsribe” or “Cancel” button should be present on the merchant website.

The cancel-redirect is a link to a website, where the customer can manage the agreement: Change, pause, cancel, etc. MobilePay does not offer any form of agreement management, like changing subscription types or price, temporary address change, etc. The URL is opened in the standard web browser. The integrator must implement such functionality for the customer to manage the agreement in their system. When a user notifies the merchant that they want to cancel a subscription or service, the merchant must ensure that the status of the agreement is set to cancelled at a suitable time. However, if the customer wants to pause the agreement, then we highly recommend that you update the parameter description so the customer knows what the status of the payment is. Furthermore, we highly recommend that you send a receipt to the customer via email or SMS, so they are sure that the agreement change has been established.

How is this implemented?

For new agreements, use endpoint POST /api/providers/{providerId}/agreements with cancel-redirect link. A new link allows agreement to be cancelled in merchant own environmnet. Merchant should ensure easy access to information and support. For existing agreements: use endpoint PATCH /api/providers/{providerId}/agreements{agreementId} endpoint to change agreement request parameters

The Pending Agreement, if not activated, will expire within the value, provided in the expiration_timeout_minutes.

Request parameters for Create agreement request

Please note: You should consider which parameter in the table below should be used. Not all parameters are required, but the user will see amount, plan and description in the Agreement screen, if you choose to use those parameters. For example: if you have a campaign where the subscription is cheaper in the beginning, users will be confused by how it appears in the MobilePay app, as it might look like the full price period starts immediately, if you enter the full price in amount

Agreements response

The response of POST /api/providers/{providerId}/agreements contains two values: a unique id of the newly created Pending Agreement and a link rel = mobile-pay.

{
  "id": "1b08e244-4aea-4988-99d6-1bd22c6a5b2c",
  "links": [
    {
      "rel": "mobile-pay",
      "href": "https://<mobile-pay-landing-page>/?flow=agreement&id=1b08e244-4aea-4988-99d6-1bd22c6a5b2c&redirectUrl=https%3a%2f%2fwww.example.com%2fredirect&countryCode=DK&mobile=4511100118"
    }
  ]
}

• The id value can be used on the merchant’s back-end system to map a Subscription agreement with a specific user on the merchant’s side, and subsequently to create new Payment Requests on behalf of the user who confirmed the agreement in MobilePay.
• The link rel = mobile-pay value contains the hyperlink reference address, which is structured in the following way: https://<mobile-pay-landing-page>/?id=318a0bf9-9039-400c-b5ff-6ec717da2971&countryCode=DK. (The link is not accessible in sandbox, only in production) The id property is of type guid and uniquely identifies the pending Subscription Agreement for the app to get the details and subsequently do an accept request. The countryCode property is used to differentiate between DK and FI apps.

The link can be used in two ways:

1. Redirect the user automatically using the HTTP response 302 or 303. Once the user is redirected, the MobilePay app will be opened to activate the Pending Agreement. In this case, it is recommended to set the expiration_timeout_minutes value to 5 minutes.
2. E-mail the generated link to the user. Once the user clicks on the link, the MobilePay app will be opened to activate the Pending Agreement. In this case, it is recommended to set the expiration_timeout_minutes to a higher value (10080 - a week, 20160 - two weeks). Note, that the link will be valid only until the user accepts the agreement or a timeout occurs.

Update existing Agreement Request

It is the merchant’s responsibility to manage and update the agreements, and to use the API to make sure everything is in sync.

Use the PATCH /api/providers/{providerId}/agreements/{agreementId} endpoint to change agreement request parameters. Its request must match the rules of RFC 6902 JSON Patch standards.

• Available operations: replace
• Available properties: amount, plan, description, frequency, external_id, success-callback, cancel-callback, cancel-redirect, disable_notification_management

[
    {
        "value": "10.01",
        "path": "/amount",
        "op": "replace"
    }
]

For example: The customer has created Streaming Premium+ on started on the 1 January 2021, which costs 100kr. On the 1st of March 2021, the customer decides to upgrade to Streaming Premium+ which costs 150kr. The Merchant should then update amount and plan parameters to reflect those changes.

Setting disable_notification_management to true will disable notification management and turn off notifications for the agreement.

Agreement signing in dual device flow

Agreement signing in single device flow

Agreement screen with and without amount parameter

Translations of text in confirmation checkbox

Existing and Deleted agreements

Agreement screen required and optional parameters

The purple parameters below are visible in the MobilePay app on the Agreement screen if they are used by the merchant. They are optional, and should only be used, if the merchant finds that they provide informative value to the customer.

Callbacks

When the Agreement’s status changes from Pending we will do a callback to the merchant’s system (see the sequence diagram below).

The table below shows possible status, status_text and status_code values depending on the Agreement status changes.

You do not get a callback that tells you specifically if/when the user closes the landing page with the timer.

If there should be a pause in an agreement, like a temporary stop of a subscription: Simply do not create any charges during the pause. You might want to update the description field of the agreement so the user can see that the subscription is paused in MobilePay. The endpoint DELETE /api/providers/{providerId}/agreements/{agreementId} will cancel the agreement, so we recommend that the merchant only uses that endpoint if the customer clearly notifies the merchant that they want to cancel a subscription or service. Cancelled agreements can not be reactivated.

Agreement state diagram

Other callback properties

Agreement callback request example

{
    "agreement_id" : "63679ab7-cc49-4f75-80a7-86217fc105ea",
    "status" : "Canceled",
    "status_text" : "Canceled by user",
    "status_code" : "40000",
    "external_id" : "SF0000568",
    "timestamp" : "2020-01-01T12:34:56+00:00"
}

user-redirect

When the Agreement activation is complete or canceled, the user will be navigated to the link rel = user-redirect to finalize the signup. Please ensure that your usage of user-redirect is well implemented at the merchant side. When the Agreement activation is completed or canceled, the user will be navigated to the link rel = user-redirect to finalize the signup.

rel = user-redirect should be a webpage, that awaits the callbacks and then takes appropriate action, depending on if the agreement was accepted or not. Based on the callback, you will redirect the user to the right place. Most merchants navigate the customer to a self-service overview, where the agreement is pending, and once the merchant receives the callback, then the merchant can update the status. Most merchants have a general page, that says “thank you for your order/support”, and then it informs about the next step. It is triggered immediately after purchase, letting customers know that their order and agreement has been received and created

Merchants can add their internal order ID to the rel = user-redirect when they create the agreement. For example https://www.merchantwebsite.com/ourcallback?order_id= This way, the merchant knows, which order the *rel = user-redirect* should handle. It is therefore a prerequisite that the merchant has an internal order ID on their side. By including the internal order ID to the *rel = user-redirect*, the merchant also has a back-up solution, in case the end customer is using incognito, as incognito makes session management, tracking and cookie storage more complex. The *rel = user-redirect* does not need to be whitelisted by MobilePay.

Please note: user-redirect is primarily for the visual user experiance. The merchant should be aware of the fact that the user might close the browser, the internet might fail etc. There are cases where the user and browser interrupt the flow, and MobilePay can’t control these cases.

MobilePay doesn’t do logging on the user-redirect, since part of the data is in in the app and part of the data is in landing page, hence it would be a very complicated set up. ​ All proper data comunication and logging and monitoring should be done thorugh callbacks and GET calls.

Agreement creation sequence diagram

When merchant cancels agreement - sequence diagram

When user cancels a Pending agreement during signup - sequence diagram

When user cancels an Active agreement - sequence diagram