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)

General notes

MobilePay Subscriptions is a full-fledged HTTPS REST api using JSON as request/response communication media.

All dates and time-stamps use the ISO 8601 format: date format - YYYY-MM-DD, date-time format - YYYY-MM-DDTHH:mm:ssZ.

Amounts are enquoted with double quotation marks using 0.00 format, decimals separated with a dot.

When doing POST, PATCH or PUT requests, Content-Type: application/json HTTP header must be provided.

$ curl --request POST --header 'Content-Type: application/json' --url https://<mobile-pay-root>/resource --data '{}'

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

REST request correlation

CorrelationId is an optional Guid header value which can be used to link requests on your back-end system to MobilePay Subscriptions business transaction for a more convenient debugging.

$ curl --header 'CorrelationId: 37b8450b-579b-489d-8698-c7800c65934c' --url https://<mobile-pay-root>/api/merchants/me/agreements

REST callback authentication

Use one of these endpoints to set REST callback authentication scheme and credentials:

REST callback retries

Once the payment or agreement changes state, a callback will be done to the callback address, which is configurable via PATCH /api/providers/{providerId} with path value /payment_status_callback_url.

In case the REST callback failed, 8 retries will be made using the exponential back-off algorithm, where N - next retry time, c - retry attempt number, R - second retry time in seconds (1st retry is an exception and is done after 5 seconds):