Receivers SDK

Version. 1.0.0

---

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

---

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.upaid.pl/artifactory/libs-release-local/"
	}
}

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.
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:receivers:{version}'
}

For debugging purposes:

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

Available configuration methods:

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

2.3.1 Input

Configuration

Parameter	Type	Description
configuration	Configuration	Configuration model

Configuration

Parameter	Type	Description
productNam	String	API product name
url	String	API hostname URL
certificateHashes	List<String>	API hostname Pin SHA256

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

Exception	Parameters	Description
CryptographyError		Cryptography error.
InternalServerError		Internal application error.
ProductNotFound		Product not found based on sent header: Product-Name.
RequestCancelled		Request was canceled.
TechnicalException	message:String?	Technical exception.
NoSessionException		Session expired.
ValidationException	validationErrors: List<ValidationError>	List of validation errors.
UnknownErrorStatus	status: String	An unknown error occurred.
HttpApiException	code:Int, message:String?	HTTP API exception.

ValidationError

Parameter	Type	Description
fieldName	String	Name of field which not passed validation.
errorMessages	List<String>	List of error messages.

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

Parameter	Type	Description
phoneNumber	String	Phone number.
displayName	String	Display name.
firstName	String?	Optional. First name.
lastName	String?	Optional. Last name.
cardNumber	CharArray?	Receiver card number.

3.1.2 Output

3.1.2.1 Success

Success callback with AddExternalReceiverResult model. AddExternalReceiverResult is empty class.

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

Parameter	Type	Description
phoneNumber	String	Phone number.
displayName	String	Display name.
firstName	String?	Optional. First name.
lastName	String?	Optional. Last name.
dcReceiverId	Int	User identifier.

3.2.2 Output

3.2.2.1 Success

Success callback with AddWalletReceiverResult model.

AddWalletReceiverResult

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

Parameter	Type	Description
receiverId	Long	Receiver identifier.

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

Parameter	Type	Description
phoneNumbers	Set	Phone numbers each of which identifiers one user. Size must be between 1 and 100 inclusive.

3.4.2 Output

3.4.2.1 Success

Success callback with GetActiveAccountsResult model.

GetActiveAccountsResult

Parameter	Type	Description
activeAccounts	Set	Set of active accounts.

ActiveAccountModel

Parameter	Type	Description
phoneNumber	String	Phone number.
userId	Long	User identifier.
cardId	Long	Card identifier.

3.4.2.2 Failure

Failure callback with throwable.

Possible types of exceptions:

Exception	Description
InvalidPhoneNumbers	Phone numbers has incorrect format.

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

Parameter	Type	Description
receivers	List<ReceiverModel>	List of receivers.

ReceiverModel

Parameter	Type	Description
firstName	String	First name.
lastName	String	Last name.
phoneNumber	String	Phone number.
displayName	String	Display name.
receiverWalletEntries	List<ReceiverWalletModel>	Receiver wallet entries list.

ReceiverWalletModel

Parameter	Type	Description
receiverId	Long	Receiver identifier.
receiverType	ReceiverType	One of: [WALLET], [EXTERNAL].
lastFourDigits	String?	Conditional. Card last 4 digits. Empty for [WALLET] type.
bin	String?	Card bin. Conditional. Card bin. Empty for [WALLET] type.

ReceiverType

Type	Description
WALLET	Wallet card receiver.
EXTERNAL	External card receiver.

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

Parameter	Type	Description
receiverId	Long	Receiver identifier.
displayName	String?	Optional. Display name.
phoneNumber	String?	Optional. Phone number.
cardNumber	CharArray?	Optional. Card number.
cardExpirationDate	CharArray?	Optional. Card expiration date.

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.