Transfers SDK

Version. 1.0.12

Table of Contents

1. Transfers SDK Overview

   1.1. What is Transfers SDK?

   1.2. How Transfers SDK works?

   1.3. Versioning and backward compatibility

2. Technical overview

   2.1. Basic information

   2.2. Basic configuration

   2.3. Transfers SDK Setup

   2.4. Error handling

3. Transfers service

   3.1. calculateCommission

   3.2. getCurrencyRate

   3.3. determineCurrency

   3.4. finalizeAuthentication

   3.5. initializeAuthentication

   3.6. mcSend

   3.7. sendMoney

4. DOCUMENT CHANGELOG

   4.1 Version 1.0.0

   4.2 Version 1.0.7

   4.3 Version 1.0.8

   4.4 Version 1.0.9

   4.5 Version 1.0.11

   4.6 Version 1.0.12

1. Transfers SDK Overview

1.1. What is Transfers SDK?

The Transfers SDK is a module dedicated for making transactions from one user payment card to another user payment card with associated phone number as an identifier.

1.2. How Transfers SDK works?

Transfers SDK requires Mobile DC SDK as a dependency. It’s required for the Transfers SDK to work correctly and handles user’s session and data (e.g. cards).

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 inceremented.
• Patch version tracks internal changes in SDK. No updates in application code are necessary to update to version, which has this number inceremented.

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

This section describes basic information about Mobile DC SDK, Transfers SDK setup and available methods.

2.1. Basic information

2.1.1 Facade

Facade is entry point to communication with Transfers SDK.

2.1.2 Multiple facade types

P2P Transfers SDK provides two public API's with same functionalities, the API's are:

• TransfersCoroutineService for projects which uses Kotlin programming language and Coroutines.
• TransfersStdService 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 <>.

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 is 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

Transfers 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 "pl.upaid.module:mobiledc:{version}"
    implementation 'com.verestro.module:transfers:{version}'
}

For debugging purposes:

dependencies{
    implementation "pl.upaid.module:mobiledc:{version}-debug"
    implementation 'com.verestro.module:transfers:{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 Transfers SDK Setup

Available configuration methods:

• TransfersCoroutineApi.init(configuration: Configuration)
• TransfersStdApi.init(configuration: Configuration)

2.3.1 Input

Configuration

Configuration

2.3.2 Sample

TransfersStdApi

fun init(configuration: Configuration) {
    TransfersStdApi.init(configuration)
}

TransfersCoroutineApi

fun init(configuration: Configuration) {
    TransfersCoroutineApi.init(configuration)
}

2.4 Error handling

SDK returns errors by TransfersSdkException, which could be catched by application and shown on UI with detailed message. Table below describes general exception types.

TransfersSdkException

ValidationError

Specific types of exceptions are described for each method.

3 Transfers service

3.1 calculateCommission

Asynchronous. Online.

This method is used to receive information about the commission that will be charged for the transaction.

3.1.1 Input

CalculateCommissionData

CalculateCommissionType

CalculateCommissionSender

CalculateCommissionReceiver

CalculateCommissionReceiverType

3.1.2 Output

3.1.2.1 Success

Success callback with CalculateCommissionResult model.

CalculateCommissionResult

CalculateCommissionTransactionCommission

CalculateCommissionConfiguration

CalculateCommissionReconciliationType (deprecated)

CalculateCommissionReconciliationTypeValue

CalculateCommissionTransactionTypeData

CalculateCommissionRevaluationResult

CalculateCommissionDeterminedCurrencyRate

3.1.2.2 Failure

Failure callback with throwable.

Possible types of exceptions:

3.1.3 Sample

Standard Callback

fun calculateCommission(calculateCommissionData: CalculateCommissionData) {
    TransfersStdApi
        .transfersStdService
        .calculateCommission(
            calculateCommissionData = calculateCommissionData,
            callback = object : ApiCallback<CalculateCommissionResult> {
                override fun onSuccess(response: CalculateCommissionResult) {
                    // handle success
                }
                override fun onFailure(error: Throwable) {
                    // handle error
                }
            }
        )
}

Kotlin Coroutines

suspend fun calculateCommission(calculateCommissionData: CalculateCommissionData): CalculateCommissionResult =
    TransfersCoroutineApi
        .transfersCoroutineService
        .calculateCommission(calculateCommissionData = calculateCommissionData)

3.2 getCurrencyRate

Asynchronous. Online.

Method is used to determine currency rate for revaluation from funding to payment (lowerRate) and payment to funding (higherRate).
Notice that lowerRate is used to transaction processing.

Select the direction of revaluation by providing type value.

SENDER - defines amount of funding in given currency. This amount is collected from sender card in selected currency.
RECEIVER - defines amount of payment in given currency. This amount is transferred to receiver card in selected currency.
In case where there’s need of revaluation from one currency to another, system uses lowerRate for SENDER type and higherRate for RECEIVER type.

3.2.1 Input

CurrencyRateData

3.2.2 Output

3.2.2.1 Success

Success callback with CurrencyRateResult model.

CurrencyRateResult

3.2.2.2 Failure

Failure callback with throwable.

3.2.3 Sample

Standard Callback

fun currencyRate(currencyRateData: CurrencyRateData) {
    TransfersStdApi
        .transfersStdService
        .getCurrencyRate(
            currencyRateData = currencyRateData,
            callback = object : ApiCallback<CurrencyRateResult> {
                override fun onSuccess(response: CurrencyRateResult) {
                    // handle success
                }
                override fun onFailure(error: Throwable) {
                    // handle error
                }
            }
        )
}

Kotlin Coroutines

suspend fun currencyRate(currencyRateData: CurrencyRateData): CurrencyRateResult =
    TransfersCoroutineApi
        .transfersCoroutineService
        .getCurrencyRate(currencyRateData = currencyRateData)

3.3 determineCurrency

Asynchronous. Online.

Determines currencies applied for given sender and receiver cards.

3.3.1 Input

DetermineCurrencyData

DetermineCurrencyReceiver

DetermineCurrencyReceiverType

3.3.2 Output

3.3.2.1 Success

Success callback with DetermineCurrencyResult model

DetermineCurrencyResult

3.3.2.2 Failure

Failure callback with throwable

Possible types of exceptions:

3.3.3 Sample

Standard Callback

fun determineCurrency(determineCurrencyData: DetermineCurrencyData) {
    TransfersStdApi
        .transfersStdService
        .determineCurrency(
            determineCurrencyData = determineCurrencyData,
            callback = object : ApiCallback<DetermineCurrencyResult> {
                override fun onSuccess(response: DetermineCurrencyResult) {
                    // handle success
                }
                override fun onFailure(error: Throwable) {
                    // handle error
                }
            }
        )
}

Kotlin Coroutines

suspend fun determineCurrency(determineCurrencyData: DetermineCurrencyData): DetermineCurrencyResult =
    TransfersCoroutineApi
        .transfersCoroutineService
        .determineCurrency(determineCurrencyData = determineCurrencyData)

3.4 finalizeAuthentication

Asynchronous. Online.

This method is used to finalize authentication using 3-D Secure 2.0 standard.

3.4.1 Input

FinalizeAuthenticationData

3.4.2 Output

3.4.2.1 Success

Success callback with FinalizeAuthenticationResult model

FinalizeAuthenticationResult

FinalizeAuthenticationModel

AuthenticationStatusType (deprecated)

AuthenticationStatusTypeValue

3.4.2.2 Failure

Failure callback with throwable

3.4.3 Sample

Standard Callback

fun finalizeAuthentication(finalizeAuthenticationData: FinalizeAuthenticationData) {
    TransfersStdApi
        .transfersStdService
        .finalizeAuthentication(
            finalizeAuthenticationData = finalizeAuthenticationData,
            callback = object : ApiCallback<FinalizeAuthenticationResult> {
                override fun onSuccess(response: FinalizeAuthenticationResult) {
                    // handle success
                }
                override fun onFailure(error: Throwable) {
                    // handle error
                }
            }
        )
}

Kotlin Coroutines

suspend fun finalizeAuthentication(finalizeAuthenticationData: FinalizeAuthenticationData): FinalizeAuthenticationResult =
    TransfersCoroutineApi
        .transfersCoroutineService
        .finalizeAuthentication(finalizeAuthenticationData = finalizeAuthenticationData)

3.5 initializeAuthentication

Asynchronous. Online.

This method is used to initialize authentication using 3-D Secure 2.0 standard.

3.5.1 Input

InitializeAuthenticationData

InitializeAuthenticationAdditionalInfoModel

InitializeAuthenticationConfigModel

InitializeAuthenticationRequestChallengeIndicator

InitializeAuthenticationType

InitializeAuthenticationCallback

3.5.2 Output

3.5.2.1 Success

Success InitializeAuthenticationResult or onChallengeRequired callback with theirs result models.

InitializeAuthenticationResult

InitializeAuthenticationFrictionlessResult

InitializeAuthenticationFrictionlessModel

InitializeAuthenticationChallengeResult

InitializeAuthenticationChallengeModel

InitializeAuthenticationThreeDsMode (deprecated)

InitializeAuthenticationThreeDsModeValue

AuthenticationStatusType (deprecated)

AuthenticationStatusTypeValue

3.5.2.2 Failure

Failure callback with throwable

Possible types of exceptions:

3.5.3 Sample

Standard Callback

fun initializeAuthentication(
    initializeAuthenticationData: InitializeAuthenticationData
) {
    TransfersStdApi
        .transfersStdService
        .initializeAuthentication(
            initializeAuthenticationData = initializeAuthenticationData,
            callback = object : InitializeAuthenticationCallback {
                override fun onThreeDsFinished(initializeAuthenticationFrictionlessResult: InitializeAuthenticationFrictionlessResult) {
                    // handle successful frictionless case
                }
                override fun onChallengeRequired(initializeAuthenticationChallengeResult: InitializeAuthenticationChallengeResult) {
                    // handle successful challenge case
                }

                override fun onFailure(error: Throwable) {
                    // handle error
                }
            }
        )
}

Kotlin Coroutines

suspend fun initializeAuthentication(
    initializeAuthenticationData: InitializeAuthenticationData
) {
    val result: InitializeAuthenticationResult = TransfersCoroutineApi
        .transfersCoroutineService
        .initializeAuthentication(initializeAuthenticationData = initializeAuthenticationData)
    when (result) {
        is InitializeAuthenticationFrictionlessResult -> {
            // handle successful frictionless case
        }
        is InitializeAuthenticationChallengeResult -> {
            // handle successful challenge case
        }
    }
}

3.6 mcSend

Asynchronous. Online.

Method allows sending money in MasterCard Send 2.0.

3.6.1 Input

McSendData

McSendSender

McSendPaymentAccountType

McSendRecipient

McSendRecipientAddress

3.6.2 Output

3.6.2.1 Success

Success callback with McSendResult model.

McSendResult

McSendTransactionStatus (deprecated)

McSendTransactionStatusValue

3.6.2.2 Failure

Failure callback with throwable

3.6.3 Sample

Standard Callback

fun mcSend(mcSendData: McSendData) {
    TransfersStdApi
        .transfersStdService
        .mcSend(
            mcSendData = mcSendData,
            callback = object : ApiCallback<McSendResult> {
                override fun onSuccess(response: McSendResult) {
                    // handle success
                }
                override fun onFailure(error: Throwable) {
                    // handle error
                }
            }
        )
}

Kotlin Coroutines

suspend fun mcSend(mcSendData: McSendData): McSendResult =
    TransfersCoroutineApi
        .transfersCoroutineService
        .mcSend(mcSendData = mcSendData)

3.7 sendMoney

Asynchronous. Online.

This method is used to full MoneySend transaction (funding and payment). It is also adding friend as sender after successful transaction.

3.7.1 Input

SendMoneyData

SendMoneyTransaction

SendMoneyTransactionType

SendMoneySenderDetails

SendMoneySenderAddress

SendMoneySenderCard

SendMoneyReceiver

SendMoneyReceiverType

SendMoneyExternalAuthentication

3.7.2 Output

3.7.2.1 Success

Success callback with SendMoneyResult model.

SendMoneyResult

3.6.2.2 Failure

Failure callback with throwable.

Possible types of exceptions:

3.7.3 Sample

Standard Callback

fun sendMoney(sendMoneyData: SendMoneyData) {
    TransfersStdApi
        .transfersStdService
        .sendMoney(
            sendMoneyData = sendMoneyData,
            callback = object : ApiCallback<SendMoneyResult> {
                override fun onSuccess(response: SendMoneyResult) {
                    // handle success
                }
                override fun onFailure(error: Throwable) {
                    // handle error
                }
            }
        )
}

Kotlin Coroutines

suspend fun sendMoney(sendMoneyData: SendMoneyData): SendMoneyResult =
    TransfersCoroutineApi
        .transfersCoroutineService
        .sendMoney(sendMoneyData = sendMoneyData)

4. DOCUMENT CHANGELOG

4.1. Version 1.0.0

• Created.

4.2. Version 1.0.7

• Disables obfuscation and pinning for debug.

4.3. Version 1.0.8

• Adds isInternalTransaction flag to CalculateCommissionResult model.

4.4 Version 1.0.9

• Updated koin to version 3.5.3
• Updated java to 17
• Updated compile and target android version

4.5 Version 1.0.11

• Updates internal mechanism responsible for data encryption

4.6 Version 1.0.12

• Added UNKNOWN type to CalculateCommissionReconciliationType and McSendTransactionStatus enum model.
• Marked all enum fields in SDK result models with @Deprecated.
• Added corresponding value classes fields for all deprecated fields.