White-label App SDK
Getting Started
How it works

How the Headless SDK works?

There are 2 primary components from the SDK - HeadlessSetup & HeadlessActivity:

  • HeadlessSetup is an object for non-UI setups
    • it provides a init method for initializing with the CPoC/ MPoC SDK under the hood.
    • another similar method is the setup method, upon calling the SDK would load default config and the keys from MineSec's backend for future transaction process.
  • HeadlessActivity is a base android activity
    • For customer to inherit and provide the UI
    • Provide the contract for android's startActivityForResult
    • Internally, the activity connect and use the CPoC/ MPoC SDK under the hood.
    • Per each transaction, the encrypted data would be passed to MineSec's backend for processing.

Note that the card read data is processed via MineSec's backend service, for more details please refer to Enabler Service

headless-how-it-works.png


Environment Provision

For each customer, MineSec would first provision the enabler service for the corresponding handling and config.


Profile Creation

Once the environment is provisioned, the customer can create and manage the profile and acceptance.

From MineSec's backend we employ a concept of acceptance. The acceptance is an entity that holds information like the MID, TID, host message format, and other information that will be used when doing a payment message request to the upstream acquirer or payment gateway.

A profile is then holding the binding to one or multiple acceptance.

For example one profile (e.g. with profileId prof_01J1VF63D8E6QFCTAJQ7ACSC4W) can bind to

  • a gateway with hostMessageFormat: MPGS_AP, with MID: 123 and TID: 456
  • another gateway with hostMessageFormat: AMEX_GCAG, with MID: 987 and TID: 654

From the application side (with the headless SDK), after a card reading, the SDK would send the encrypted data to the MineSec's backend.

From MineSec's backend, based on the payment method read and the service configuration, it knows how to route and construct the corresponding payment message.


New App Install

For a freshly installed application, it would need to register the SDK first, underneath the SDK would do an initial attestation and also get back the sdkId from MineSec's backend.

After the SDK is registered, the app can call the initial setup for some initial param download and key loading. This initial setup is only required once per application.


Each App Launch

Each time the application is launched, it would need to perform the init in order for processing card reading.

So we recommend to put this init call binded in your application lifecycle.


Making Transaction Request

Making transaction request to the headless SDK is rather straight forward - Request with

  1. profileId - for the routing/ message format lookup & constructing the payment message in MineSec's backend
  2. request amount

There are some other optional request parameter, check details in the API section.

After the Headless SDK receives the request, it'll load the corresponding EMV config, perform the card read, encrypt the data and send it to MineSec's backend for host processing.