MobilePay Subscriptions

Developer Documentation

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):