Token Management Platform SDK
Version 1.2.0
Table of Contents
Token Management Platform SDK Overview
1.1. What is Token Management Platform SDK?
-
2.1. Basic information
2.2. Basic configuration
2.3. Token Management Platform SDK Setup
2.4. Error handling
Token Management Platform Service
3.1. getOpaquePaymentCard
3.2. getTokens
3.3 activateToken
-
4.1 Version 1.0.0
4.2 Version 1.0.1
4.3 Version 1.0.2
4.4 Version 1.0.3
4.5 Version 1.0.4
4.6 Version 1.0.5
4.7 Version 1.0.6
4.8 Version 1.0.7
4.9 Version 1.1.0
4.10 Version 1.1.1
4.11 Version 1.1.2
Token Management Platform SDK Overview
1.1 What is Token Management Platform SDK?
Token Management Platform is a solution created in order to allow much easier connection to TSP( MDES, VTS). That can be used for card „pre-digitization” from all Token requestors with minimum development on the issuer side.
1.2 How does Token Management Platform SDK work?
Token Management Platform SDK requires Mobile DC as a dependency. It’s required for the Token Management Platform SDK to work correctly and handles user’s session and data (e.g. cards, addresses). Please read the Mobile DC SDK’s documentation to see more details about the installation and integration process
In order to incorporate this SDK into your app, see Basic configuration
1.3 Versioning and backward compatibility
SDK is based on semantic versioning.
For example: 1.0.0 ( MAJOR.MINOR.PATCH
)
- Major version compatibility-breaking changes in SDK public APIs.
It is mandatory to update application code, to use SDK, when this is incremented. - Minor version tracks new, not compatibility-breaking changes in
public API of SDK.
It is optional to update application code, when this digit is incremented. - Patch version tracks internal changes in SDK.
No updates in application code are necessary to update to version, which has this number incremented.
Changes not breaking compatibility:
- adding new optional interface to SDK setup
- adding new method to any domain
- adding new enum value to input or output
- adding new field in input or output model
2. Technical overview
2.1. Basic information
2.1.1 Facade
Facade is an entry point to communication with Token Management Platform SDK.
2.1.2 Multiple facade types
Token Management Platform SDK provides two public API's with same functionalities, the API's are:
- TokenManagementPlatformCoroutineService for projects which uses Kotlin programming language and Coroutines.
- TokenManagementPlatformStdService for projects which uses Kotlin or Java programming language and standard Callback.
The difference between the API's is a way of providing data to SDK methods and getting the
results
from them.
Input and output as an data models are the same.
This documentation
presents I/O types in a Kotlin way as it's easier to mark nullable fields (as
question mark).
2.1.3 Method structure
Every method description has same structure.
Execution type:
- Asynchronous - operation could take more time and method is called on thread different than main. The result of execution is provided in callback (described below).
- Synchronous - result of operation is provided as method return type.
Method type:
- Online - operation requires Internet connection.
- Offline - operation can be called without Internet connection.
Input
Input parameters with name, type and description.
Output
Result delivered by standard Callback with data or result is
suspended until the Coroutine
completes <Multiple facade types>
.
2.2 Basic configuration
2.2.1 Min SDK Version
The minSdkVersion must be at least 23 (Android 6.0).
2.2.2 Artifactory
SDK is available on Verestro maven repository and can be configured in project using Gradle build system.
Username and password are provided by Verestro.
repositories {
maven {
credentials {
username "<enter_username_here>"
password "<enter_password_here>"
}
url "https://artifactory.upaid.pl/artifactory/libs-release-local/"
}
}
2.2.3 SDKs version
Token Management Platform SDK is available in two versions: debug and release.
The
difference between version is debug allows to use application with debugger connected.
Debug
version is ended with appendix "-debug" in version name.
Samples below.
For release version, used on production environment in application uploaded to Google Play:
dependencies {
implementation 'com.verestro.sdk:tmp:${version}'
implementation 'pl.upaid.module:mobiledc:{version}'
}
For debugging purposes:
dependencies {
implementation 'com.verestro.sdk:tmp-dev:${version}-debug'
implementation 'pl.upaid.module:mobiledc:{version}-debug'
}
2.2.1 Source code obfuscation and optimization
As SDK is written in Kotlin language we recommend to add following code to gradle configuration:
android {
...
kotlinOptions {
freeCompilerArgs = [
'-Xno-param-assertions',
'-Xno-call-assertions',
'-Xno-receiver-assertions'
]
}
packagingOptions { exclude '/kotlin_metadata/**' }
...
}
Then use newest tools for code shrinking, optimization and obfuscation from Google by enabling R8 instead Proguard in gradle.properties file:
android.enableR8=true
2.3 Token Management Platform SDK Setup
Available configuration methods:
- TokenManagementPlatformCoroutineApi.init(configuration: Configuration)
- TokenManagementPlatformStdApi.init(configuration: Configuration)
2.3.1 Input
Configuration
Parameter | Type | Description |
---|---|---|
configuration | Configuration | Configuration model |
Configuration
Parameter | Type | Description |
---|---|---|
url | String | API hostname URL |
issuerName | String | API issuer name |
certificateHashes | List<String> | API hostname Pin SHA256 |
2.3.2 Sample
TokenManagementPlatformCoroutineApi
fun init(configuration: Configuration) {
TokenManagementPlatformCoroutineApi.init(configuration)
}
TokenManagementPlatformStdApi
fun init(configuration: Configuration) {
TokenManagementPlatformStdApi.init(configuration)
}
2.4 Error handling
SDK returns errors by TmpSdkException, which could be catched by application and shown on UI with detailed message.
Table below describes general exception types.
Exception type | Exception class | Description |
---|---|---|
Backend | TmpSdkException | Provides additional validation or error on backend side. Application should get reason code and show suitable message or made action. Message should be never shown to user. Could be logged for error reporting and for developers List of available exceptions in table below |
TmpSdkException
Exception | Parameters | Description |
---|---|---|
HttpApiException | code: Int, message: String? | HTTP API exception. |
TechnicalException | message: String? | Technical exception. |
UnknownErrorStatus | status: String? | An unknown error occurred. |
NoSessionException | User is unauthorized - session expired. | |
RequestCancelled | Request was canceled. | |
NoCertificatePinningException | No certificate pinning. | |
ValidationErrorException | Contains list of ValidationError. |
3 Token Management Platform Service
3.1 getOpaquePaymentCard
Asynchronous. Online.
Provide opaque payment card from backend.
3.1.1 Input
OpaquePaymentCardData
Parameter | Type | Description |
---|---|---|
opaquePaymentCardData | OpaquePaymentCardData | Opaque payment card data model |
OpaquePaymentCardData
Parameter | Type | Description |
---|---|---|
cardId | Long | Card identifier |
3.1.2 Output
3.1.2.1 Success
Success callback with OpaquePaymentCardResult model.
OpaquePaymentCardResult
Parameter | Type | Description |
---|---|---|
getOpaquePaymentCard | OpaquePaymentCardResult | Get opaque payment card result model |
OpaquePaymentCardResult
Parameter | Type | Description |
---|---|---|
opaquePaymentCard | OpaquePaymentCardModel | Opaque payment card model |
OpaquePaymentCardModel
Parameter | Type | Description |
---|---|---|
signedCard | String | Opaque Payment Card binary data |
3.1.2.2 Failure
Failure callback with throwable.
Sample
Standard Callback
fun getOpaquePaymentCard(opaquePaymentCardData: OpaquePaymentCardData) {
TokenManagementPlatformCoroutineApi
.tokenManagementPlatformCoroutineService
.getOpaquePaymentCard(
opaquePaymentCardData = opaquePaymentCardData,
callback = object : ApiCallback<OpaquePaymentCardResult> {
override fun onSuccess(response: OpaquePaymentCardResult) {
/*TODO: do something with get opaque payment card */
}
override fun onFailure(error: Throwable) {
/*TODO: something went wrong*/
}
}
)
}
Kotlin Coroutines
suspend fun getOpaquePaymentCard(opaquePaymentCardData: OpaquePaymentCardData): OpaquePaymentCardResult =
TokenManagementPlatformCoroutineApi
.tokenManagementPlatformCoroutineService
.getOpaquePaymentCard(opaquePaymentCardData = opaquePaymentCardData)
3.2 getTokens
Asynchronous. Online.
Provide token reference ids from backend.
3.2.1 Input
GetTokensData
Parameter | Type | Description |
---|---|---|
getTokensData | GetTokensData | Get tokens data model |
GetTokensData
Parameter | Type | Description |
---|---|---|
activeWalletId | String | Unique identifier for each instance of a [Android user, Google account] pair wallet. |
3.2.2 Output
3.2.2.1 Success
Success callback with GetTokensResult model.
GetTokensResult
Parameter | Type | Description |
---|---|---|
getTokensResult | GetTokensResult | Get tokens result model |
GetTokensResult
Parameter | Type | Description |
---|---|---|
tokens | List<TokenModel> | List of tokens |
TokenModel
Parameter | Type | Description |
---|---|---|
cardId | Long | Card identifier |
tokenReferenceId | String | Identifier number to refer to a DPAN |
3.2.2.2 Failure
Failure callback with throwable.
3.2.3 Sample
Standard Callback
fun getTokens(getTokensData: GetTokensData) {
TokenManagementPlatformCoroutineApi
.tokenManagementPlatformCoroutineService
.getTokens(
getTokensData = getTokensData,
callback = object : ApiCallback<GetTokensResult> {
override fun onSuccess(response: GetTokensResult) {
/*TODO: do something with get opaque payment card */
}
override fun onFailure(error: Throwable) {
/*TODO: something went wrong*/
}
}
)
}
Kotlin Coroutines
suspend fun getTokens(getTokensData: GetTokensData): GetTokensResult =
TokenManagementPlatformCoroutineApi
.tokenManagementPlatformCoroutineService
.getTokens(getTokensData = getTokensData)
3.3 activateToken
Asynchronous. Online.
Activates token by reference id. Passes verification status in result.
3.3.1 Input
ActivateTokenData
Parameter | Type | Description |
---|---|---|
activateTokenData | ActivateTokenData | Activate token data model |
ActivateTokenData
Parameter | Type | Description |
---|---|---|
tokenReferenceId | String | Identifier number to refer to a DPAN |
3.3.2 Output
3.3.2.1 Success
Success callback with ActivateTokenResult model.
ActivateTokenResult
Parameter | Type | Description |
---|---|---|
activateTokenResult | ActivateTokenResult | Activate token result model |
ActivateTokenResult
Parameter | Type | Description |
---|---|---|
verificationStatus | VerificationStatus | Status of activation process |
comment | String? | Detailed message, for ex. (Validation error message) Token is not INACTIVE |
VerificationStatus
Type | Description |
---|---|
APPROVED | Process finished with success. |
DECLINED | Process declined. |
FAILED | Process finished with error. |
UNKNOWN | Unhandled status. Update SDK. |
3.3.2.2 Failure
Failure callback with throwable.
3.3.3 Sample
Standard Callback
fun activateToken(activateTokenData: ActivateTokenData) {
TokenManagementPlatformCoroutineApi
.tokenManagementPlatformCoroutineService
.activateToken(
activateTokenData = activateTokenData,
callback = object : ApiCallback<ActivateTokenResult> {
override fun onSuccess(response: ActivateTokenResult) {
/*TODO: handle verification status */
}
override fun onFailure(error: Throwable) {
/*TODO: something went wrong*/
}
}
)
}
Kotlin Coroutines
suspend fun activateTokenData(activateTokenData: ActivateTokenData): ActivateTokenResult =
TokenManagementPlatformCoroutineApi
.tokenManagementPlatformCoroutineService
.activateToken(activateTokenData = activateTokenData)
4. Document changelog
4.1. Version 1.0.0
- Created Token Management Platform SDK
4.2 Version 1.0.1
- Handle validator error exception
4.3 Version 1.0.2
- Refactor Configuration model
- Add certificate pinning
4.4 Version 1.0.3
- Add hostname verification
4.5 Version 1.0.4
- Refactor getTokenReferenceIds method to getTokens
4.6 Version 1.0.5
- Updates documentation
4.7 Version 1.0.6
- Added support for DC access token
4.8 Version 1.0.7
- Disables pinning and obfuscation for debug
4.9 Version 1.1.0
- Removes unnecessary fields from TokenModel
4.10 Version 1.1.1
- Updates documentation
4.11 Version 1.1.2
- Updated koin to version 3.5.3
- Updated java to 17
- Updated compile and target android version
4.12 Version 1.2.0
- Adds activate token method