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
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:
path Parameters
| providerid required | string <uuid> |
header Parameters
| CorrelationId | string CorrelationId used for logging |
Responses
Response samples
- 200
- 400
- 500
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:
path Parameters
| providerid required | string <uuid> |
header Parameters
| CorrelationId | string CorrelationId used for logging |
Request Body schema:
object or null | |
| path | string or null |
| op | string or null |
| from | string or null |
Responses
Request samples
- Payload
[- {
- "value": { },
- "path": "string",
- "op": "string",
- "from": "string"
}
]Response samples
- 400
- 500
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:
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
- Payload
{- "client_id": "string",
- "client_secret": "string",
- "token_url": "string",
- "scope": "string"
}Response samples
- 400
- 500
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:
path Parameters
| providerid required | string <uuid> |
header Parameters
| CorrelationId | string CorrelationId used for logging |
Request Body schema:
| api_key required | string |
Responses
Request samples
- Payload
{- "api_key": "string"
}Response samples
- 400
- 500
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:
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
- Payload
{- "user_name": "string",
- "password": "string"
}Response samples
- 400
- 500
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:
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
- Payload
{- "external_id": "string",
- "amount": 0,
- "currency": "string",
- "description": "string",
- "next_payment_date": "2019-08-24T14:15:22Z",
- "frequency": 0,
- "links": [
- {
- "rel": "string",
- "href": "string"
}
], - "country_code": "string",
- "plan": "string",
- "expiration_timeout_minutes": 1,
- "mobile_phone_number": "string",
- "one_off_payment": {
- "amount": 0.01,
- "external_id": "string",
- "description": "string",
- "expiration_timeout_minutes": 1
}, - "disable_notification_management": true,
- "notifications_on": true,
- "retention_period_hours": 24
}Response samples
- 201
- 400
- 500
Get the list of Subscriptions agreements.
Authorizations:
path Parameters
| providerid required | string <uuid> Subscription provider id. |
query Parameters
| pageNumber required | integer <int32> Page number if you're using MS SQL. Initial request should have pageNumber=1 |
| status | string or null The agreement status. |
| pageSize | integer or null <int32> Quantity of agreements that response should contain. |
header Parameters
| CorrelationId | string CorrelationId used for logging |
Responses
Response samples
- 200
- 400
- 500
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:
path Parameters
| providerid required | string <uuid> |
| agreementid required | string <uuid> |
header Parameters
| CorrelationId | string CorrelationId used for logging |
Request Body schema:
object or null | |
| path | string or null |
| op | string or null |
| from | string or null |
Responses
Request samples
- Payload
[- {
- "value": { },
- "path": "string",
- "op": "string",
- "from": "string"
}
]Response samples
- 400
- 500
Cancel subscription agreement.
Cancels an 'active or 'pending' agreement.
Authorizations:
path Parameters
| providerid required | string <uuid> |
| agreementid required | string <uuid> |
header Parameters
| CorrelationId | string CorrelationId used for logging |
Responses
Response samples
- 400
- 412
- 500
Request a payment batch for later execution.
Authorizations:
path Parameters
| providerid required | string <uuid> |
header Parameters
| CorrelationId | string CorrelationId used for logging |
Request Body schema:
| 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 ] |
Responses
Request samples
- Payload
[- {
- "agreement_id": "67dd069b-637c-4b8e-8d92-17a313d06fb8",
- "amount": 0.01,
- "due_date": "string",
- "next_payment_date": "2019-08-24T14:15:22Z",
- "external_id": "string",
- "description": "string",
- "grace_period_days": 1
}
]Response samples
- 202
- 400
- 412
- 500
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:
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:
object or null | |
| path | string or null |
| op | string or null |
| from | string or null |
Responses
Request samples
- Payload
[- {
- "value": { },
- "path": "string",
- "op": "string",
- "from": "string"
}
]Response samples
- 400
- 500
Decline a 'pending' subscriptions payment.
Authorizations:
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
- 400
- 404
- 500
Request one-off payment on an existing agreement.
Authorizations:
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) | |
| auto_reserve | boolean |
| expiration_timeout_minutes | integer or null <int32> [ 1 .. 181440 ] |
Responses
Request samples
- Payload
{- "amount": 0.01,
- "external_id": "string",
- "description": "string",
- "links": [
- {
- "rel": "string",
- "href": "string"
}
], - "auto_reserve": true,
- "expiration_timeout_minutes": 1
}Response samples
- 202
- 400
- 412
- 500
Cancel a requested/reserved one-off payment.
Authorizations:
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
- 400
- 404
- 500
Update payment attachment.
Authorizations:
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
- Payload
{- "external_attachment_url": "string",
- "generate_pdf": true,
- "attachment_details": {
- "document_title": "string",
- "hide_payment_point_address": true,
- "consumer_name": "string",
- "consumer_address_lines": [
- "string"
], - "consumer_phone_number": "string",
- "merchant_contact_name": "string",
- "delivery_address_lines": [
- "string"
], - "delivery_date": "2019-08-24T14:15:22Z",
- "invoice_number": "string",
- "merchant_order_number": "string",
- "buyer_order_number": "string",
- "issue_date": "2019-08-24T14:15:22Z",
- "due_date": "2019-08-24T14:15:22Z",
- "order_date": "2019-08-24T14:15:22Z",
- "payment_reference": "string",
- "comment": "string",
- "price_reduction": 2147483647,
- "price_discount": 0,
- "bonus": 2147483647,
- "total_amount_ex_vat": 0,
- "total_vat_amount": 0,
- "total_amount": 2147483647,
- "articles": [
- {
- "article_number": "string",
- "article_description": "string",
- "quantity": 0,
- "unit": "string",
- "price_per_unit": 0,
- "vat_rate": 0,
- "total_vat_amount": 0,
- "total_price_including_vat": 0
}
]
}
}Response samples
- 400
- 500
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
- 200
- 500
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 ] |
| status_callback_url | string or null |
| external_id | string or null |
Responses
Request samples
- Payload
{- "amount": 0.01,
- "status_callback_url": "string",
- "external_id": "string"
}Response samples
- 202
- 500