Receivers SDK

Version. 2.0.5

Table of Contents

1. Receivers SDK Overview

   1.1. What is Receivers SDK?

   1.2. How Receivers SDK works?

   1.3. Versioning and backward compatibility

2. Technical overview

   2.1. Basic information

   2.2. Basic configuration

   2.3. Receivers SDK Setup

   2.4. Error handling

3. Receivers service

   3.1. addExternalReceiver

   3.2. addWalletReceiver

   3.3. deleteReceiver

   3.4. getActiveAccounts

   3.5. getReceivers

   3.6. updateReceiver

   4. DOCUMENT CHANGELOG

      4.1. Version 1.0.0

      4.2. Version 1.0.5

      4.3. Version 1.0.6

      4.4. Version 1.0.8

      4.5. Version 1.0.9

      4.6. Version 1.0.10

      4.7. Version 2.0.0

      4.8. Version 2.0.1

      4.9 Version 2.0.2

      4.10 Version 2.0.3

      4.11 Version 2.0.4

      4.12 Version 2.0.5

1. Receivers SDK Overview

1.1. What is Receivers SDK?

The P2P Receivers SDK is a module dedicated for receivers management. Receivers contains useful data required in transaction process. Receivers are represented by phone numbers and associated cards. SDK includes functions such as: get, add, update and delete receivers.

1.2. How Receivers SDK works?

Receivers SDK requires Mobile DC SDK as a dependency. It’s required for the Receivers 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, Receivers SDK setup and available methods.

2.1. Basic information

2.1.1 Facade

Facade is entry point to communication with Receivers SDK.

2.1.2 Multiple facade types

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

• receiversCoroutineService for projects which uses Kotlin programming language and Coroutines.
• receiversStdService 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.verestro.com/artifactory/android-release/"
    }
}

2.2.3 SDKs version

Receivers SDK is available in two versions: debug and release. The difference between version is debug allows to use application with debugger connected. 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:receivers:{version}'
}

For debugging purposes:

dependencies{
    implementation "pl.upaid.module:mobiledc:{version}-debug"
    implementation 'com.verestro.module:receivers:debug-{version}'
}

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 Receivers SDK Setup

Available configuration methods:

• ReceiversCoroutineApi.init(configuration: Configuration)
• ReceiversStdApi.init(configuration: Configuration)

2.3.1 Input

Configuration

Configuration

2.3.2 Sample

ReceiversStdApi

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

ReceiversCoroutineApi

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

2.4 Error handling

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

ReceiversSdkException

ValidationError

Specific types of exceptions are described for each method.

3 Receivers service

3.1 addExternalReceiver

Asynchronous. Online.

This method allows user to add external receiver.

3.1.1 Input

AddExternalReceiverData

3.1.2 Output

3.1.2.1 Success

Success callback with AddExternalReceiverResult model.

AddExternalReceiverResult

AddReceiverModel

3.1.2.2 Failure

Failure callback with throwable.

3.1.3 Sample

Standard Callback

fun addExternalReceiver(addExternalReceiverData: AddExternalReceiverData) {
    ReceiversStdApi
        .receiversStdService
        .addExternalReceiver(
            addExternalReceiverData = addExternalReceiverData,
            callback = object : ApiCallback<AddExternalReceiverResult> {
                override fun onSuccess(response: AddExternalReceiverResult) {
                    // handle success
                }
                override fun onFailure(error: Throwable) {
                    // handle error
                }
            }
        )
}

Kotlin Coroutines

suspend fun addExternalReceiver(addExternalReceiverData: AddExternalReceiverData): AddExternalReceiverResult =
    ReceiversCoroutineApi
        .receiversCoroutineService
        .addExternalReceiver(addExternalReceiverData = addExternalReceiverData)

3.2 addWalletReceiver

Asynchronous. Online.

This method allows user to add wallet receiver which are already added to database.

3.2.1 Input

AddWalletReceiverData

3.2.2 Output

3.2.2.1 Success

Success callback with AddWalletReceiverResult model.

AddWalletReceiverResult

AddReceiverModel

3.2.2.2 Failure

Failure callback with throwable.

3.2.3 Sample

Standard Callback

fun addWalletReceiver(addWalletReceiverData: AddWalletReceiverData) {
    ReceiversStdApi
        .receiversStdService
        .addWalletReceiver(
            addWalletReceiverData = addWalletReceiverData,
            callback = object : ApiCallback<AddWalletReceiverResult> {
                override fun onSuccess(response: AddWalletReceiverResult) {
                    // handle success
                }
                override fun onFailure(error: Throwable) {
                    // handle error
                }
            }
        )
}

Kotlin Coroutines

suspend fun addWalletReceiver(addWalletReceiverData: AddWalletReceiverData): AddWalletReceiverResult =
    ReceiversCoroutineApi
        .receiversCoroutineService
        .addWalletReceiver(addWalletReceiverData = addWalletReceiverData)

3.3 deleteReceiver

Asynchronous. Online.

This method allow user to delete a friend.

3.3.1 Input

DeleteReceiverData

3.3.2 Output

3.3.2.1 Success

Success callback with DeleteReceiverResult model.

DeleteReceiverResult

3.3.2.2 Failure

Failure callback with throwable.

3.3.3 Sample

Standard Callback

fun deleteReceiver(deleteReceiverData: DeleteReceiverData) {
    ReceiversStdApi
        .receiversStdService
        .deleteReceiver(
            deleteReceiverData = deleteReceiverData,
            callback = object : ApiCallback<DeleteReceiverResult> {
                override fun onSuccess(response: DeleteReceiverResult) {
                    // handle success
                }
                override fun onFailure(error: Throwable) {
                    // handle error
                }
            }
        )
}

Kotlin Coroutines

suspend fun deleteReceiver(deleteReceiverData: DeleteReceiverData): DeleteReceiverResult =
    ReceiversCoroutineApi
        .receiversCoroutineService
        .deleteReceiver(deleteReceiverData = deleteReceiverData)

3.4 getActiveAccounts

Asynchronous. Online.

Method is used to find users with valid card (not expired, strong verified). Response will contain phone numbers with user and card identifiers. Users without accepted terms of service or without valid card will not be returned in response. If user has multiple cards that match criteria response will contain only user’s default card id.

3.4.1 Input

ActiveAccountsData

3.4.2 Output

3.4.2.1 Success

Success callback with GetActiveAccountsResult model.

GetActiveAccountsResult

ActiveAccountModel

3.4.2.2 Failure

Failure callback with throwable.

Possible types of exceptions:

3.4.3 Sample

Standard Callback

fun getActiveAccounts(getActiveAccountsData: GetActiveAccountsData) {
    ReceiversStdApi
        .receiversStdService
        .getActiveAccounts(
            getActiveAccountsData = getActiveAccountsData,
            callback = object : ApiCallback<GetActiveAccountsResult> {
                override fun onSuccess(response: GetActiveAccountsResult) {
                    // handle success
                }
                override fun onFailure(error: Throwable) {
                    // handle error
                }
            }
        )
}

Kotlin Coroutines

suspend fun getActiveAccounts(getActiveAccountsData: GetActiveAccountsData): GetActiveAccountsResult =
    ReceiversCoroutineApi
        .receiversCoroutineService
        .getActiveAccounts(getActiveAccountsData = getActiveAccountsData)

3.5 getReceivers

Asynchronous. Online.

This method is used to get receivers list.

3.5.1 Input

No input parameters.

3.5.2 Output

3.5.2.1 Success

Success callback with GetReceiversResult model.

GetReceiversResult

ReceiverModel

ReceiverWalletModel

ReceiverType (deprecated)

ReceiverTypeValue

3.5.2.2 Failure

Failure callback with throwable.

3.5.3 Sample

Standard Callback

fun getReceivers() {
    ReceiversStdApi
        .receiversStdService
        .getReceivers(
            callback = object : ApiCallback<GetReceiversResult> {
                override fun onSuccess(response: GetReceiversResult) {
                    // handle success
                }
                override fun onFailure(error: Throwable) {
                    // handle error
                }
            }
        )
}

Kotlin Coroutines

suspend fun getReceivers(): GetReceiversResult =
    ReceiversCoroutineApi
        .receiversCoroutineService
        .getReceivers()

3.6 updateReceiver

Asynchronous. Online.

This method allow user to update receiver. For a receiver of the type WALLET you can update only the field: displayName. For a receiver of the type EXTERNAL you can update the fields: phoneNumber, displayName, firstName, lastName, cardNumber.

3.6.1 Input

UpdateReceiverData

3.5.2 Output

3.5.2.1 Success

Success callback with UpdateReceiverResult model.

UpdateReceiverResult

3.5.2.2 Failure

Failure callback with throwable.

3.5.3 Sample

Standard Callback

fun updateReceiver(updateReceiverData: UpdateReceiverData) {
    ReceiversStdApi
        .receiversStdService
        .updateReceiver(
            updateReceiverData = updateReceiverData,
            callback = object : ApiCallback<UpdateReceiverResult> {
                override fun onSuccess(response: UpdateReceiverResult) {
                    // handle success
                }
                override fun onFailure(error: Throwable) {
                    // handle error
                }
            }
        )
}

Kotlin Coroutines

suspend fun updateReceiver(updateReceiverData: UpdateReceiverData): UpdateReceiverResult =
    ReceiversCoroutineApi
        .receiversCoroutineService
        .updateReceiver(updateReceiverData = updateReceiverData)

4. DOCUMENT CHANGELOG

4.1. Version 1.0.0

• Created.

4.2. Version 1.0.5

• Disables obfuscation and pinning for debug.

4.3 Version 1.0.6

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

4.4 Version 1.0.8

• Updates internal mechanism responsible for date encryption.

4.5 Version 1.0.9

• Added UNKNOWN type to ReceiverType enum model.
• Marked receiverType field in ReceiverWalletModel model with @Deprecated.
• Added corresponding value class field receiverTypeValue for deprecated field.

4.6 Version 1.0.10

• Improved SDKs deploying.

4.7 Version 2.0.0

• Added missing phoneNumber field in ReceiverWalletModel

4.8 Version 2.0.1

• Internal changes have been introduced to improve build process.

4.9 Version 2.0.2

• Update koin to version 4.0.4
• Update java to 21
• Update compile and target android version

4.10 Version 2.0.3

• Internal changes improving SDK delivery process.

4.11 Version 2.0.4

• Added receiver field to AddExternalReceiverResult and AddWalletReceiverResult models.

4.12 Version 2.0.5

• Internal. Updates build utilities.