Skip to main content

Glossary of Terms

AgreementAn agreement in which merchant can provide subscription service to sell to Customers.
Agreement_idSubscription agreement ID on the MobilePay side. MobilePay generates the agreement_id when the customer swipes to accept the agreement. Agreement_id does not change regardless of what happens to the agreement. Agreement_id is the counterpart to the external_id on client. Before requesting subscription payment, an agreement should be created and accepted by customer. You cannot request a Subscription Payment without having agreement_id
APIApplication Programming interface.
CallbackOnce a payment status change happens, a callback will be done to the payment_status_callback_url. We send callbacks in sandbox and production environemtn.
ClientClient is used interchangeably for the application that calls the MobilePay Subscriptions API. Client is often used when only discussing the software.
CustomerThe customer is the user who wants to pay for goods and services with MobilePay Subscriptions.
CaptureCapture is the process by which payments are secured once the payment has been authorized, i.e. a reservation has been made. Merchant handles Capture for OneOff payments.
CorrelationIdIs an optional Guid heade value which can be used to link requests on your back-end system to MobilePay Subscriptions business transaction for a more convenient debugging
DescriptionAdditional information provided by the merchant to the user, that will be displayed on the Agreement screen. This is visible on the payment screen, so ensure that the information provided makes sense towards the Customer.
External_id (for agreement)Agreement ID on the merchant’s side. It is meant as a unique identifier, chosen by the merchant, which shouldn’t change. Two different agreements should not have the same external_id It should stay the same, so we can trace the full history of the agreement. It is included in the request body of the success and cancel callback.
External_id (for payment)Payment ID on the merchant's side. The external_id will be included in the request body of the refund callback. If the merchant is using instant transfer, then the reference number will be the external_id for Subscription Payments and OneOff payments. The Customer can see the payment external_id in the app.
IntegratorThe company that develops the client and calls the MobilePay Subscriptions API on behalf of the merchant. The Integrator also coordinates with the Merchant, whom they are managing the solution for, which parameters should be used and how they should be used. For example, for agreement, it is amount, description, frequency, external_id, retention_period_hours, disable_notification_management, notifications_on
JSONJSON is the short form for Javascript Object Notation and is a text-based information format that follows Javascript object syntax.
MerchantThe merchant is the company that wants to receive payments for goods and services from MobliePay users.
MobilePay - Admin PortalThe merchant orders the product on the MobilePay Portal in Production Portal. The merchant can upload a logo for their SubscriptionProvider on the MobilePay Portal. In sandbox, you will provided with a sandbox test user that is created by
ReservationA reservation is a pre-authorization which guarantees that the user has sufficient funds to pay for the given transaction. Uncaptured one-off payments expire after 14 days.
RESTIt stands for "Representational State Transfer".
retention_period_hoursMerchant can set for how long agreement can not be cancelled by the user, after the user accepted the agreement, for up to 24 hours.
page_size and pagination_statePagination_state is a key, that indicates, how many pages have already been collected, and which pages are the next. With every request, you will receive a pagination_state, that you should use in the subsequent request. Both page_size and pagination_state are 'optional' in GET /subscriptions/api/providers/{providerId}/agreements, so if you haven't included it, you will have all agreements returned. pageSize=<integer_value> - this defines how many agreement rows will be returned by single request (the limit is 2000). paginationState=token - pagination token returned by previous request, should be empty for the very first request and should be url-encoded when present.
Payment_idSubscription payment ID on the MobilePay side. MobilePay generates the agreement_id.
Payment - SubscriptionA payment request from the merchant, which is used when the Merchant needs to charge for periodic payment. The customer does not need to swipe to accept the payment.
Payment - OneOffCustomer action performed in order to initiate payment. The customer can create agreements with an initial OneOff payment, for example when the user wants to set up an agreement and you want to charge upfront. or request a OneOff payment on an existing agreement
Payment_status_callback_urlYou need to configure the payment_status_callback_url before you start to send payment requests.Once the payment or agreement changes state, a callback will be done to the callback address. You will not receive callbacks from MobilePay, unless you have set the payment_status_callback. It does not need to be whitelisted at MobilePay side.
ProviderIDOnce you have completed the OpenID Connect flow, you are ready to make the first call to our API. The first thing you need to do is call GET /api/merchants/me which will return you a list of subscription providers for that merchant, with their IDs and basic information. You need to deliver the ProviderID in the endpoints in the calls as {providerId}. If you are an Integrator, you should remember that the Merchant should not send you the ProviderID. You (the integrator) is able to retrieve the ID by making an api call. You set the payment_status_callback_url for each providerID
SubscriptionProviderThe SubscriptionsProvider is the actual service provider name. Each subscriptions provider contains its own address information, homepage url and etc. For example, if a single merchant has several brands, each brand would be a subscription provider. Merchant can create new and update current Subscriptions Provider on the MobilePay Portal in Production on
VAT-numberIn Denmark, this is the CVR-number. In Finland, this is the Y-tunnus. Both refer to the official business ID.