MobilePay Subscriptions

Developer Documentation

Api principles

This is a preliminary list of architectural principles. The API documentation provides insight into the structure of the API and will help you determine the best approach for integration as well as provide details on typical use cases. Read through the reference to find information and examples for the calls

Error handling

Your MobilePay Subscriptions integration might have to deal with errors at some point when making API requests to MobilePay. MobilePay uses HTTP response status codes to indicate the success or failure of your API requests. These errors fall into a few major categories:

Your API integration should always check the HTTP response code to ensure correct handling of success and error conditions. ONLY an HTTP status of 200 means the request was successful. For non 200 responses, the predictable response body will give you details on why the request failed.

We suggest logging any failure response body as best practice; the MobilePay Developer support team will need the full response body to assist with troubleshooting. We recommend writing code that gracefully handles all possible API exceptions.

Errors

You might encounter the following HTTP errors:

  1. 400 - Bad Request , if request data is invalid. 
     {
     "error": "BadRequest",
     "error_description": {
         "message": "request.Name is required",
         "error_type": "InputError",
         "correlation_id": "f4b02597-32cc-420f-a468-942307e89a97"
     }
 }

  2. 404 - Not Found with no response body, if the resource (agreement or payment) is not found.

  3. 412 - Precondition Failed , if business validation rule was violated. 
     {
     "error": "PreconditionFailed",
     "error_description": {
         "message": "Duplicate payment.",
         "error_type": "PreconditionError",
         "correlation_id": "f4b02597-32cc-420f-a468-942307e89a97"
     }
 }
  4. 500 - Internal Server Error , if something really bad has happened. 
     {
     "error": "InternalServerError",
     "error_description": {
         "message": "An error occurred, please try again or contact the administrator.",
         "error_type": "ServerError",
         "correlation_id": "f4b02597-32cc-420f-a468-942307e89a97"
     }
 }

Checking Requests

There is no admin panel to check request, but you can use the following API calls:

API Change

Breaking changes

Our services change continually as we add new features, but we do our best to create stability so that the applications our clients build on top of our API can adapt gracefully as well. MobilePay will establish an appropriate timeline and regular communication with the API consumers to ensure that merchants and integrators migrate to the new version.

The following types of changes qualify as breaking changes:

Examples of non-breaking changes

The following types of changes do not qualify as breaking changes. Please note that this list is not exhaustive; these are just some examples of non-breaking changes.

API Version Status

External_id

When utilizing callbacks, it is important that you evaluate your usage of external_id, as it will be included in the request body of the refund callback, as well in the reference number and bank statement. External_id’s are not required to be unique however this is highly recommended. However, if the external_id in not unique the mapping could be more cluttered on merchant side. We recommend that the external_id for a payment should be associated with the specified orderId on merchant side. We recommend that the external_id for an Agreement should be associated with the specified customer number on merchant side.

Capture or cancellation of old reservations

All reservations should be captured or cancelled as soon as possible practically. If an error occurs that result in either cancellation or capture being impossible the client is responsible for persisting which payments should be captured at a later stage. We encourage you to capture as soon as a service is rendered or order shipped. It results in bad end-user experience, if the amount is reserved on the customer’s account for too long, as the customer can see the amount on their bank statement.

WebView

A WebView might be useful if the merchant needs more control over the UI and advanced configuration options that will allow the Merchant to embed web pages in a specially-designed environment for their app. It does not include any features of a fully developed web browser, such as navigation controls or an address bar. All that WebView does is show a web page.

If the Merchant uses WebViews in their app, the user will experience single device flow - MobilePay app will get opened for user to continue the flow.

Important configuration for Android Webview
In Android app if you set WebViewClient on Webview, then you must override shouldOverrideUrlLoading method exactly like this: 
    webView.setWebViewClient(new WebViewClient() {
        @Override
        public boolean shouldOverrideUrlLoading(WebView view, String url) {
            Uri uri = Uri.parse(url);
            if (uri.getHost().toLowerCase().contains("open.mobilepay.dk")) {
                Intent intent = new Intent(Intent.ACTION_VIEW, uri);
                intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_CLEAR_TASK);
                startActivity(intent);
                return true;
            }
            return false;
        }
    });
Without this code MobilePay app will not get opened.