Version 1.0.4
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
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
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.
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
SDK is based on semantic versioning.For example: 1.0.0 ( MAJOR.MINOR.PATCH )
Changes not breaking compatibility:
Facade is an entry point to communication with Token Management Platform SDK.
Token Management Platform SDK provides two public API's with same functionalities, the API's are:
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).
Every method description has same structure.
Execution type:
Method type:
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>
.
The minSdkVersion must be at least 23 (Android 6.0).
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/"
}
}
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'
}
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
Available configuration methods:
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 |
TokenManagementPlatformCoroutineApi
fun init(configuration: Configuration) {
TokenManagementPlatformCoroutineApi.init(configuration)
}
TokenManagementPlatformStdApi
fun init(configuration: Configuration) {
TokenManagementPlatformStdApi.init(configuration)
}
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. |
Asynchronous. Online.
Provide opaque payment card from backend.
OpaquePaymentCardData
Parameter | Type | Description |
---|---|---|
opaquePaymentCardData | OpaquePaymentCardData | Opaque payment card data model |
OpaquePaymentCardData
Parameter | Type | Description |
---|---|---|
cardId | Long | Card identifier |
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 |
Failure callback with throwable.
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)
Asynchronous. Online.
Provide token reference ids from backend.
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. |
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 |
panReferenceId | String? | Unique set of numbers and letters that is to a transaction |
tokenStatus | TokenStatus | Token status |
authorizationPath | AuthorizationPath | Authorization path |
processStatus | ProcessStatus | Process status |
TokenStatus
Type | Description |
---|---|
INACTIVE | Token status inactive |
ACTIVE | Token status active |
SUSPENDED | Token status suspended |
DEACTIVATED | Token status deactivated |
AuthorizationPath
Type | Description |
---|---|
GREEN | Authorization green path |
YELLOW | Authorization yellow path |
RED | Authorization red path |
ORANGE | Authorization orange path |
ProcessStatus
Type | Description |
---|---|
FINISHED | Process status finished |
IN_PROGRESS | Process status in progress |
FAILED | Process status failed |
Failure callback with throwable.
TmpSdkException
Reason | Description |
---|---|
UnknownTokenStatus | Unknown token status |
UnknownAuthorizationPath | Unknown authorization path |
UnknownProcessStatus | Unknown process status |
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)