Understanding what happens in the natural course of a subscription helps provide the smoothest experience for both you and your users. Seen as you're using our platform, we are happy to provide you with tips & tricks to handle the payments.

You can issue a Subscription Payment maximum 126 days before the due date, and at at least 1days before the due date.
- Due Date
- Due Date Payments cannot be created with the same Due Date.
- Multiple Recurring payments can be created within period [126 before Due Date >= Payment Request Date >= 1 before Due Date]
- Next Payment Date If there are multiple pending payments, the Next Payment Date is the one closest to Today
- Frequency
- Valid values are 0, 1, 2, 4, 12, 26, 52, 365. For example: If you have a customer where the frequency of an agreement is set to 4, that means 365 / 4 = 91.25 (approximately quarterly).
- Payment Limit
- If your services cost more than 15.000 DKK please refer to the guidelines regarding payment limits on this page.
How are the payments validated ?
There are validation rules; however the payments are not validated until they have been created in our system. Therefore, even though you get a response with pending payments, they may not be valid. When you make a payment request, we will validate the request itself, but not the individual payments. So it only validates if you have the required parameters with the correct types. So the response you get for the payment request, does not say if the payment is pending, but if the payment creation is pending. Then the payments are processed in our system, and they will either be requested (valid) or declined (invalid). Moreover, you will receive a callback to inform whether payments are requested or declined. This will be sent to your payment status callback
How should I send the payments?
- You can send your payments to us max 126 days prior to the due date and min 1 day prior to the due date.
- The MobilePay user will be able to see payments in the app 1 day before due date.
- If a payment changes status e.g. declined by user, a callback on the specific payment will be made.
- On due date we process the payments starting from 02:00. If some payments are declined we will then try again approx. every 2. hour up until 23:59.
- If payment errors occur the user will get a notification approx. 08:30 that we can not process payment and that he/she can complete the payment manually (by correcting error and swiping).
- On 23:59 we will decline the transaction and revert back with a callback.
There is no admin panel to check request, but you can use the following API calls:
GET /api/providers/{providerId}/agreements
- Get a list of agreementsGET /api/providers/{providerId}/agreements/{agreementId} -
Get agreements detailsGET /api/providers/{providerId}/agreements/{agreementId}/paymentrequests
- Get a list of payments in a given agreementGET /api/providers/{providerId}/agreements/{agreementId}/paymentrequests/{paymentId}
- Get single payment detailsGET /api/providers/{providerId}/agreements/{agreementId}/oneoffpayments
- Get all OneOff payments of a single agreementGET /api/providers/{providerId}/agreements/{agreementId}/oneoffpayments/{paymentId}
- Get single OneOff payment detailsGET /api/providers/{providerId}/agreements/{agreementId}/payments/{paymentId}/refunds
- Get a list of refunds issued for particular payment
It is easy to do reconciliation with the MobilePay Subscriptions API. It is possible to do reconciliation in three ways.
- Callbacks: You get the status on the payment through the API. When the payment has status
executed
then the customer has paid. Callbacks for subscription payments are found here The individual transactions will contain the sameexternal_id
, that you have assigned, and thatexternal_id
will be returned through the API.external_id
is the identifier of a specific payment in merchant's system, and can be used for this purpose. For example, if the merchant wants to use their FIK-Creditor-ID for transactions, then the merchant simply choose the reference number for theexternal_id
, which can be the merchant FIK-Creditor-ID. There are no special requirements for the merchant FIK-creditor-ID to be able to use it for MobilePay Subscriptions Read more about subscription payments external_id here and one-off payment external_id here - TRX api: Use the Transaction Reporting API
- MobilePay Portal: The merchant logs in to our MobilePay portal on https://admin.mobilepay.dk where the merchant can see transactions and export these in a CSV file or a XLXS file
With the Transaction Reporting API, you can quickly find all information associated with each of your payment. When using the Transaction Reporting API, you will be introduced to the terms:
paymentPointId
ExternalTransactionID
payment_transaction_id
Merchant Payer Reference
In the table below, you can map the field in the Subscriptions API to the field in the Transaction Reporting Api. Furthermore, you can see who provides the different fields, when initiating payments.
Please use the table below for correlating transactions between MobilePay Subscriptions and external merchant / integrator system.
Field in Transaction Reporting Api | Field in Subscriptions Api | Who sets it? | Type | Viewable in the MobilePay app | Description | Our recommendation |
ExternalTransactionID |
|
Merchant | string | YES |
|
Use the order ID, so it is easy for the customer to see on the receipt itself, what they are paying for. The orderID should be unique for each customer. |
|
|
MobilePay | GUID |
NO |
|
|
|
|
Merchant | string |
YES + the external_id is included in the subject field, when/if the customer sends an email from the MobilePay app |
|
|
|
|
Merchant | string |
The identifier assigned by merchant to the specific payment. This is what the merchant should use to book against in their own systems when reconciling. |
||
|
MobilePay | YES |
|
The process on failed payments the Due Date is as follows:
• 06:00 First hiccup is run at 06:00 on the due date. Once done, a notification about completion is returned. Merchant is informed about successful payments and user about failed payment
• 13:30 Second hiccup is run at 13:30 on the due date. Once done, a notification about completion is returned. Merchant is informed about successful payments and user about failed payment.
• 18:00 20:00 22:30 - hiccups keep running throughout the day. Once done, a notification about completion is returned. Merchant is informed about successful payments and user about failed payment,

Your MobilePay Subscriptions integration might have to deal with errors at some point when making API requests to MobilePay. MobilePay uses HTTP response status codes to indicate the success or failure of your API requests. These errors fall into a few major categories:
- Content errors occur because the content in the API request was invalid in some way. They return an HTTP response with a 4xx error code. For example, the API servers might return a
401
if an invalid API key was provided, or if access token is expired, or a400
if a required parameter was missing. Integrations should correct the original request, and try again. Depending on the type of user error, it may be possible to handle the problem programmatically. - Network errors errors occur because of intermittent communication problems between client and server. When intermittent problems occur, clients and MobilePay Merchants can be left in a state where they do not know whether the server received the request. For MobilePay Subscriptions, we do not track each request, but we track the state of a payment or agreement. For example: if a OneOff is captured, then the client will receive a callback and a 4xx response with error body.
- Server errors occur because of a problem on MobilePay’s servers. Server errors return an HTTP response with a
5xx
error code. MobilePay works to make these errors as rare as possible, but integrations should be able to handle them when they do arise. The result of a500
request should be treated as indeterminate. The most likely time to observe one is during a production incident, and generally during such an incident’s remediation. When a production incident happens, you will receive an e-mail from MobilePay Operations team, assuming you have subscribed to the operational maillist. When this happens, MobilePay engineers will examine failed requests and try to appropriately reconcile the results of any mutations that resulted in500
Your API integration should always check the HTTP response code to ensure correct handling of success and error conditions. ONLY an HTTP status of 200 means the request was successful. For non 200 responses, the predictable response body will give you details on why the request failed. We suggest logging any failure response body as best practice; the MobilePay Developer support team will need the full response body to assist with troubleshooting.
It is important to know which transfer type are possible to use as a merchant. There are two:
- Instant Transfer
- Daily Transfer
|
Instant Transfer |
Daily Transfer |
WHEN TRANSFER IS DONE |
|
|
REFERENCE NUMBER |
|
|
HOW TO SET IT |
|
|
BANK STATEMENT |
|
|
Refund |
|
Payment Flow
Now that you've have integrated the api, feel free to read our Subscriptions Release Notes, to ensure you are updated on the newest features.
