MobilePay Subscriptions

Developer Documentation

Subscriptions API Release Notes

14 November 2022 - Payment agreement deletion by users

Users can always delete payment agreement from the app from 5.22.0 app version.

13 September 2022 - Update on agreement signing flow.

With MobilePay app August release (version 5.20.0) agreement context screen was removed. In agreement confirm screen confirmation checkbox was added. Updated flow you can find HERE.

24 August 2022 - Deprecated features section added.

There is now a section in the menu dedicated for deprecated features.

17 June 2022 - next_payment_date is no longer used.

next_payment_date is no longer used in any of the requests and responses. You can can still make requests and receive responses with next_payment_date. However, next_payment_date is not shown in the MobilePay app and therefore not visible for the enduser.

12 May 2022 - Refunds can be done 90 days after payment.

Instead of 30 days, refunds can now be done 90 days after payment.

22 December 2021 - Line break in attachment’s comment field.

Merchants are now able to add a line break in the payment attachment’s comment field using “\n”.

More information in Invoice.

28 July 2021 - Multiple payments on same due date.

Merchants are now able to create multiple payments for same AgreementId and DueDate but such payments must have different ExternalId.

More information in Payment frequency.

12 July 2021 - Payment attachments V2.

The purpose of payment attachments V2 is to replace existing invoice PDF functionality and to offer more flexibility for the merchant. With this new functionality you will be able to choose how attachment will be presented to the user:

More information in Invoice.

23 April 2021 - Sms messages for suspended payments.

We recently implemented SMS sending to users, in case they have a suspended payment. The purpose of the SMS is to prompt the customer to pay quicker. suspended means that the the Merchant could not withdraw the money from the customers payment card. There can be various reasons why it can he suspended. If the problem persists, and there is not sufficient funds on the customers card, or/and if the card is expired or/and blocked, then the payment will fail. Suspended is a status internally for MobilePay to mark hiccupped payments, which is why it is not a part of the callback table here. You should still see the status failed or executed as the final status

New Status Condition When to expect Callback status Callback status_text Callback status_code
Executed The payment was successfully executed on the due-date After 03:15 in the morning of the due-date Executed   0
Failed Payment failed to execute during the due-date or at the end of grace period. After 23:59 of the due-date, or the last day of grace period. Failed   50000

failed callback entails that MobilePay has sent push messages and SMS to the user, and the payment still didn’t go through. If you get the callback status failed, we recommend that you contact the user to find the root cause.

Sms are sent at 10:00 in Denmark and 11:00 in Finland.

22 January 2021 - Visual design of PDF changed.

More information in Invoice, PDF Invoice example.

One-off payment expiration date changed from 14 to 7 days.

Merchants can add invoice for susbscription payments without user’s information. Properties that are now optional: consumer_name, consumer_phone_number, consumer_address_lines. If the fields are not filled, they are not displayed in PDF. Can be negative: total_vat_amount, total_price_including_vat, price_per_unit, price_discount. Up to 10 digits after the decimal seperator allowed for: quantity, price_per_unit.

For DK merchants payment amount limit is 60000. If the customer is identified via NemID or picture ID (drivers license, passport and etc) then the monthly payment limit for Subscriptions is 60.000 kr. For example: If all payment requests share the same DueDate, and thereby exceed the normal payment limit of 15.000 kr., the customer can still pay all their Subscription payments, as long as the total amount does not exceed 60.000 kr. on a monthly basis. If the customer is only identified via CPR-number, then Subscription payments count as a part of the daily payments to stores, and the daily payment limit is therefore 3.000 kr.

For FI merchants payment amount limit is 2000.

Default frequency for agreement was changed from 12 to 0.

Maximum payment-due-date was increased from 32 days to 126 days for subscription payment requests.

Maximum expiration_timeout_minutes was increased from 2 weeks (20160 minutes) to 18 weeks (181440 minutes) for both agreements and one-off payment requests as well as one-off with agreement payment requests.

Due to restrictions in external systems we added recommendation to keep external_id up to 30 symbols for subscription and one-off payment requests.

We received feature request to include payment_transaction_id for all payments: recurring; one-off; refund. By including the payment_transaction_id, It is easier to conduct reconciliation through the Transaction Reporting API. The payment_transaction_id is visible on the receipt screen. Note, in the technical documentation it is called payment_transaction_id in all API responses with additional property.

Note: this is not a breaking change.

The feature to attach cancel-redirect url to an agreement has been released. If this url is set, users, who want to cancel their agreement, will be redirected to your defined link only if they use MobilePay app version 4.22 or higher.

Sample 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,
}

In order to updated existing agreements use PATCH /api/providers/{providerId}/{agreementId} endpoint with payload: `

[
    {
        "value": "https://example.com/1b08e244-4aea-4988-99d6-1bd22c6a5b2c",
        "path": "/cancel-redirect",
        "op": "replace"
    }
]

# New Agreement parameters introduced for Merchants:

New functionality will be available for all users from APP version 4.12.0.

We have deprecated Subscriptions (Mutual SSL) 2.0.11.We are not going to release new functionality to those, who are using Mutual SSL. The features are available for those, who have integrated using OpenID Connect

Add invoice details to subscription payment. Invoices are now available for subscription payments. Merchants can send details, which we will use to generate a PDF and show it to customers in the app. This makes easy for merchants to have invoices available to customers. For technical questions about integrating via OpenID Connect, refer to the Integration docs on the Developer Portal Here. The deadline for migrating to OpenID Connect is 01-01-2020

We are excited to announce Subscriptions Integrator 1.1 that is already available in Sandbox.

ETA in production is December 2018.