Production payments 

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.

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, 365For 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.
Subscriptions Payment Flow 

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. 
Checking requests

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 agreements
  • GET /api/providers/{providerId}/agreements/{agreementId} - Get agreements details
  • GET /api/providers/{providerId}/agreements/{agreementId}/paymentrequests - Get a list of payments in a given agreement
  • GET /api/providers/{providerId}/agreements/{agreementId}/paymentrequests/{paymentId} - Get single payment details  
  • GET /api/providers/{providerId}/agreements/{agreementId}/oneoffpayments - Get all OneOff payments of a single agreement
  • GET /api/providers/{providerId}/agreements/{agreementId}/oneoffpayments/{paymentId} - Get single OneOff payment details
  • GET /api/providers/{providerId}/agreements/{agreementId}/payments/{paymentId}/refunds - Get a list of refunds issued for particular payment
3 ways to do Reconciliation

It is easy to do reconciliation with the MobilePay Subscriptions API. It is possible to do reconciliation in three ways.

  1. 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 same external_id, that you have assigned, and that external_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 the external_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
  2. TRX api: Use the Transaction Reporting API
  3. 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
Transaction reporting api

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

  • external_id for recurring payments and one_off_payment.
  • external_id for one-off payments will be used in bank statement in fields:
Merchant string YES
  • It is provided by merchant / payment integrator when initiating payments and is used for correlating transactions between MobilePay and external merchant or integrator system. 

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. 

paymentPointId 

SubscriptionsProviderID

MobilePay GUID NO
  • is a GUID assigned to payment point. 
  • You can call GET /api/merchants/me, which will return a list of all subscription providers, associated with that merchant. Read more here 
 

Merchant Payer Reference 

external_id for agreements

Merchant string YES + the external_id is included in the subject field, when/if the customer sends an email from the MobilePay app   
  • Use Customer ID, so it is easy for the Support Unit at Merchant side to know, who the customer is. 

merchant_reference

external_id for payments 

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.

 

payment_transaction_id

  MobilePay   YES
  • includes payment_transaction_id for all payments: recurring; one-off; refund.
  • The Transaction ID is visible on the receipt screen.
 

 Learn More

 
Failed Payments flow

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,

 

 

Error handling  

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 a 400 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 a 500 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 in 500

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.

Subscriptions API - Transfers

It is important to know which transfer type are possible to use as a merchant. There are two:

  1. Instant Transfer
  2. Daily Transfer

 

Instant Transfer

Daily Transfer

WHEN TRANSFER IS DONE

  • MobilePay transfers instantly after the payment is completed.
  • Transfer might reach Merchant account later then MobilePay executes transfers. It depends on Merchant bank transfer times.
  • MobilePay transfers once per day, at night. Payments payed on day X will be transferred on day X+1.
  • Transfer might reach Merchant account later than MobilePay executes transfers. It depends on Merchant bank transfer times.

REFERENCE NUMBER

  • Field external_id for recurring payments and one_off_payment. external_id for one-off payments is used as Reference number.
  • Reference number is generated by MobilePay.
  • External Rules here.

HOW TO SET IT

  • Merchant can set Instant transfers for each Subscription provider in MobilePay portal.
  • Merchant can set Daily transfers for each Subscription provider in MobilePay portal.

BANK STATEMENT

  • external_id for recurring payments and one_off_payment.external_id for one-off payments will be used in bank statement in fields:
    • DK Text field.
    • FI Text field and Reference no. field.
  • MobilePay generated reference number will be used in bank statement in fields:
    • DK Text field.
    • FI Text field and Reference no. field.

Refund

  • Currently it is not possible to refund when the merchant has chosen 'instant transfer' method.  
 

 

 

What's next?

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. 

Previous step