Mobile and browser SDKs
Introduction on the native payment landscape
The Worldline platform supports payments from all mobile platforms, including “native” in-app payments. Merchants that have apps developed for iOS and Android have the added advantage of a very easy “native” implementation using our platform specific native SDKs.
These SDKs help you to implement the Client API. This is a special secure channel between your native app and our server, used to obtain security credentials to keep your customer’s data secure in transit.
In the full landscape of working with native payments with the Worldline platform, the following system components play a role:
- The Worldline servers, exposing the Client API and the Server API, both as REST endpoints
- The Client API, exposing all REST API endpoints that need to be accessed by the mobile device directly
- The Server API, exposing REST API endpoints that are specially adapted to accept data from native clients that flow through your e-commerce server
- Your e-commerce server that communicates with the Server API and your e-commerce app
- Your e-commerce app that communicates with your e-commerce server and the Client API
- The Client SDK (Native SDK) that implements logic to connect your e-commerce app with the Client API on the Worldline servers, and display payment screens in an optimal way
- The Server SDK that implements logic to connect your e-commerce server with the Server API on the Worldline servers
Note on in-app payment regulations
Please note that all major mobile platforms have specific rules for what type of products are allowed to be purchased outside of the platform’s default store or payment mechanism. Worldline is an “external” payment service provider from this perspective. Usually, digital in-app products are not allowed while physical goods and services are allowed. You have to make sure that your e-commerce app complies with the platform specific rules and regulations with regards to payments, as you risk having the app rejected during the approval process or taken down from the store.
Our native SDK for iOS supports iOS 6.1 and up out-of-the box. Of course, the SDK components can also be used on iOS 7 and higher.
Our native SDK for Android supports API level 10 and up. This means you can use it from Android 2.3.3 (GINGERBREAD_MR1) onwards. 2.3.3 is a small feature release that adds several improvements and APIs to the Android 2.3 platform.
Main SDK components
The native SDKs provide you with these core support components, to help you implement native payments in your apps:
- Components that provide cryptography support
- Components that provide communication support
- Components that wrap Client API responses (JSON to native platform objects)
- Component that help you manage and get assets like payment product images
- Components that help you implement localization on the payment pages
- Components for field validation and value presentation
- IIN lookup support (to find the right card brand for a card number)
- An example implementation of payment screens, using all of the above
The process supported by the native SDK
The native SDKs use the Client API to secure card and other sensitive payment data. The process is described below.
- Your e-commerce server starts a new “session” on behalf of the mobile app. This is processed through the Server API, and the session ID has to be sent to your e-commerce app.
- Using this session ID, the e-commerce app can start communicating directly on the Client API, for example to request payment products configured for you, assets like payment product logos or to do amount conversions.
- When your customer and your e-commerce app are ready for the actual payment process, the native SDK will request a public a-symmetric key from the Client API. Only we know the corresponding private key.
- Card and other PCI-DSS or sensitive data in the payment process is encrypted by the native SDK. For this encryption process, a unique one-time password is generated. This password is encrypted with the public key from the Client API. The entire encrypted package (a PreparedPaymentRequest) is sent to your e-commerce server.
- Your e-commerce server sends the encrypted payment data and (if needed) additional data to the Server API using the Server SDK. We will use the private key to unlock the encrypted package and process the payment. Feedback is provided over the Server API channel.
To get started with implementing native payment in your e-commerce app, load the example app in your development environment (IDE) and have a look around. You’ll see that the example app uses all available SDK components in a “best practice” implementation. The example app uses IIN lookups, localization, JSON mapping and the Client API with crypto support. We suggest that you use the example app code as the starting point for your own implementation and change its look & feel in any way you like. We do recommend that you try to minimize the changes to the examples app's logic and cryptography code to make sure it will work for all possible payment products.