Mobile SDK

Mobile SDK

Important: Visa, Mastercard, American Express, JCB, Diners/Discover, mada and Carte Bancaire have scheduled to decommission 3-D Secure V1 (3DS1) globally in October 2022. Customers are strongly advised to implement 3-D Secure V2 (3DS 2) if they have not already done so to ensure compliance with this requirement.

In regions that fall under the requirement to comply with the PSD2 directive or mandate the usage of 3D Secure in general, transactions that do not meet strong customer authentication (SCA) requirements or are generally accompanied with 3-D Secure V2 will experience declines after this date.

If you have integrated the mobile SDK and already process successful 3-D Secure V2 transactions, no action is required.

If you haven’t migrated to 3-D Secure V2 via mSDK yet or are not able to process 3-D Secure V2 transactions successfully, please upgrade your integration depending on the UI used to:

  • Ready-to-Use UI:
    • from version 3.4.0 with browser-based authentication (a setting in Planet Payment Gateway is required)
    • from version 4.0.0 with fully-supported features
  • Custom & Your Own UI: from version 4.0.0

We strongly recommend updating the mobile SDK to the latest version and review our 3-D Secure V2 documentation for more information.

Mobile SDK makes it easy to accept payments in your mobile app on iOS and Android platforms.

This guide shows you how to integrate in-app payments into your mobile shop or build a wallet-style app. The Mobile SDK takes care of the complexity: it routes the payment correctly to your account and handles the interaction with the payment gateway.

Integration scenarios

  1. You can integrate our ready-to-use checkout screens and customize them or
  2. You can build your own payment forms and checkout process and use our framework in the background to process the transaction.

NOTE: When you are just getting started with your project, we suggest trying our checkout screens to instantly have a full-fledged checkout experience. You can always come back and build your own payment forms later.

How it works in three main steps


Get the Checkout ID

Send the server-to-server request parameters to get the Checkout ID.


Send the payment info
using the Mobile SDK

Use the Checkout ID to send the payment info. You can use our Checkout screens or create your own payment form.


Get the payment status

Find out if the payment was successful.

MSDK Overview Diagram
Why is a Merchant Server required?

As you can see on the diagram, Merchant Server communicates with your app and our Server (Platform) on steps 1 and 3.
To integrate the SDK you need to expose your backend API first. We did not include this functionality to the SDK due to security reasons. Your authentication details are required for these steps, they should be stored on your server, not in the app.

Step 1. Get the Checkout ID in order to make the payment using the mSDK

  1. Your app sends сheckout configuration details including amount, currency, etc. to your server.
  2. Your server sends received data along with authentication details to the Platform to get the Checkout ID.
  3. Your server receives the Checkout ID and sends it back to the app.

Step 2. Send the payment info using the Mobile SDK

If you are using the SDK with our Checkout Screens:

  1. Your app initializes mSDK with the Checkout ID.
  2. SDK presents the Checkout screens, handles users' input and submits a transaction.
  3. SDK returns authorization status of payment from Platform and passes control back to the merchant app.

If you are using the SDK with your own UI:

  1. Your app initialize mSDK with the Checkout ID and users' payment details.
  2. SDK submit a transaction and returns authorization status of payment from Platform.

Step 3. Get the payment status

  1. Your app sends the Checkout ID to your server.
  2. Your server sends the Checkout ID along with authentication details to the Platform to request the payment status.
  3. Your server receives the payment status and sends it back to the app.

Key concepts

Checkout ID

The checkout ID is a string returned by your application from your server to represent a unique transaction identificator. This should not be reused; a new checkout ID should be generated for each new customer transaction. Your server is responsible for generating the checkout ID.

Your client is responsible to obtaining the checkout ID from your server and initializing the Mobile SDK.


The token is a string returned by the Mobile SDK to represent the stored payment details. Mobile SDK uses this string to obtain the detailed payment information to allow making one-click payment. Your server is responsible for getting and storing the token.

Your client is responsible for obtaining the tokens from your server and providing them to the Mobile SDK.

Synchronous & asynchronous payments

To pay with a credit card (that is not enrolled with 3D Secure program) the shopper needs to fill app's payment form with card details. Then he confirms purchase e.g. by clicking "Buy" and the transaction is submitted immediately. It is a synchronous workflow.

If the card is enrolled with 3D, after purchase confirmation the shopper should be redirected to the issuer page to perform the 3D authorization. The transaction will be processed only after successful authentication. It is a typical example of asynchronous workflow. Another example is online banking transfers, in this case customer may need to pass account authentication on issuer bank page (e.g. SOFORT Banking).

Privacy policy for the app when integrating the Android Mobile SDK

The recommendation for all merchants is to invoke the Fraud prevention, security, and compliance teams and adjust the privacy policy. You must be transparent in how you handle user data (for example, information collected from or about a user, including device information).

That means disclosing the access, collection, use, handling, and sharing of user data from your app, and limiting the use of the data to the policy compliant purposes disclosed. The following fields might be considered as sensitive. This information might be collected when making a 3D Secure 2.x authentication during the payment.

  • Advertising ID
  • Latitude
  • Longitude
  • DeviceId (not used in API level 29 or higher)
  • SubscriberId (not used in API level 29 or higher)
  • Group Identifier Level
  • Phone number
  • Serial number of the SIM (not used in API level 29 or higher)
  • WiFi Mac Address
  • Hardware address of the local Bluetooth adapter
  • Array of bonded(paired) Bluetooth Device MAC address
  • Array of bonded(paired) Bluetooth Device alias
  • String that uniquely identifies this build
  • Hardware serial number (not used in API level 29 or higher)
  • Installed Applications

Show all supported brands

BrandAsync / sync workflow