MobilePay Subscriptions

Overview

Authentication

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)

Glossary

Get Started

API Principles

Error Handling

API Change

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"
         }
     }
    

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.