Best practices for Unified SDK integration

There are many ways you can implement the integration. Here is a set of good and proved practises from experience to ensure smooth, optimal and high quality integration.

Think through and plan your payment/checkout flow prior the integration. Have a look at checkout flow best practises.

Don't forget to add security. For a secure integration it is always a good idea to add as much security as you can by securing the callbacks and whitelisting IP-s.

Separate test payments from live ones. In order to maintain test payments and live payments it is recommended to make a clear distinction between them. This can be done by either making different Fortumo accounts(one for test and one for production) or setting up different callback URL-s so your backend can process sandbox and live callbacks accordingly.

Handling callbacks to provide the service. There are different callbacks for authorisation, payment and subscription. Take a look at the data we send with each callback. Bare in mind that there is no need to handle every single callback and value. Assess what information is useful to provide the service and handle the data accordingly. You want to be able to identify the unique user and transaction - listen to consumer_identity and transaction_id or operation_reference. Most of the occations you do not need information on authorisation so no need to receive authorisation callbacks. In case of payment callbacks you want to know whether the charge was successful or not so listen transaction_state parameter. For subscription callbacks you want to know subscription_status, service_starts_at and service_ends_at.

Set up reporting on your side. It is a good idea to set up a reporting system on your end to get a good overview of the traffic. This can be done by using our Reporting API and/or saving the callback data in your DB. Proper reporting helps you to monitor traffic and detect potential fraud.

Decide whether operator selection is implemented on your frontend. In case "channel_code" is not defined in the payload, Unified SDK provides a operator selection as a first step of the payment flow. On the other hand if "channel_code" is defined in the payload the operator is pre-selected. In this case you would have to implement the telco selection inside your app/webpage frontend. Some merchants decide to have the telco selection on their frontend for visual UI reasons or to get a better control of the checkout flow.

Use WebView if integrating in native application. Webview is a browser bundled inside of a mobile application. Using a webview allows mobile apps to be built using Web technologies (HTML, JavaScript, CSS, etc.) but still package it as a native app. This allows Unified SDK payment window to be presented as part your your native mobile application. Check out more information here.

Limit your subscriptions per user. If you are using Unified SDK recurring payment, make sure that you limit the number of active subscriptions per user. By default Unified SDK does not limit how many active subscriptions one customer can have. In most of the cases you do not want one user to be able to have multiple active subscriptions(e.g. subscribes to Weekly VIP and is able to subscribe to Monthly VIP at the same time). You can either request our Account Manager to limit active subscriptions per phone number or you can set up the limitation on your end(e.g. Hide other subscription offers once user has an active subscription).

Think how to redirect the user after completed payment flow After payment attempt is done user must be redirected accordingly. Unified SDK has multiple options to redirect the user - automatic redirection(user is redirected automatically to your defined URL) or user clicking "Back to Merchant" button(you can set different URL for failed and succeeded payments).

Make sure country and currency combination is correct in the payload. The currency must respect the country you have set in the payload. Otherwise Unified SDK falls back to default currency and presents it in the payment flow. This may cause confusion so always check that the currency you have selected for the country is correct.

Make sure you whitelist only our IP-s for your callback URL-s and that they are publicly accessable. Keep in mind that callback URL must be HTTPS and it is recommended that the domain name would not hold any sensitive information.

We can configure your integration on our end in multiple ways - changing the the support URL presented in payment window, setting subscription limits, allowing intermediate auth/payment/subscription statuses sent in the callbacks etc.


Thorough testing is a very important step for the integration. Here are few guidelines on what should be covered with the tests.

Ensure there are no errors on the payment flow. Check that payment flow that is opened from your site is completed as expected without errors(one-time payments, subscriptions, unsubscribing).

Check that prices are correct and match the setup. Check that all of your payment packages/items info on your site matches what is configured in Unified SDK frontend - price, currency, country

Make sure that service is porvided after successful charge and vice versa. Test your callback handling thoroughly to ensure that service is provided after successful charge and vice versa.

Make sure that subscription is provided to the user correctly. Test your callback handling thoroughly to ensure that the subscription that is set up in Unified SDK matches what is presented in your page.

Make sure that subscription renewals are handled correctly. On each renewal we will send a callback with a status update. Make sure that you will contonue giving the service(service_ends_at in subscription callback) on successfully charged renewal and vice versa. When testing use hours as a unit in subscription object together with cycles to test the renewals faster. Note that hours are only supported in Sandbox.

Make sure that unsubscribing is reflected on your site. When user unsubscribes from the recurring payment, it must be ensured that end user will get the service till the date that is paid for(service_ends_at in subscription callback). After that the service should be discontinued.

Ensure that one end-user can not activate a subscription for the same product if one is already active By default Unified SDK does not limit how many active subscriptions one customer can have. In most of the cases you do not want one user to be able to have multiple active subscriptions(e.g. subscribes to Weekly VIP and is able to subscribe to Monthly VIP at the same time).

Help us improve our Merchants Portal. Was this article helpful?