Skip to main content

Subscriptions API

The MobilePay Subscriptions API uses OAuth 2.0 protocol for authentication and authorization and contains endpoints needed to implement MobilePay Subscriptions in your system. This API is for the technical integrator acting on behalf of merchant, or merchant creating their own integrations. MobilePay Subscriptions allow you to offer recurring billing for your customers, including One-off payments and Refunds.
Documentation

Subscriptions Merchant

Get merchant's information and a list of subscription providers.

Authorizations:
Bearer
header Parameters
Authorization
required
any

Id for user performing action (Must be a valid GUID)

CorrelationId
string

CorrelationId used for logging

Responses

Response samples

Content type
No sample

Subscriptions

The MobilePay Subscriptions API contains endpoints for the merchants, needed to implement MobilePay Subscriptions in your system. MobilePay Subscriptions allow you to offer recurring billing for your customers, including one-off payments.

Get configuration details.

Gets own configuration details: payment_status_callback_url, scheme, key, password, scope.

Authorizations:
Bearer
path Parameters
providerid
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

Responses

Response samples

Content type
No sample

Update subscription provider's details.

Updates subscription provider's details. It's request must match the rules of RFC 6902 JSON Patch standards

Available operations:

  • replace

Available properties:

  • payment_status_callback_url

payment_status_callback_url - url where callbacks should be sent for payments.

Authorizations:
Bearer
path Parameters
providerid
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

Request Body schema:
Array
object or null
path
string or null
op
string or null
from
string or null

Responses

Request samples

Content type
[
  • {
    }
]

Response samples

Content type
No sample

Change REST callback authentication scheme to OAuth2.

The OAuth2 authentication scheme follows RFC 6749 flow defined in section 4.4.

First a call will be made to token_url using basic authentication with provided client_id and client_secret in order to obtain bearer token.

All subsequent REST requests will contain the bearer token in Authorization header, as defined in RFC 6749 section 4.4.

Authorizations:
Bearer
path Parameters
providerid
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

Request Body schema:
client_id
required
string
client_secret
required
string
token_url
required
string
scope
string or null

Responses

Request samples

Content type
{
  • "client_id": "string",
  • "client_secret": "string",
  • "token_url": "string",
  • "scope": "string"
}

Response samples

Content type
No sample

Change REST callback authentication scheme to Api Key.

The provided API key will be added to Authorization HTTP header for all REST callback requests.

Authorizations:
Bearer
path Parameters
providerid
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

Request Body schema:
api_key
required
string

Responses

Request samples

Content type
{
  • "api_key": "string"
}

Response samples

Content type
No sample

Change REST callback authentication scheme to Basic.

All the REST callbacks will contain basic credentials in Authorization HTTP header: Authorization: Basic [Base64 encoded username:password].

Authorizations:
Bearer
path Parameters
providerid
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

Request Body schema:
password
required
string
user_name
required
string

Responses

Request samples

Content type
{
  • "user_name": "string",
  • "password": "string"
}

Response samples

Content type
No sample

Create a new Subscriptions agreement.

Creates a new Subscriptions agreement with status "Pending" which will be prompted for user to confirm in the MobilePay app.

The response will contain a single hypermedia link with "rel" parameter set to "mobile-pay". The user must be redirected to this address in order to prompt agreement details for confirmation in the app. As soon as the agreement is confirmed or the sign-up flow canceled, we will notify you by doing a POST request at one of the callback URLs that are provided in the "links" collection:

  • If agreement was created successfully, we will POST you at the link rel=" success-callback";.
  • If user has canceled the flow, we will do a POST to link rel="cancel-callback".

When the agreement creation flow is complete, the agreement status will be changed to "Accepted". Regardless of whether agreement was accepted or rejected user will be navigated to link rel=" user-redirect".

Authorizations:
Bearer
path Parameters
providerid
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

Request Body schema:
country_code
required
string
currency
required
string
expiration_timeout_minutes
required
integer <int32> [ 1 .. 181440 ]
required
Array of objects (Shared.Models.ResourceLink)
plan
required
string [ 0 .. 30 ] characters
external_id
string or null [ 0 .. 64 ] characters
amount
number or null <double>
description
string or null [ 0 .. 60 ] characters
next_payment_date
string or null <date-time>
frequency
integer or null <int32>
mobile_phone_number
string or null
object (RestAPI.Models.Merchant.OneOffPaymentDetails)
disable_notification_management
boolean or null
notifications_on
boolean or null
retention_period_hours
integer <int32> [ 0 .. 24 ]

Responses

Request samples

Content type
{
  • "external_id": "string",
  • "amount": 0,
  • "currency": "string",
  • "description": "string",
  • "next_payment_date": "2019-08-24T14:15:22Z",
  • "frequency": 0,
  • "links": [
    ],
  • "country_code": "string",
  • "plan": "string",
  • "expiration_timeout_minutes": 1,
  • "mobile_phone_number": "string",
  • "one_off_payment": {
    },
  • "disable_notification_management": true,
  • "notifications_on": true,
  • "retention_period_hours": 24
}

Response samples

Content type
No sample

Get the list of Subscriptions agreements.

Authorizations:
Bearer
path Parameters
providerid
required
string <uuid>

Subscription provider id.

query Parameters
status
string or null

The agreement status.

pageSize
integer or null <int32>

Quantity of agreements that response should contain.

pageNumber
integer or null <int32>

Page number if you're using MS SQL.

header Parameters
CorrelationId
string

CorrelationId used for logging

Responses

Response samples

Content type
No sample

Get the details of subscription agreement.

Authorizations:
Bearer
path Parameters
providerid
required
string <uuid>
agreementid
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

Responses

Response samples

Content type
No sample

Update subscription agreement details.

Updates agreement by id. It's request must match the rules of RFC 6902 JSON Patch standards

Available operations:

  • replace

Available properties:

  • amount
  • plan
  • description
  • next_payment_date
  • frequency
  • external_id
  • success-callback
  • cancel-callback.
Authorizations:
Bearer
path Parameters
providerid
required
string <uuid>
agreementid
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

Request Body schema:
Array
object or null
path
string or null
op
string or null
from
string or null

Responses

Request samples

Content type
[
  • {
    }
]

Response samples

Content type
No sample

Cancel subscription agreement.

Cancels an 'active or 'pending' agreement.

Authorizations:
Bearer
path Parameters
providerid
required
string <uuid>
agreementid
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

Responses

Response samples

Content type
No sample

Request a payment batch for later execution.

Authorizations:
Bearer
path Parameters
providerid
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

Request Body schema:
Array
agreement_id
required
string <uuid>
amount
required
number <double> [ 0.01 .. 2147483647 ]
description
required
string [ 0 .. 60 ] characters
due_date
required
string
external_id
required
string [ 0 .. 64 ] characters
next_payment_date
string or null <date-time>
grace_period_days
integer or null <int32> [ 1 .. 3 ]
object (RestAPI.Models.Invoice)

Responses

Request samples

Content type
[
  • {
    }
]

Response samples

Content type
No sample

Get a list of agreement's payments.

Authorizations:
Bearer
path Parameters
providerid
required
string <uuid>
agreementid
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

Responses

Response samples

Content type
No sample

Get single payment details.

Authorizations:
Bearer
path Parameters
providerid
required
string <uuid>
agreementid
required
string <uuid>
paymentid
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

Responses

Response samples

Content type
No sample

Update a pending payment request.

Updates a pending payment request by id. It's request must match the rules of RFC 6902 JSON Patch standards

Available operations:

  • replace

Available properties:

  • amount

It can be updated with an amount which is less than the pending amount.

Authorizations:
Bearer
path Parameters
providerid
required
string <uuid>
paymentid
required
string <uuid>
agreementid
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

Request Body schema:
Array
object or null
path
string or null
op
string or null
from
string or null

Responses

Request samples

Content type
[
  • {
    }
]

Response samples

Content type
No sample

Decline a 'pending' subscriptions payment.

Authorizations:
Bearer
path Parameters
providerid
required
string <uuid>
paymentid
required
string <uuid>
agreementid
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

Responses

Response samples

Content type
No sample

Request one-off payment on an existing agreement.

Authorizations:
Bearer
path Parameters
providerid
required
string <uuid>
agreementid
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

Request Body schema:
amount
required
number <double> [ 0.01 .. 2147483647 ]
description
required
string
external_id
required
string [ 0 .. 64 ] characters
Array of objects or null (Shared.Models.ResourceLink)
object (RestAPI.Models.Invoice)
auto_reserve
boolean
expiration_timeout_minutes
integer or null <int32> [ 1 .. 181440 ]

Responses

Request samples

Content type
{
  • "amount": 0.01,
  • "external_id": "string",
  • "description": "string",
  • "links": [
    ],
  • "invoice": {
    },
  • "auto_reserve": true,
  • "expiration_timeout_minutes": 1
}

Response samples

Content type
No sample

Get a list of one-off payments by agreement id.

Authorizations:
Bearer
path Parameters
providerid
required
string <uuid>
agreementid
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

Responses

Response samples

Content type
No sample

Get single one-off payment details.

Authorizations:
Bearer
path Parameters
providerid
required
string <uuid>
agreementid
required
string <uuid>
paymentid
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

Responses

Response samples

Content type
No sample

Cancel a requested/reserved one-off payment.

Authorizations:
Bearer
path Parameters
providerid
required
string <uuid>
agreementid
required
string <uuid>
paymentid
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

Responses

Response samples

Content type
No sample

Capture reserved one-off payment.

Authorizations:
Bearer
path Parameters
providerid
required
string <uuid>
agreementid
required
string <uuid>
paymentid
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

Responses

Response samples

Content type
No sample

Get payment attachment details.

Authorizations:
Bearer
path Parameters
providerid
required
string <uuid>
paymentid
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

Responses

Response samples

Content type
No sample

Update payment attachment.

Authorizations:
Bearer
path Parameters
providerid
required
string <uuid>
paymentid
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

Request Body schema:
external_attachment_url
string or null
generate_pdf
boolean
object (RestAPI.Models.Payments.UpdatePaymentAttachmentDetailsRequest)

Responses

Request samples

Content type
{
  • "external_attachment_url": "string",
  • "generate_pdf": true,
  • "attachment_details": {
    }
}

Response samples

Content type
No sample

Delete payment attachment.

Authorizations:
Bearer
path Parameters
providerid
required
string <uuid>
paymentid
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

Responses

Response samples

Content type
No sample

Get payment attachment file.

Authorizations:
Bearer
path Parameters
providerid
required
string <uuid>
paymentid
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

Responses

Response samples

Content type
No sample

Subscriptions Refund

The MobilePay Subscriptions Refund API contains endpoints for the merchants, needed to implement MobilePay Subscriptions refunds in your system.

Get refunds.

path Parameters
providerid
required
string <uuid>
agreementid
required
string <uuid>
paymentid
required
string <uuid>
header Parameters
Authorization
required
any

Authentication token (must contain valid merchant id)

CorrelationId
string

CorrelationId used for logging

Responses

Response samples

Content type
No sample

Request a new refund.

path Parameters
providerid
required
string <uuid>
agreementid
required
string <uuid>
paymentid
required
string <uuid>
header Parameters
Authorization
required
any

Authentication token (must contain valid merchant id)

CorrelationId
string

CorrelationId used for logging

Request Body schema:
amount
number or null <double> [ 0.01 .. 2147483647 ]
statusCallbackUrl
string or null
externalId
string or null

Responses

Request samples

Content type
{
  • "amount": 0.01,
  • "statusCallbackUrl": "string",
  • "externalId": "string"
}

Response samples

Content type
No sample

Subscriptions User Simulation

This API is used to simulate app functionality for testing your implementation of MobilePay Subscriptions.

Accept/Reject agreement.

Possible status values: "Accepted", "Rejected".

path Parameters
id
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

Request Body schema:
status
string or null
notifications_on
boolean

Responses

Request samples

Content type
{
  • "status": "string",
  • "notifications_on": true
}

Response samples

Content type
No sample

Accept/Reject one off payment.

Possible status values: "Accepted", "Rejected".

path Parameters
agreementid
required
string <uuid>
paymentid
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

Request Body schema:
Array
object or null
path
string or null
op
string or null
from
string or null

Responses

Request samples

Content type
[
  • {
    }
]

Cancel agreement.

Possible status values: "Canceled".

path Parameters
agreementid
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

Request Body schema:
status
string or null

Responses

Request samples

Content type
{
  • "status": "string"
}

Reject payment.

path Parameters
paymentid
required
string <uuid>
header Parameters
CorrelationId
string

CorrelationId used for logging

Responses