MobilePay Subscriptions

Overview

General Notes

Subscription providers

Agreement

Create & Update

Callbacks

Subscription payments

Create & Update

Callbacks

One-off payments

Create & Update

Callbacks

Capture

Refund

Create

Callbacks

Invoice

Release notes

Mutual SSL Flow (DEPRECATED)

Overview

Billing your customers has never been easier before. This document explains how to make a technical integration to the MobilePay Subscription API. The audience for this document is either technical integrators acting on behalf of merchants or merchants themselves. You can find more information on our Developer Portal.

Our MobilePay Subscriptions REST api enables you to:

  1. Establish and manage Agreements between you, the Merchant, and MobilePay Users.
  2. Create Subscription Payments in relation to an established Agreement and get notified about the status via REST callbacks. Subscription Payments are requested 1 day before the actual booking date - no manual user confirmation required!

Merchant onboarding

You enroll to the Subscriptions Production via www.MobilePay.dk or the MobilePay Administration portal. Then you get access to the MobilePay Sandbox environment, where you can test the API. The Sandbox environment is located on The Sandbox Developer Portal You can use the Subscriptions API in test mode, which does not affect your live data or interact with the banking networks.

Authentication

OpenID Connect

When the merchant is onboarded, he has a user in MobilePay that is able to manage which products the merchant wishes to use.

The flow:

In short - The flow is described in the following 4 steps:

Step 1: Call /connect/authorize to initiate user login and consent

Step 2: Wait for the response by listening on the redirect URI and get the authorization code

Step 3: Exchange the authorization code for tokens using /connect/token

Step 4: Keep the session alive by using the refresh token

Step 5: Follow Best Practice

The merchant must grant consent to an application(Client). The client is the application that is attempting to get access to the user’s account. The client needs to get consent from the user before it can do so. This consent is granted through mechanism in the OpenID Connect protocol suite.
Integrators and merchants are the same as Clients in the OAuth 2.0 protocol. The Client must initiate the hybrid flow specified in OpenID connect. For Subscriptions product the Client must request consent from the merchant using the subscriptions scope. You also need to specify offline_access scope, in order to get the refresh token. The authorization server in sandbox is located here.
If the merchant grants consent, an authorization code is returned which the Client must exchange for an id token, an access token and a refresh token. The refresh token is used to refresh ended sessions without asking for merchant consent again. This means that if the Client receives an answer from the api gateway saying that the access token is invalid, the refresh token is exchanged for a new access token and refresh token.

An example of how to use OpenID connect in C# can be found here.

When user clicks on this button, merchant must do back-end call to
"/authorize" endpoint for initiating authentication flow. You need to wait for the response by listening on the redirect URI and get the Authorization Code. Our system will re-direct the merchant back to your system also using the redirect URL.

OpenID configuration endpoints

Find the configuration links below:

Environment Links
Sandbox Denmark https://sandprod-admin.mobilepay.dk/account/.well-known/openid-configuration
Finland https://sandprod-admin.mobilepay.fi/account/.well-known/openid-configuration
Production Denmark https://admin.mobilepay.dk/account/.well-known/openid-configuration
Finland https://admin.mobilepay.fi/account/.well-known/openid-configuration

QuickStart: follow our QuickStart to start building your integration

Implementing OpenID Connect protocol

There are many OpenID Connect certified libraries for different platforms, so you just have to chose the one, that suits you best from this list.

In order to authenticate to the API, all requests to the API must contain at least three authentication headers:

  1. x-ibm-client-id
  2. x-ibm-client-secret
  3. Authorization
$ curl --header "Authorization: Bearer <token>" --header 'x-ibm-client-id: client-id' --header 'x-ibm-client-secret: client-secret' --url https://<mobile-pay-root>/api/merchants/me/resource